mirror of
https://github.com/ellmau/adf-obdd.git
synced 2025-12-19 09:29:36 +01:00
82 lines
5.0 KiB
Markdown
82 lines
5.0 KiB
Markdown
# How to contribute
|
|
|
|
We are really glad you are reading this, because we need developers to help this project come to fruition.
|
|
|
|
## Folder structure
|
|
|
|
The project is divided into two different cargo-projects under one rust-workspace.
|
|
|
|
* `lib` is where the library is located
|
|
* `bin` is where the binary is located
|
|
* `res` is a folder, where different resources for testing and benchmarks are located (usually managed through `git submodules`
|
|
|
|
Easy first tasks for contributing will be to integrate implemented features from the library, which are not represented in the binary.
|
|
|
|
## Testing
|
|
|
|
Please make sure to test your additional features.
|
|
|
|
### Unit-Testing
|
|
Unit tests are done for each module by an associated `test` sub-module.
|
|
It can either be directly in the `<module.rs>` file or in an additional `test` sub-directory.
|
|
Please try to generate meaningful tests, with sane data. It would be most appreciated if there are some real-world flavours.
|
|
Add `quickcheck` tests whenever it is applicable.
|
|
|
|
### Integration-Testing
|
|
Integration testing is done in the related `tests` directory on the top-level of the crate.
|
|
|
|
## Submitting changes
|
|
|
|
Please send a [GitHub Pull Request to ellmau/adf-obdd](https://github.com/ellmau/adf-obdd/pull/new/main) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). When you send a pull request be sure to check open and claimed tickets first. We can always use more test coverage. Please follow our coding conventions (below).
|
|
|
|
Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should have a commit-paragraph and/or a related and appropriately mentioned [issue](https://github.com/ellmau/adf-obdd/issues).
|
|
|
|
Before creating the pull request be sure to check if
|
|
- [ ] all already existing tests are passing,
|
|
- [ ] new tests are passing,
|
|
- [ ] `clippy` does not complain about your code, and
|
|
- [ ] the code has been formatted with `rustfmt`.
|
|
|
|
If you have done changes to any other folder than `lib` and `bin`, choose the `repository`-label for the pull request.
|
|
|
|
We are monitoring our code-coverage through [coveralls](https://coveralls.io), so it is expected that additional changes do not reduce the test-coverage significantly.
|
|
Keep in mind, that the current coverage-tools have some issues with rust-code and sometimes report lower code-coverage than it is in reality.
|
|
|
|
Finally, if you create a pull request for work in progress, please mark this by creating a draft pull request.
|
|
|
|
### Commit messages
|
|
|
|
To create uniform and easy to read commit messages, please stick to the following conventions:
|
|
|
|
* Capitalise the first word
|
|
* Do not end the message title in punctuation
|
|
* Use imperative mood
|
|
* The message title shall not exceed 50 characters
|
|
* Be direct, do not use filler words (e.g. "I think", "maybe", "kind of", ...)
|
|
* Use [Github Issue/PR Keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) in the message description part where applicable
|
|
* Link to other related pull requests, issues, commits, comments, ... to have a concise representation of the context in the message description
|
|
* Sign your commit whenever possible
|
|
|
|
A commit message is usually consisting of the first line, the so-called `message-title`, one free line, and the `message description` which may take the following lines.
|
|
|
|
## Coding conventions
|
|
|
|
Start reading our code and you'll get the hang of it.
|
|
|
|
* We use `rustfmt` as code-convention. (you can use whatever styles you like, just let `rustfmt` format the code before you commit)
|
|
* We try to reduce redundancies in enumeration-variant names.
|
|
* We try to use the `where` clause over embedded clauses for better readability.
|
|
* We follow the code-conventions and naming-conventions of the current Rust version.
|
|
* We write `clippy`-conform code, so follow `clippy` suggestions where applicable. If you write a compiler-exception (i.e. `#[allow(...)]`) describe your decision to do so in a meaningful comment. We advise to mark this code-segment in the pull-request as a code-comment too.
|
|
* `rustdoc` is obligatory for crate-exposed structures (e.g. `enum`, `struct`, `fn`, ...).
|
|
* `rustdoc` is nice to have for non-crate-exposed structures.
|
|
* We try to have one atomic commit for refactoring work done.
|
|
* Error-handling shall follow these guidelines:
|
|
* `panic!` (and `expect()`, `assert!`, `unreachable!` etc.) is fine for situations that should not occur, e.g., if there is some invariant that makes the situation impossible, or where graceful recovery is impossible, but not otherwise, and
|
|
* `unwrap()` should (almost?) always be `expect()` instead (exceptions are in tests).
|
|
* Use `unsafe` code only if :
|
|
* It is checked that there is no safe way to achieve the functionality,
|
|
* it has been discussed with the core development team in detail,
|
|
* the unsafe part is tested even more carefully than the rest of the code, and
|
|
* you will persistently insist on a detailed code-review
|