Contributing

Thank you for your interest in contributing to the rustic ecosystem!

We appreciate your help in making this project better.

Code of Conduct
How to Contribute
Development Setup
License

Code of Conduct

Please review and abide by the general Rust Community Code of Conduct when contributing to this project. In the future, we might create our own Code of Conduct and supplement it at this location.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on GitHub and provide as much detail as possible. Include steps to reproduce the bug and the expected behavior.

Issue and Pull Request labels

Our Issues and Pull Request labels follow the official Rust style:

A - Area
C - Category
D - Diagnostic
E - Call for participation
F - Feature
I - Issue e.g. I-crash
M - Meta
O - Operating systems
P - priorities e.g. P-{low, medium, high, critical}
PG - Project Group
perf - Performance
S - Status e.g. S-{blocked, experimental, inactive}
T - Team relevancy
WG - Working group

Suggesting Enhancements

If you have an idea for an enhancement or a new feature, we’d love to hear it! Open an issue on GitHub and describe your suggestion in detail.

Code Style and Formatting

We follow the Rust community’s best practices for code style and formatting. Before submitting code changes, please ensure your code adheres to these guidelines:

Use rustfmt to format your code. You can run it with the following command:
```
cargo fmt --all
```
Use dprint to format text in markdown, toml, and json. You can install it with cargo install dprint/scoop install dprint and run it with the following command in the repository root:
```
dprint fmt
```
Use Clippy — a collection of lints to catch common mistakes. If you haven’t installed your Rust toolchain with rustup, please install Clippy first. Then run Clippy with the following command in the crate root:
```
cargo clippy --all -- -D warnings
```
Write clear and concise code with meaningful, self-describing variable and function names. This tells the reader what the code does.
Write clear and consise comments to tell the reader why you chose to implement it that way and which problem it solves.

Testing

We value code quality and maintainability. If you are adding new features or making changes, please include relevant unit tests. Run the test suite with:

cargo test --workspace

or check the testing guide for more information which tools we provide for making developing rustic easier.

Make sure all tests pass before submitting your changes. PRs containing tests have a much higher probability of getting merged (fast).

We expect PRs especially ones that introduce new features to contain tests for the new code.

Besides that, we welcome PRs which increase the general test coverage of the project. You can check the testing guide for more information.

We appreciate tests in every form: be it unit, doc or integration tests (chose depending on your use case).

If you want to implement some fuzzing or benchmarking, that is also highly appreciated.

Submitting Pull Requests

To contribute code changes, follow these steps:

Fork the repository.

Create a new branch with a descriptive name:

git checkout -b feature/your-feature-name

Check and Commit your changes:

just pre-commit
git commit -m "Add your meaningful commit message here"

Push your branch to your forked repository:

git push origin feature/your-feature-name

Open a Pull Request (PR) to our repository. Please include a detailed description of the changes and reference any related issues.

`Release early and often!` also applies to pull requests

Consider drafting a Pull request early in the development process, so we can follow your progress and can give early feedback.

Once your PR is submitted, it will be reviewed by the maintainers. We may suggest changes or ask for clarifications before merging.

IMPORTANT NOTE

Please don’t force push commits in your branch, in order to keep commit history and make it easier for us to see changes between reviews.

Make sure to Allow edits of maintainers (under the text box) in the PR so people can actually collaborate on things or fix smaller issues themselves.

Rebasing and other workflows

(taken from: openage on rebasing)

Rebasing is ‘moving’ your commits to a different parent commit.

In other words: Cut off your branch from its tree, and attach it somewhere else.

There’s two main applications:

If you based your work on a older main (so old that stuff can’t be automatically merged), you can rebase to move your commits to the current upstream main:

# update the upstream remote to receive new commits
git fetch upstream

# be on your feature branch (you probably are)
git checkout my-awesome-feature

# make backup (you never know, you know?)
git branch my-awesome-feature-backup

# rebase: put your commits on top of upstream's main
git rebase -m upstream/main

If you want to fix an older commit of yours, or merge several commits into a single one (squash them), rebase interactively. We don’t want to have a commit history like this:
- add stuff
- fix typo in stuff
- fix compilation
- change stuff a bit
- and so on…

`rebase` in practice

git log --graph --oneline shows your commit history as graph. To make some changes in that graph, you do an interactive rebase:

git rebase -i -m upstream/main

With this command, your new “base” is upstream/main and you can then change any of your branch’s commits.

-i will open an interactive editor where you can choose actions for each individual commit:

re-order commits
drop commits by deleting their line
squash/fixup (“meld”) your commits
reword a commit message
stop rebasing at a commit to edit (--amend) it manually

Just follow the messages on screen.

Changing commits with `amend` and `fixup`

There’s also git commit --amend which is a “mini-rebase” that modifies just the last commit with your current changes by git add. It just skips the creation of a new commit and instead melds the changes into the last one you made.

If you want to update a single commit in the range [upstream/main, current HEAD] which is not the last commit:

edit stuff you wanna change in some previous commit
git add changed_stuff
git commit --fixup $hash_of_commit_to_be_fixed
git rebase --autosquash -i -m upstream/main

Pushing changes

After you have rebased stuff (“rewritten history”) that had already been pushed, git will not accept your pushes because they’re not simple fast-forwards:

The commit contents and the parent commit have changed as you updated the commit, therefore the commit hash changed, too.
- If somebody used those commits, they will keep a copy and have a hard time updating to your updated version (because they “use” the old hashes).
- Update your pull request branch with your re-written history!
force push is the standard way of overwriting your development work with the fixed and mergeable version of your contribution!
- Why? You changed the commits, so you want the old ones to be deleted!
You can use any of:
- git push origin +my-awesome-feature
- git push origin -f my-awesome-feature
- git push origin --force my-awesome-feature

Some extra tutorials on git rebase:

Development Setup

If you want to set up a local development environment, follow the steps in the development guide file - which is currently being worked on.

License

By contributing to rustic or any crates contained in this repository, you agree that your contributions will be licensed under:

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

rustic dev documentation