Contributing

Philosophy

In LSML all work is done towards specific issues in the LSML issue tracker. If there is something you want to fix or improve you need to first create an issue on the issue tracker. It may already be worked on by some one else. This is so that work can be tracked and that I can make patch notes that include all changes easily.

In general I'm happy to accept patches that are well written, have accompanying unit tests and solve some issue on the issue tracker. Patches must be provided under GPLv3 and come with class level and public method JavaDocs. Each PR must affirmatively state that you hand over copyright over the changes made in the PR to LSML so that the license of LSML remains intact.

Before you start

If you haven't already done so, please follow the steps in Getting Started and check out the Style Guide.

Work flow

LSML uses a pull-request based work flow. The general work flow is something like this:

1. Pick an issue to work on in the LSML issue tracker. If there doesn't exist a suitable issue create a new one and wait for it to be approved. Commits without an issue referenced will be rejected.
2. Create or sync your fork's develop branch to upstream.
3. Assign the issue to yourself or let a contributor know that you'd like to work on it. Ask a contributor for input on the problem, they may be able to provide useful insights.
4. Optionally (highly recommended) create a feature branch for your fix. This makes rebasing later easier if needed.
5. Make your changes.
6. Make sure that everything uses UTF-8 encoding.
7. Check for spelling and proper grammar in comments etc.
8. Make sure that gradle check passes. You can use ./gradlew spotlessJavaApply to fix any formatting errors.
9. Create a pull request and mention the issue that the PR is fixing and other necessary info in the PR comment.
10. In the event that the develop branch changed in a way to create a collision with your PR you may need to resolve those. Please prefer to rebase upon develop in that case.

Pre-Pull-Request-Checklist

• Do all new files include the GPLv3 preamble? (copy paste from existing files)
• Do all new classes have a class level JavaDoc annotated with author and purpose of the class?
• Do all new non-trivial methods have a JavaDoc describing their arguments and method behaviour?
• Do all classes and methods which have had changes in their behaviour had their JavaDoc updated?
• Are there unit tests that cover all new or changed behaviours (except UI)?
• Are all files encoded using UTF-8?
• Does gradle check complete without errors?
• Does the code compile cleanly without warnings (except @Deprecated)?
• Does the code adhere to the SOLID principles.
• Does the code actually fix the issue?
• Does the patch apply cleanly to the HEAD of develop on the main repository?
• Does all commit messages reference an issue on the issue tracker?