docs: Add git commit hygiene guidelines to CONTRIBUTING.md

Write down our policy for git commit hygiene, especially when it comes
to the history, i.e., multiple git commits in a PR.

TL;DR: Commits must be revieable units guiding reviewers how the
       developer got from A to B.

Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
On-behalf-of: SAP philipp.schuster@sap.com
This commit is contained in:
Philipp Schuster
2026-03-16 10:51:05 +01:00
committed by Rob Bradford
parent 1733e08a0f
commit faebd57db8

View File

@@ -61,22 +61,31 @@ commit you make.
In order to get a clear contribution chain of trust we use the [signed-off-by language](https://www.kernel.org/doc/Documentation/process/submitting-patches.rst) In order to get a clear contribution chain of trust we use the [signed-off-by language](https://www.kernel.org/doc/Documentation/process/submitting-patches.rst)
used by the Linux kernel project. used by the Linux kernel project.
## Patch format ## Patch format & Git Commit Hygiene
Beside the signed-off-by footer, we expect each patch to comply with the following format: _We use **Patch** as synonym for **Commit**._
``` We require patches to:
<component>: Change summary
More detailed explanation of your changes: Why and how. - Have a `Signed-off-by: Name <email>` footer
Wrap it to 72 characters. - Follow the pattern: \
See http://chris.beams.io/posts/git-commit/ ```
for some more good pieces of advice. <component>: Change summary
More detailed explanation of your changes: Why and how.
Wrap it to 72 characters.
See http://chris.beams.io/posts/git-commit/
for some more good pieces of advice.
Signed-off-by: <contributor@foo.com>
```
Signed-off-by: <contributor@foo.com> Valid components are listed in `TitleStartsWithComponent.py`. In short, each
``` cargo workspace member is a valid component as well as `build`, `ci`, `docs` and
`misc`.
For example: Example patch:
``` ```
vm-virtio: Reset underlying device on driver request vm-virtio: Reset underlying device on driver request
@@ -94,6 +103,20 @@ configure it anyway.
Signed-off-by: Rob Bradford <robert.bradford@intel.com> Signed-off-by: Rob Bradford <robert.bradford@intel.com>
``` ```
### Git Commit History
We value a clean, **reviewable** commit history. Each commit should represent
a self-contained, logical step that guides reviewers clearly from A to B.
Avoid patterns like `init A -> init B -> fix A` or \
`init design A -> revert A -> use design B`. Commits must be independently
reviewable - don't leave "fix previous commit" or earlier design attempts in
the history.
Intermediate work-in-progress changes are acceptable only if a subsequent
commit in the same series cleans them up (e.g. a temporary `#[allow(unused)]`
removed in the next commit).
## Pull requests ## Pull requests
Cloud Hypervisor uses the “fork-and-pull” development model. Follow these steps if Cloud Hypervisor uses the “fork-and-pull” development model. Follow these steps if
@@ -104,10 +127,14 @@ you want to merge your changes to `cloud-hypervisor`:
1. Within your fork, create a branch for your contribution. 1. Within your fork, create a branch for your contribution.
1. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) 1. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
against the main branch of the Cloud Hypervisor repository. against the main branch of the Cloud Hypervisor repository.
1. To update your pull request amend existing commits whenever applicable and 1. Each commit must comply with the Commit Hygiene guidelines above.
then push the new changes to your pull request branch. 1. A pull request should address a single component or concern to keep review
focused and approvals straightforward.
1. Once the pull request is approved it can be integrated. 1. Once the pull request is approved it can be integrated.
Please squash any changes done during review already into the corresponding
commits instead of pushing `<component>: addressing review for A`-style commits.
## Issue tracking ## Issue tracking
If you have a problem, please let us know. We recommend using If you have a problem, please let us know. We recommend using