-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
718b078
commit bf9acae
Showing
9 changed files
with
279 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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._ | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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._ | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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._ | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 [...] | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters