Skip to content

Commit 0547ff2

Browse files
committed
docs(contrib): Clarify our policies
1 parent 2a274e1 commit 0547ff2

File tree

1 file changed

+30
-15
lines changed

1 file changed

+30
-15
lines changed

CONTRIBUTING.md

+30-15
Original file line numberDiff line numberDiff line change
@@ -29,27 +29,42 @@ to re-work some of it and the discouragement that goes along with that.
2929

3030
### Process
3131

32-
Before posting a PR, we request that the commit history get cleaned up.
33-
However, we recommend avoiding this during the review to make it easier to
34-
check how feedback was handled. Once the PR is ready, we'll ask you to clean up
35-
the commit history from the review. Once you let us know this is done, we can
36-
move forward with merging! If you are uncomfortable with these parts of git,
37-
let us know and we can help.
38-
39-
For commit messages, we use [Conventional](https://www.conventionalcommits.org)
40-
style. If you already wrote your commits and don't feel comfortable changing
41-
them, don't worry and go ahead and create your PR. We'll work with you on the
42-
best route forward. You can check your branch locally with
43-
[`committed`](https://github.com/crate-ci/committed).
44-
4532
As a heads up, we'll be running your PR through the following gauntlet:
4633
- warnings turned to compile errors
4734
- `cargo test`
4835
- `rustfmt`
4936
- `clippy`
5037
- `rustdoc`
51-
- [`committed`](https://github.com/crate-ci/committed)
52-
- [`typos`](https://github.com/crate-ci/typos)
38+
- [`committed`](https://github.com/crate-ci/committed) as we use [Conventional](https://www.conventionalcommits.org) commit styl
39+
- [`typos`](https://github.com/crate-ci/typos) to check spelling
40+
41+
Not everything can be checked automatically though.
42+
43+
We request that the commit history get cleaned up.
44+
We ask that commits are atomic, meaning they are complete and have a single responsibility.
45+
PRs shoukd tell a cohesive story, with test and refactor commits that keep the
46+
fix or feature commits simple and clear.
47+
48+
Specifically, we would encouage
49+
- File renames be isolated into their own commit
50+
- Add tests in a commit before their feature or fix, showing the current behavior.
51+
The diff for the feature/fix commit will then show how the behavior changed,
52+
making it clearer to reviewrs and the community and showing people that the
53+
test is verifying the expected state.
54+
- e.g. [clap#5520](https://github.com/clap-rs/clap/pull/5520)
55+
56+
Note that we are talking about ideals.
57+
We understand having a clean history requires more advanced git skills;
58+
feel free to ask us for help!
59+
We might even suggest where it would work to be lax.
60+
We also understand that editing some early commits may cause a lot of churn
61+
with merge conflicts which can make it not worth editing all of the history.
62+
63+
For code organization, we recommend
64+
- Grouping `impl` blocks next to their type (or trait)
65+
- Grouping private items after the `pub` item that uses them.
66+
- The intent is to help people quickly find the "relevant" details, allowing them to "dig deeper" as needed. Or put another way, the `pub` items serve as a table-of-contents.
67+
- The exact order is fuzzy; do what makes sense
5368

5469
## Releasing
5570

0 commit comments

Comments
 (0)