Skip to content

Commit

Permalink
(#3) Added Contribution Guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
lucasstarsz committed Apr 19, 2021
1 parent 718b078 commit bf9acae
Show file tree
Hide file tree
Showing 9 changed files with 279 additions and 1 deletion.
24 changes: 24 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<div align="center">

# Contributing to FastJ
</div>

🎉 To begin, thank you for considering contributing to FastJ! 🎉

This project has been growing well on its own, but with the addition of new features and enhancements we're going to need to work together as much as possible. Without you all, this project really wouldn't be possible. Once more, thank you! ^^

## Contributing Guidelines

### Contributing Code
For contributing code, please follow along with the guidelines outlined [here][Contributing-Code].

### Contributing Documentation
For contributing api/website documentation, please follow along with the guidelines outlined [here][Contributing-Documentation].

### Opening an Issue
For guidelines on opening an issue, please follow along with the guidelines outlined [here][Opening-An-Issue].


[Contributing-Code]: /.github/contributing/contributing-code.md "Contributing Code"
[Contributing-Documentation]: /.github/contributing/contributing-documentation.md "Contributing Documentation"
[Opening-An-Issue]: /.github/contributing/opening-issues.md "Opening Issues"
43 changes: 43 additions & 0 deletions .github/ISSUE_TEMPLATE/bug-report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
name: Bug Report
about: Something not working? Let us know!
title: "[Bug]"
labels: bug
assignees: ''

---

## Platform Info
_Place an `x` in the box(es)_ `[x]` _that the issue occurs on (or that you've found the issue on)_
- [ ] Windows
- Version: _e.g. Windows 10 20H2_
- [ ] Mac OS
- Version: _e.g. High Sierra 10.13.6_
- [ ] Linux
- Distro: _e.g Linux Mint_
- Version: _e.g. 20.1_


## Describe the Bug
_A clear and concise description of what the bug is._


## Expected Behavior
_A clear and concise description of what you expected to happen._


## How to Reproduce the Bug
_Steps to reproduce the behavior:_
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error


## Media Aid
_If applicable, add screenshots/GIFs/videos to help explain your problem._


## Additional context
_Additional context not provided above._

16 changes: 16 additions & 0 deletions .github/ISSUE_TEMPLATE/documentation-fix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
name: Documentation Fix
about: Incorrect docs/wiki? Let us know!
title: "[Documentation]"
labels: documentation
assignees: lucasstarsz

---

## The Outdated/Incorrect Information
_Describe what and where in the documentation/wiki is incorrect, as clearly and concisely as you can._


## Suggestions
_If you have any thoughts on what the content can be changed to, please let us know. Links to outside sources of information are incredibly helpful._

24 changes: 24 additions & 0 deletions .github/ISSUE_TEMPLATE/feature-request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
name: Feature Request
about: Think we're missing something? We're happy to hear you out.
title: "[Feature Request]"
labels: enhancement
assignees: ''

---

## Is your feature request related to a problem? Please describe.
_A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]_


## What should the solution be like?
_A clear and concise description of what you want to happen._


## Alternatives?
_A clear and concise description of any alternative solutions or features you've considered. if you want to go into detail about why something else does it better, now's your chance._


## Additional Context
_Add any other context or screenshots about the feature request here._

88 changes: 88 additions & 0 deletions .github/contributing/contributing-code.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Contributing Code

I've no clue how I managed to spend 3 years learning software development without using a proper IDE for developing larger projects. From the first days of FastJ I quickly realized I needed a rule set for how my code should be written.

- [IDE](#IDE)
- [Imports](#Imports)
- [General Code Style](#General-Code-Style)
- [Column Limit](#Column-Limit)
- [Block Indentation](#Block-Indentation)
- [Wildcard Imports](#Wildcard-Imports)
- [Annotations](#Annotations)
- [Constant Names](#Constant-Names)
- [Type Variable Names](#Type-Variable-Names)
- [Camel Case Defined](#Camel-Case-Defined)
- [API Documentation](#API-Documentation)
- [Be Clear](#Be-Clear)
- [Be Thoroughly Concise](#Be-Thoroughly-Concise)
- [Website Documentation](#Website-Documentation)


## IDE
I absolutely prefer that you use [IntelliJ IDEA][IntelliJ-Link] while developing FastJ, but [Eclipse][Eclipse-Link] is fairly capable of keeping up as well. VSCode, _I'm personally not a fan of it_ -- it's given me a lot of trouble for Java development in the past, and I don't plan on using it for bigger Java projects any time soon. However, as long as you can get the job done in whatever you're comfortable with you're free to use it.


## Imports
There's a specific order your imports should follow:
```java
import io.github.lucasstarsz.fastj.engine.*;
import io.github.lucasstarsz.fastj.math.*;
import io.github.lucasstarsz.fastj.graphics.*;

import io.github.lucasstarsz.fastj.systems.*;

import java.*;
import javax.*;

import others

import static others

public class ... {
}
```

A bit excessive, but for me (the owner of the repo, hi) it provides the most optimal reading -- not that anyone else reads them.


## General Code Style
For the most part, you can follow along with this codebase using [Google's Java Style Guide][Style-Guide-Link]. It covers most of the bases, with exceptions as follows:

### Column Limit
Other than JUnit test asserts, Markdown, and Git commits -- I don't care about the exact style of these in terms of this, Lines should hard-wrap at the **120-character** limit, and not at 100.

### Block Indentation
Indentation must be **4 spaces**. Indentations for method chaining must be **8 spaces**.

### Wildcard Imports
Wildcard imports are only allowed if the file's import count from that specific package is more than 10, with the same situation being applied to static imports more than 7.

### Annotations
For the sake of my own sanity, until further notice I will not allow the exception regarding single parameterless annotations for methods. However:
- Single parameterless annotations for a field are always welcome to be on the same line.
- Otherwise, annotations must always be on a line of its own (one annotation per line).

### Constant Names
All `static final` values should be `UpperCamelCase`, rather than `CONSTANT_CASE`. Of course, this does not change the use of `CONSTANT_CASE` for enum values.
- Furthermore, mutable object constants (e.g. `static final Set<Integer>`) should _also_ use `UpperCamelCase`.

### Type Variable Names
I have no preference on how these are named.

### Camel Case Defined
I will most definitely end up changing this style a lot over time, but do note I prefer `newCustomerID` to `newCustomerId`.


## Documentation
Please see [Contributing Documentation][Contributing-Documentation].

## Unit Tests
Unit Tests are an integral part of the project. No part of the project should be left untested -- I am currently working hard to give this project as much unit testing as possible.

New code added to the repository should **always** be accompanied by unit testing. There is no exception to this -- PRs without unit tests for new methods added (of course, there are exceptions to this rule) will **not** be merged.


[IntelliJ-Link]: https://www.jetbrains.com/idea/ "IntelliJ IDEA IDE"
[Eclipse-Link]: https://www.eclipse.org/downloads/ "Eclipse IDE"
[Style-Guide-Link]: https://google.github.io/styleguide/javaguide.html "Google Java Style Guide"
[Contributing-Documentation]: contributing-documentation.md "Contributing Documentation"
28 changes: 28 additions & 0 deletions .github/contributing/contributing-documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Documentation

Documentation is incredibly important to any open-source project. Without it, it becomes much harder to actually tell what's going on without at least using examples. As such, I heavily enforce that it is well-written. (Obviously, [contributing code][Contributing-Code] and contributing documentation go hand in hand.)

- [API Documentation](#API-Documentation)
- [Be Clear](#Be-Clear)
- [Be Thoroughly Concise](#Be-Thoroughly-Concise)
- [Website Documentation](#Website-Documentation)


## API Documentation
API Documentation and source code go hand-in-hand. PRs will **not** go through until accompanying documentation is satisfactory to me.

### Be Clear
Clarity is an integral part of documentation, without a doubt. Documentation should make it easy for someone with reading, math, and comprehension skills to understand what a method does, and at a minimum how to use it with a certain result in mine.

### Be Thoroughly Concise
In the case of API Documentation it makes more sense to be a bit more verbose with describing how certain methods work, and that's _fine_. If you need to explain the different nuances of why your specific implementation of a rotation method acts the way it does, go right ahead!

However, it is not acceptable to be _too_ verbose, especially for parts of the code that don't need it. For example, you don't need a 4-paragraph essay for a getter method (unless that method does some wacky side effects that you just _have_ to explain).


## Website Documentation
I'm not entirely sure how this should be handled just yet -- for now, please [open an issue using the documentation template][Issues-Link], make your request, and be prepared for a bit of jank.


[Contributing-Code]: contributing-code.md
[Issues-Link]: https://github.com/lucasstarsz/FastJ/issues/new "Open an issue on FastJ"
30 changes: 30 additions & 0 deletions .github/contributing/opening-issues.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Opening Issues

Issues are always a common way of outlining where improvements to a project can be made. They give developers tasks to complete, and oftentimes end up drastically improving the quality-of-life of the repository for everyone.

When opening an issue, please be sure to follow the provided issue templates. Be sure to follow the guidelines outlined here.

- [Be Clear and Comprehensive](#Be-Clear-and-Comprehensive)
- [Amicability Gets Results](#Amicability-Gets-Results)
- [What if my issue doesn't fit into a template?](#What-if-my-issue-doesn't-fit-into-a-template?)
- [Request/Create a new template](#Request/Create-a-new-template)
- [Create an issue without a template](#Create-an-issue-without-a-template)

## Be Clear and Comprehensive
format your issue in an easy-to-comprehend way. We're all human here, nothing's perfect -- but that doesn't mean you should talk in caveman speak because "few word work well".

~~We're Java developers, expect verbosity~~ Please provide all the relevant details right away or immediately on request.

## Amicability Gets Results
In short, **be nice**. If you can hold a mature, productive conversation with an understanding tone and be receptive to feedback, you'll do just fine! I expect all sides of a conversation to be professional -- starting drama is absolutely childish, embarrassing, and will likely result in you being temporarily or permanently **banned** from the project.

## What if my issue doesn't fit into a template?
If your issue does not fit into any of the provided templates, you can do one of the following:

### Request/Create a new template
Sometimes there are topics so common that they can and should be turned into a separate template. That's perfectly ok -- the needs of a repository are not simply constrained to whatever measures are currently in place.

### Create an issue without a template
Other times, the question is too specific to not warrant a separate template, and it doesn't fit into the templates either. That's ok too! Once again, the needs of a repository are not constrained to whatever measures are currently in place.

If you plan on doing this, please be sure to format your issue in an easily-understandable format. You can even use templates from other repositories -- nothing wrong with stealing ideas. As long as you provide the information needed, things will usually work out.
21 changes: 21 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# PR Title

## Additions
_In a list, briefly describe each new feature you added._
- Added functionality to [...]


## Bug Fixes
_In a list, briefly describe each bug you fixed. A link to the issue/pr where this bug is referenced is highly recommended._
- (#issue_number) Fixed issue where [...]


## Breaking Changes
_In a list, briefly describe each change you made that breaks backward compatibility._
- Renamed method `z` to `abxy`


## Other Changes
_Changes to the source code which do not fit in the above categories._
- Modified method so that [...]

6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,10 @@ _Having trouble using `gradlew`? Read [this][Terminals Are Different]._

From there, explore the [example code][FastJ-Example], play around with it, and read the documentation to get a better understanding of FastJ.

## Contributing to FastJ
Plan on contributing to the repository? Great! Be sure to read over the [contribution guidelines][Contributing-Guidelines].

## Building FastJ
### Building FastJ
Building FastJ is a generally simple task. You just need to follow these steps:

- Clone the FastJ repository.
Expand Down Expand Up @@ -131,4 +133,6 @@ This repository is licensed under the [MIT License][MIT-License].

[FastJ-Example]: src/example "FastJ: Example Game"

[Contributing-Guidelines]: /.github/CONTRIBUTING.md "Contributing to FastJ"

[Terminals Are Different]: https://gist.github.com/lucasstarsz/9bbc306f8655b916367d557043e498ad "Terminals Access Files Differently"

0 comments on commit bf9acae

Please sign in to comment.