mirror of https://github.com/shred/acme4j
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# Contributing to _acme4j_
|
|
|
|
Thank you for taking your time to contribute!
|
|
|
|
## Acceptance Criteria
|
|
|
|
These criteria must be met for a successful pull request:
|
|
|
|
* Follow the [Style Guide](#style-guide).
|
|
* If you add code, remember to add [unit tests](#unit-tests) that test your code.
|
|
* All unit tests must run successfully.
|
|
* Integration tests should run successfully, unless there is a good reason (e.g. waiting for a pending change in Pebble).
|
|
* Your commits follow the [git commit](#git-commits) guide.
|
|
* You accept that your code is distributed under the terms of [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).
|
|
* You confirm that you did not use AI based code generators like GitHub Copilot for your contribution.
|
|
|
|
## Style Guide
|
|
|
|
Our style guide bases on [Oracle's Code conventions for the Java Programming Language](http://www.oracle.com/technetwork/java/codeconventions-150003.pdf). These additional rules apply:
|
|
|
|
* Indentation is 4 spaces. Do not use tabs!
|
|
* Remove trailing spaces.
|
|
* Line length is 90 characters. You may exceed this length by a few characters if it is easier to read than a wrapped line.
|
|
* `if`, `for` and `while` statements always use blocks, even for a single statement.
|
|
* All types and methods must have a descriptive JavaDoc, except of `@Override` annotated methods. For plain getter and setter methods, `@param` and `@return` can be omitted.
|
|
|
|
## Unit Tests
|
|
|
|
More than 80% of the code is covered by unit tests, and we would like to keep it that way.
|
|
|
|
* Main functionalities must be covered by unit tests.
|
|
* Corner cases should be covered by unit tests.
|
|
* Common exception handling does not need to be tested.
|
|
* No tests are required for code that is not expected to be executed (e.g. `UnsupportedEncodingException` when handling utf-8, or the empty private default constructor of a utility class).
|
|
* Unit tests should not depend on external resources, as they might be temporarily unavailable at runtime.
|
|
|
|
There are no unit tests required for the `acme4j-example` and `acme4j-it` modules.
|
|
|
|
## git Commits
|
|
|
|
Good programming does not end with a clean source code, but should have pretty commits as well.
|
|
|
|
* Always put separate concerns into separate commits.
|
|
* If you have interim commits in your history, squash them with an interactive rebase before sending the pull request.
|
|
* Use present tense and imperative mood in commit messages ("fix bug #1234", not "fixed bug #1234").
|
|
* Always give meaningful commit messages (not just "bugfix").
|
|
* The commit message must be concise and should not exceed 50 characters. Further explanations may follow in subsequent lines, with an empty line as separator.
|
|
* Commits must compile and must not break unit tests.
|
|
* Do not commit IDE generated files and directories (like `.project` or `.idea`).
|