This project welcomes any contributions and enforces the values of openness, usability, correctness, clean code, and rigorous testing through the defined processes.
You can contribute to this project by contributing to issues, discussions, and proposing code changes.
English is the mandated language for all communication and contributions.
This project has adopted a Code of Conduct and it will be enforced in any communication.
You can report bugs, create feature requests, propose enhancements, or raise questions on the issue page.
Choose and adhere to the provided templates and be as precise as possible to enable an easy evaluation of the issue. If you're interested in resolving your issue yourself, take a look at the possibility of creating code contributions](#propose-a-code-change).
Before creating any issue, please look up already closed or open issues!
A bug report should include details regarding any unforeseen or malfunctioning aspects of SAPL (please verify to the best of your ability that this pertains specifically to a dedicated issue with SAPL). Once the bug is reported, any project contributor can assess, engage in discussions, and contribute additional information to the corresponding issue.
After a maintainer evaluates the bug, he or she will add a tag to categorize the bug and describe his examination result and the next steps that need to be taken.
Do not post bugs with security implications publicly and follow this.
An enhancement request is any kind of enhancement. It can be code, documentation, or anything else maintained in the repository. Once the request is posted, any project contributor can evaluate it, participate in discussions, and contribute additional information to the issue.
A decision can be made by consensus, ensuring stability and alignment with the direction of the project and module.
A feature request is a request to add a new feature to the project. It should provide a new, unknown capability that is not already provided by this project. Once the request is posted, any project member can evaluate it, participate in discussions, and contribute additional information to the corresponding issue.
The decision to add and support a new feature is made by the BDFL.
A question is an issue for requesting support on a specific topic, that the requestor can not answer on its own. Anyone is welcome to help resolve this issue, and the requestor or a maintainer will close this issue.
If you find any security vulnerability, please follow the process described here.
With a code change, you can actively improve the product itself. To ensure a high quality please follow the following guidelines and the enforced processes.
Before writing code you might want to create an issue to get feedback before implementing.
TODO - We need to provide and formalize more guidelines for styling and coding. No automatic tool will resolve all requirements.
All code contributions are expected to be reviewed and merged into the master branch via pull requests.
To create a pull request for your code, you need to use a fork (except you are a
maintainer).
Look up here how to create a fork and here
how to create a pull request.
All commits in your code contribution need to be signed. Your pull request will not be merged if commits are not signed. You can find more information on signing commits here.
Apply the default provided template to your pull request!
Once all required pipelines execute, tests pass and the changes are approved, the pull request will be merged by a maintainer.
Maintaining a consistent code style is crucial for our project's readability.
We enforce these standards automatically using formatter-maven-plugin based on Eclipse Code Formatter configured in the formatter.xml file, which checks and ensures adherence to our guidelines.
Beyond the automatic enforcing of formatting by tools, we have style preferences that are described as the following rules.
- Use
varinstead of explicitly specifying the type whenever possible. - Avoid starting interfaces with the letter
I, e.g.,IFileProvider. - Avoid using the prefix
Myfor variables, methods, and classes. - Use the default scope for test classes and methods.
- End the names of test classes with
Tests. - Follow the pattern
whenSOMETHINGthenSOMETHING-ELSEfor naming test methods. - Avoid using
@SuppressWarning, except with explicit permission from maintainers. - If a file happens to differ in style from the guidelines, the existing style in that file takes precedence.
- Use Lombok annotations.
- Use the @Slf4j annotation for logging.
We use SonarCloud with SpotBugs and sb-contrib for static analysis of your code.
Once you created a pull request, test pipelines will run that include static code analysis. Results will be posted to your pull request and can be found on our project site on SonarCloud.
We strive to keep our code clean, so pull requests can only be merged if they do not introduce any new bugs or security vulnerabilities. Please resolve all issues detected by the SonarCloud analysis. If you think issues include false positive results or cannot be fixed, please add a comment to your pull request accordingly.
To avoid issues on SonarCloud, you can use SonarLint and the
SpotBugs plugin in your IDE to keep your code clean. Sb-contrib
can be added to the SpotBugs plugin and you can use our exclude filter file in your SpotBugs plugin configuration to exclude certain
source files and rules from your local SpotBugs analysis.
Please note that not all issues on SonarCloud can be avoided by using SonarLint due to technical limitations of
SonarLint.
We strive to achieve a test coverage of at least 95%. Use the integrated tools of your IDE or our SonarCloud integration to check missing tests for branches/lines of code.