From faebd57db88539feef8dbb037956e2135cea7cff Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Mon, 16 Mar 2026 10:51:05 +0100 Subject: [PATCH] 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 On-behalf-of: SAP philipp.schuster@sap.com --- CONTRIBUTING.md | 53 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac65550c0..1518d0f1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) 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**._ -``` -: Change summary +We require patches to: -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. +- Have a `Signed-off-by: Name ` footer +- Follow the pattern: \ + ``` + : 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: + ``` + -Signed-off-by: -``` +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 @@ -94,6 +103,20 @@ configure it anyway. Signed-off-by: Rob Bradford ``` +### 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 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. [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. -1. To update your pull request amend existing commits whenever applicable and - then push the new changes to your pull request branch. +1. Each commit must comply with the Commit Hygiene guidelines above. +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. +Please squash any changes done during review already into the corresponding +commits instead of pushing `: addressing review for A`-style commits. + ## Issue tracking If you have a problem, please let us know. We recommend using