diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55dc55ba3..8a65ce565 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,15 +28,26 @@ which are considered to be things to work on to get going. If you're interested ## Submitting your work -Fork the repository and open a pull request to submit your work. Please consider: +Fork the repository and open a pull request to submit your work. -* Running `cargo fmt` and `cargo clippy` to keep the code formatting in check. -* Running `make` to run the test suite. +The CI checks for formatting, Clippy warnings, and test failures so remember to run the following before submitting your pull request: -As general guideline for pull requests, please: +* `cargo fmt` and `cargo clippy` to keep the code formatting in check. +* `make` to run the test suite. + +**Keep your pull requests focused and as small as possible, but not smaller.** IOW, when preparing a pull request, ensure it focuses on a single thing and that your commits align with that. For example, a good pull request might fix a specific bug or a group of related bugs. Or a good pull request might add a new feature and test for it. Conversely, a bad pull request might fix a bug, add a new feature, and refactor some code. + +**The commits in your pull request tell the story of your change.** Break your pull request into multiple commits when needed to make it easier to review and ensure that future developers can also understand the change as they are in the middle of a `git bisect` run to debug a nasty bug. A developer should be able to reconstruct the intent of your change and how you got to the end-result by reading the commits. To keep a clean commit history, make sure the commits are _atomic_: + +* **Keep commits as small as possible**. The smaller the commit, the easier it is to review, but also easier `git revert` when things go bad. +* **Don't mix logic and cleanups in same commit**. If you need to refactor the code, do it in a commit of its own. Mixing refactoring with logic changes makes it very hard to review a commit. +* **Don't mix logic and formatting changes in same commit**. Resist the urge to fix random formatting issues in the same commit as your logic changes, because it only makes it harder to review the commit. +* **Write a good commit message**. You know your commit is atomic when it's easy to write a short commit message that describes the intent of the change. + +To produce pull requests like this, you should learn how to use Git's interactive rebase (`git rebase -i`). + +For a longer discussion on good commits, see Al Tenhundfeld's [What makes a good git commit](https://www.simplethread.com/what-makes-a-good-git-commit/), for example. -* Don't mix fixes and cleanups in same pull request. They just increase the likelihood of merge conflicts. Cleanups are welcome, but just keep them separate. -* Prefer `git rebase main` over `git merge main` on your branches to keep git logs clean. ## Debugging query execution