|
| 1 | +# Contributing to `rustic` |
| 2 | + |
| 3 | +Thank you for your interest in contributing to `rustic`! |
| 4 | + |
| 5 | +We appreciate your help in making this project better. |
| 6 | + |
| 7 | +## Table of Contents |
| 8 | + |
| 9 | +- [Code of Conduct](#code-of-conduct) |
| 10 | +- [How to Contribute](#how-to-contribute) |
| 11 | + - [Reporting Bugs](#reporting-bugs) |
| 12 | + - [Issue and Pull Request Labels](#issue-and-pull-request-labels) |
| 13 | + - [Suggesting Enhancements](#suggesting-enhancements) |
| 14 | + - [Code Style and Formatting](#code-style-and-formatting) |
| 15 | + - [Testing](#testing) |
| 16 | + - [Submitting Pull Requests](#submitting-pull-requests) |
| 17 | + - [Rebasing and other workflows](#rebasing-and-other-workflows) |
| 18 | +- [Development Setup](#development-setup) |
| 19 | +- [License](#license) |
| 20 | + |
| 21 | +## Code of Conduct |
| 22 | + |
| 23 | +Please review and abide by the general Rust Community |
| 24 | +[Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) when |
| 25 | +contributing to this project. In the future, we might create our own Code of |
| 26 | +Conduct and supplement it at this location. |
| 27 | + |
| 28 | +## How to Contribute |
| 29 | + |
| 30 | +### Reporting Bugs |
| 31 | + |
| 32 | +If you find a bug, please open an |
| 33 | +[issue on GitHub](https://github.com/rustic-rs/rustic/issues/new/choose) and |
| 34 | +provide as much detail as possible. Include steps to reproduce the bug and the |
| 35 | +expected behavior. |
| 36 | + |
| 37 | +### Issue and Pull Request labels |
| 38 | + |
| 39 | +Our Issues and Pull Request labels follow the official Rust style: |
| 40 | + |
| 41 | +```text |
| 42 | +A - Area |
| 43 | +C - Category |
| 44 | +D - Diagnostic |
| 45 | +E - Call for participation |
| 46 | +F - Feature |
| 47 | +I - Issue e.g. I-crash |
| 48 | +M - Meta |
| 49 | +O - Operating systems |
| 50 | +P - priorities e.g. P-{low, medium, high, critical} |
| 51 | +PG - Project Group |
| 52 | +perf - Performance |
| 53 | +S - Status e.g. S-{blocked, experimental, inactive} |
| 54 | +T - Team relevancy |
| 55 | +WG - Working group |
| 56 | +``` |
| 57 | + |
| 58 | +### Suggesting Enhancements |
| 59 | + |
| 60 | +If you have an idea for an enhancement or a new feature, we'd love to hear it! |
| 61 | +Open an [issue on GitHub](https://github.com/rustic-rs/rustic/issues/new/choose) |
| 62 | +and describe your suggestion in detail. |
| 63 | + |
| 64 | +### Code Style and Formatting |
| 65 | + |
| 66 | +We follow the Rust community's best practices for code style and formatting. |
| 67 | +Before submitting code changes, please ensure your code adheres to these |
| 68 | +guidelines: |
| 69 | + |
| 70 | +- Use `rustfmt` to format your code. You can run it with the following command: |
| 71 | + |
| 72 | + ```bash |
| 73 | + cargo fmt --all |
| 74 | + ``` |
| 75 | + |
| 76 | +- Use `dprint` to format text in markdown, toml, and json. You can install it |
| 77 | + with `cargo install dprint`/`scoop install dprint` and run it with the |
| 78 | + following command in the repository root: |
| 79 | + |
| 80 | + ```bash |
| 81 | + dprint fmt |
| 82 | + ``` |
| 83 | + |
| 84 | +- Write clear and concise code with meaningful, self-describing variable and |
| 85 | + function names. This tells the reader **what** the code does. |
| 86 | + |
| 87 | +- Write clear and consise comments to tell the reader **why** you chose to |
| 88 | + implement it that way and **which** problem it solves. |
| 89 | + |
| 90 | +### Testing |
| 91 | + |
| 92 | +We value code quality and maintainability. If you are adding new features or |
| 93 | +making changes, please include relevant unit tests. Run the test suite with: |
| 94 | + |
| 95 | +```bash |
| 96 | +cargo test --workspace |
| 97 | +``` |
| 98 | + |
| 99 | +or check the [testing guide](development/testing_guide.md) for more information |
| 100 | +which tools we provide for making developing `rustic` easier. |
| 101 | + |
| 102 | +Make sure all tests pass before submitting your changes. PRs containing tests |
| 103 | +have a much higher probability of getting merged (fast). |
| 104 | + |
| 105 | +We expect PRs especially ones that introduce new features to contain tests for |
| 106 | +the new code. |
| 107 | + |
| 108 | +Besides that, we welcome PRs which increase the general test coverage of the |
| 109 | +project. You can check the |
| 110 | +[testing guide](development/testing_guide.md#code-coverage) for more |
| 111 | +information. |
| 112 | + |
| 113 | +We appreciate tests in every form: be it *unit*, *doc* or *integration* tests |
| 114 | +(chose depending on your use case). |
| 115 | + |
| 116 | +If you want to implement some *fuzzing* or *benchmarking*, that is also highly |
| 117 | +appreciated. |
| 118 | + |
| 119 | +### Submitting Pull Requests |
| 120 | + |
| 121 | +To contribute code changes, follow these steps: |
| 122 | + |
| 123 | +1. **Fork** the repository. |
| 124 | + |
| 125 | +2. **Create** a new branch with a descriptive name: |
| 126 | + |
| 127 | + ```bash |
| 128 | + git checkout -b feature/your-feature-name |
| 129 | + ``` |
| 130 | + |
| 131 | +3. **Check** and **Commit** your changes: |
| 132 | + |
| 133 | + ```bash |
| 134 | + just pre-commit |
| 135 | + git commit -m "Add your meaningful commit message here" |
| 136 | + ``` |
| 137 | + |
| 138 | +4. **Push** your branch to your forked repository: |
| 139 | + |
| 140 | + ```bash |
| 141 | + git push origin feature/your-feature-name |
| 142 | + ``` |
| 143 | + |
| 144 | +5. **Open** a Pull Request (PR) to our repository. Please include a detailed |
| 145 | + description of the changes and reference any related issues. |
| 146 | + |
| 147 | +#### `Release early and often!` also applies to pull requests |
| 148 | + |
| 149 | +Consider drafting a Pull request early in the development process, so we can |
| 150 | +follow your progress and can give early feedback. |
| 151 | + |
| 152 | +Once your PR is submitted, it will be reviewed by the maintainers. We may |
| 153 | +suggest changes or ask for clarifications before merging. |
| 154 | + |
| 155 | +##### IMPORTANT NOTE |
| 156 | + |
| 157 | +Please don't force push commits in your branch, in order to keep commit history |
| 158 | +and make it easier for us to see changes between reviews. |
| 159 | + |
| 160 | +Make sure to Allow edits of maintainers (under the text box) in the PR so people |
| 161 | +can actually collaborate on things or fix smaller issues themselves. |
| 162 | + |
| 163 | +#### Rebasing and other workflows |
| 164 | + |
| 165 | +(taken from: |
| 166 | +[openage on rebasing](https://github.com/SFTtech/openage/blob/master/doc/contributing.md#rebasing)) |
| 167 | + |
| 168 | +**Rebasing** is 'moving' your commits to a different parent commit. |
| 169 | + |
| 170 | +In other words: *Cut off* your branch from its tree, and *attach it* somewhere |
| 171 | +else. |
| 172 | + |
| 173 | +There's two main applications: |
| 174 | + |
| 175 | +- If you based your work on a older main (so old that stuff can't be |
| 176 | + automatically merged), you can rebase to move your commits to the current |
| 177 | + [upstream](https://help.github.com/articles/fork-a-repo/) main: |
| 178 | + |
| 179 | +```bash |
| 180 | +# update the upstream remote to receive new commits |
| 181 | +git fetch upstream |
| 182 | + |
| 183 | +# be on your feature branch (you probably are) |
| 184 | +git checkout my-awesome-feature |
| 185 | + |
| 186 | +# make backup (you never know, you know?) |
| 187 | +git branch my-awesome-feature-backup |
| 188 | + |
| 189 | +# rebase: put your commits on top of upstream's main |
| 190 | +git rebase -m upstream/main |
| 191 | +``` |
| 192 | + |
| 193 | +- If you want to fix an older commit of yours, or merge several commits into a |
| 194 | + single one (**squash** them), rebase interactively. We ***don't*** want to |
| 195 | + have a commit history like this: |
| 196 | + |
| 197 | + - `add stuff` |
| 198 | + - `fix typo in stuff` |
| 199 | + - `fix compilation` |
| 200 | + - `change stuff a bit` |
| 201 | + - and so on... |
| 202 | + |
| 203 | +##### `rebase` in practice |
| 204 | + |
| 205 | +`git log --graph --oneline` shows your commit history as graph. To make some |
| 206 | +changes in that graph, you do an **interactive rebase**: |
| 207 | + |
| 208 | +```sh |
| 209 | +git rebase -i -m upstream/main |
| 210 | +``` |
| 211 | + |
| 212 | +With this command, your new "base" is `upstream/main` and you can then change |
| 213 | +any of your branch's commits. |
| 214 | + |
| 215 | +`-i` will open an interactive editor where you can choose actions for each |
| 216 | +individual commit: |
| 217 | + |
| 218 | +- re-order commits |
| 219 | +- drop commits by deleting their line |
| 220 | +- squash/fixup ("meld") your commits |
| 221 | +- reword a commit message |
| 222 | +- stop rebasing at a commit to edit (`--amend`) it manually |
| 223 | + |
| 224 | +Just follow the messages on screen. |
| 225 | + |
| 226 | +##### Changing commits with `amend` and `fixup` |
| 227 | + |
| 228 | +There's also `git commit --amend` which is a "mini-rebase" that modifies just |
| 229 | +the last commit with your current changes by `git add`. It just skips the |
| 230 | +creation of a new commit and instead melds the changes into the last one you |
| 231 | +made. |
| 232 | + |
| 233 | +If you want to update a single commit in the range |
| 234 | +`[upstream/main, current HEAD]` which is not the last commit: |
| 235 | + |
| 236 | +- `edit stuff you wanna change in some previous commit` |
| 237 | +- `git add changed_stuff` |
| 238 | +- `git commit --fixup $hash_of_commit_to_be_fixed` |
| 239 | +- `git rebase --autosquash -i -m upstream/main` |
| 240 | + |
| 241 | +##### Pushing changes |
| 242 | + |
| 243 | +After you have rebased stuff |
| 244 | +(["rewritten history"](https://www.youtube.com/watch?v=9lXuZHkOoH8)) that had |
| 245 | +already been pushed, git will not accept your pushes because they're not simple |
| 246 | +fast-forwards: |
| 247 | + |
| 248 | +- The commit contents and the parent commit have changed as you updated the |
| 249 | + commit, therefore the commit hash changed, too. |
| 250 | + - If somebody used those commits, they will keep a copy and have a hard time |
| 251 | + updating to your updated version (because they "use" the old hashes). |
| 252 | + - Update your pull request branch with your re-written history! |
| 253 | + |
| 254 | +- **force push** is the standard way of overwriting your development work with |
| 255 | + the fixed and mergeable version of your contribution! |
| 256 | + - Why? You changed the commits, so you want the old ones to be deleted! |
| 257 | + |
| 258 | + You can use any of: |
| 259 | + - `git push origin +my-awesome-feature` |
| 260 | + - `git push origin -f my-awesome-feature` |
| 261 | + - `git push origin --force my-awesome-feature` |
| 262 | + |
| 263 | +Some extra tutorials on `git rebase`: |
| 264 | + |
| 265 | +- [Atlassian's Git Tutorial](https://www.atlassian.com/git/tutorials/rewriting-history/) |
| 266 | +- [Pro Git book](http://git-scm.com/book) |
| 267 | +- `man git-rebase` |
| 268 | + |
| 269 | +## Development Setup |
| 270 | + |
| 271 | +If you want to set up a local development environment, follow the steps in the |
| 272 | +[development guide](development/intro.md) file - which is currently being worked |
| 273 | +on. |
| 274 | + |
| 275 | +## License |
| 276 | + |
| 277 | +By contributing to `rustic` or any crates contained in this repository, you |
| 278 | +agree that your contributions will be licensed under: |
| 279 | + |
| 280 | +- [Apache License, Version 2.0](./LICENSE-APACHE) |
| 281 | +- [MIT license](./LICENSE-MIT). |
| 282 | + |
| 283 | +Unless you explicitly state otherwise, any contribution intentionally submitted |
| 284 | +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be |
| 285 | +dual licensed as above, without any additional terms or conditions. |
0 commit comments