diff --git a/doc/contributing/submitting-changes.xml b/doc/contributing/submitting-changes.xml index 73222c1a49ac..a88965f5cc60 100644 --- a/doc/contributing/submitting-changes.xml +++ b/doc/contributing/submitting-changes.xml @@ -407,23 +407,47 @@ Additional information.
Stable release branches - + + For cherry-picking a commit to a stable release branch (backporting), use git cherry-pick -x <original commit> so that the original commit id is included in the commit. + + + + Add a reason for the backport by using git cherry-pick -xe <original commit> instead when it is not obvious from the original commit message. It is not needed when it’s a minor version update that includes security and bug fixes but don’t add new features or when the commit fixes an otherwise broken package. + + + + Here is an example of a cherry-picked commit message with good reason description: + + + +zfs: Keep trying root import until it works + +Works around #11003. + +(cherry picked from commit 98b213a11041af39b39473906b595290e2a4e2f9) + +Reason: several people cannot boot with ZFS on NVMe + + + + Other examples of reasons are: + + + - If you're cherry-picking a commit to a stable release branch (“backporting”), always use git cherry-pick -xe and ensure the message contains a clear description about why this needs to be included in the stable branch. + Previously the build would fail due to, e.g., getaddrinfo not being defined + + - An example of a cherry-picked commit would look like this: + The previous download links were all broken + + + + + Crash when starting on some X11 systems - -nixos: Refactor the world. - -The original commit message describing the reason why the world was torn apart. - -(cherry picked from commit abcdef) -Reason: I just had a gut feeling that this would also be wanted by people from -the stone age. -