-
Notifications
You must be signed in to change notification settings - Fork 102
Contribution
The JOML team is always happy about contributions from other GitHub users in the form of bug fixes, new functionality/enhancements and test cases.
First we request you to make an own fork of JOML using your own GitHub user. There, you can make any changes you like. After you are content with your changes, you can use GitHub's "Pull Request" feature to have your changes being integrated into the JOML repository.
Code you want to contribute MUST build with Maven 3 under a JDK8+ and succeed without any errors and warnings in any build stages (compile, javadoc, packaging). This specifically includes JDK8 JavaDoc's doclint to not output any errors or warnings.
Every class, method and constructor MUST have JavaDocs that express the intent of the class and the semantics of the method. All method parameters MUST be described with their possible value ranges. If a method throws an exception of any kind, that exception MUST be documented using the @throws JavaDoc statement.
If a method returns a non-void result, this MUST be documented using the @return statement.
Additional JavaDoc comments that express possible limitations of the method or hints to better suited methods for certain sequences of calls with certain arguments SHOULD be added.
Additionally, code you contribute SHOULD be tested using unit tests.
JOML uses the JUnit test framework for all of its unit tests. In order to remain Java 1.4 compatible, it uses the last version of JUnit 3, which as of this date is 3.8.2. Most IDEs, such as Eclipse, have built-in support for JUnit to let you develop unit tests and execute them from within the IDE.
Make sure that all unit tests pass before committing them to the git branch which you use for the Pull Request.
Also when creating new test classes and test methods, make sure to follow Maven's and JUnit's naming conventions:
- Test classes must either start or end with Test
- Test classes must extend junit.framework.TestCase
- Methods in a test class must begin with test
JOML's commit messages follow the "Good Commit Messages" style explained in:
- https://github.com/erlang/otp/wiki/writing-good-commit-messages
- https://chris.beams.io/posts/git-commit/
Please first have a look at JOML's git commit history and follow the style used there.
Also, when finally issuing the pull request, refrain from having multiple commits when they rework or fix the same code you committed earlier as part of the pull request. Since your commits are not yet integrated into JOML's master, you can freely squash, reword and rebase your own commits. It is not necessary to see buggy commits and fixes of your own code as part of the pull request when later merging into JOML's master. When you added a single feature in your pull request, a good way is to simply squash all commits into a single commit with a good commit message.
Commits will not be accepted that merely reformat the sources (Java sources or JavaDocs). So, please do not use an auto formatter provided by your IDE. Every commit that you contribute must make the essence of the change visible.