leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation/submitting-patches: Extend commit message layout description

Browse Source 
Add more blurb about the level of detail that should be contained in a
patch's commit message. Extend and make more explicit what text should
be added under the --- line. Extend examples and split into more easily
palatable paragraphs.

This has been partially carved out from a tip subsystem handbook
patchset by Thomas Gleixner:

  https://lkml.kernel.org/r/20181107171010.421878737@linutronix.de

and incorporates follow-on comments.

Signed-off-by: Borislav Petkov <bp@suse.de>
Reviewed-by: Robert Richter <rrichter@amd.com>
Link: https://lore.kernel.org/r/20210215141949.GB21734@zn.tnic
[jc: Tweaked "example subjects" wording]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Borislav Petkov 2021-02-15 15:19:49 +01:00 committed by Jonathan Corbet
parent 315c4e45f1
commit 875f82cb37
1 changed files with 54 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
Documentation/process/submitting-patches.rst
View File

@ -630,16 +630,19 @@ not considered part of the summary phrase, but describe how the patch
should be treated. Common tags might include a version descriptor if should be treated. Common tags might include a version descriptor if
the multiple versions of the patch have been sent out in response to the multiple versions of the patch have been sent out in response to
comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
comments. If there are four patches in a patch series the individual comments.
patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures
that developers understand the order in which the patches should be
applied and that they have reviewed or applied all of the patches in
the patch series.
A couple of example Subjects:: If there are four patches in a patch series the individual patches may
be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers
understand the order in which the patches should be applied and that
they have reviewed or applied all of the patches in the patch series.
Here are some good example Subjects::
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCH v2 01/27] x86: fix eflags tracking Subject: [PATCH v2 01/27] x86: fix eflags tracking
Subject: [PATCH v2] sub/sys: Condensed patch summary
Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
The ``from`` line must be the very first line in the message body, The ``from`` line must be the very first line in the message body,
and has the form: and has the form:
@ -652,34 +655,54 @@ then the ``From:`` line from the email header will be used to determine
the patch author in the changelog. the patch author in the changelog.
The explanation body will be committed to the permanent source The explanation body will be committed to the permanent source
changelog, so should make sense to a competent reader who has long changelog, so should make sense to a competent reader who has long since
since forgotten the immediate details of the discussion that might forgotten the immediate details of the discussion that might have led to
have led to this patch. Including symptoms of the failure which the this patch. Including symptoms of the failure which the patch addresses
patch addresses (kernel log messages, oops messages, etc.) is (kernel log messages, oops messages, etc.) are especially useful for
especially useful for people who might be searching the commit logs people who might be searching the commit logs looking for the applicable
looking for the applicable patch. If a patch fixes a compile failure, patch. The text should be written in such detail so that when read
it may not be necessary to include _all_ of the compile failures; just weeks, months or even years later, it can give the reader the needed
enough that it is likely that someone searching for the patch can find details to grasp the reasoning for **why** the patch was created.
it. As in the ``summary phrase``, it is important to be both succinct as
well as descriptive.
The ``---`` marker line serves the essential purpose of marking for patch If a patch fixes a compile failure, it may not be necessary to include
handling tools where the changelog message ends. _all_ of the compile failures; just enough that it is likely that
someone searching for the patch can find it. As in the ``summary
phrase``, it is important to be both succinct as well as descriptive.
One good use for the additional comments after the ``---`` marker is for The ``---`` marker line serves the essential purpose of marking for
a ``diffstat``, to show what files have changed, and the number of patch handling tools where the changelog message ends.
inserted and deleted lines per file. A ``diffstat`` is especially useful
on bigger patches. Other comments relevant only to the moment or the
maintainer, not suitable for the permanent changelog, should also go
here. A good example of such comments might be ``patch changelogs``
which describe what has changed between the v1 and v2 version of the
patch.
If you are going to include a ``diffstat`` after the ``---`` marker, please One good use for the additional comments after the ``---`` marker is
use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from for a ``diffstat``, to show what files have changed, and the number of
the top of the kernel source tree and don't use too much horizontal inserted and deleted lines per file. A ``diffstat`` is especially useful
space (easily fit in 80 columns, maybe with some indentation). (``git`` on bigger patches. If you are going to include a ``diffstat`` after the
generates appropriate diffstats by default.) ``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that
filenames are listed from the top of the kernel source tree and don't
use too much horizontal space (easily fit in 80 columns, maybe with some
indentation). (``git`` generates appropriate diffstats by default.)
Other comments relevant only to the moment or the maintainer, not
suitable for the permanent changelog, should also go here. A good
example of such comments might be ``patch changelogs`` which describe
what has changed between the v1 and v2 version of the patch.
Please put this information **after** the ``---`` line which separates
the changelog from the rest of the patch. The version information is
not part of the changelog which gets committed to the git tree. It is
additional information for the reviewers. If it's placed above the
commit tags, it needs manual interaction to remove it. If it is below
the separator line, it gets automatically stripped off when applying the
patch::
<commit message>
...
Signed-off-by: Author <author@mail>
---
V2 -> V3: Removed redundant helper function
V1 -> V2: Cleaned up coding style and addressed review comments
path/to/file | 5+++--
...
See more details on the proper patch format in the following See more details on the proper patch format in the following
references. references.