diff options
Diffstat (limited to 'Documentation/process/5.Posting.rst')
| -rw-r--r-- | Documentation/process/5.Posting.rst | 74 |
1 files changed, 54 insertions, 20 deletions
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 4213e580f273..9999bcbdccc9 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -10,8 +10,7 @@ of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; more information can also be found in the files -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`, -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`. @@ -192,19 +191,38 @@ change to a revision control system. It will be followed by: option to diff will associate function names with changes, making the resulting patch easier for others to read. -You should avoid including changes to irrelevant files (those generated by -the build process, for example, or editor backup files) in the patch. The -file "dontdiff" in the Documentation directory can help in this regard; -pass it to diff with the "-X" option. +The tags already briefly mentioned above are used to provide insights how +the patch came into being. They are described in detail in the +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document; what follows here is a brief summary. -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in -the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -document; what follows here is a brief summary. Each of these lines has -the format: +One tag is used to refer to earlier commits which introduced problems fixed by +the patch:: -:: + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Another tag is used for linking web pages with additional backgrounds or +details, for example an earlier discussion which leads to the patch or a +document with a specification implemented by the patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +As per guidance from the Chief Penguin, a Link: tag should only be added to +a commit if it leads to useful information that is not found in the commit +itself. + +If the URL points to a public bug report being fixed by the patch, use the +"Closes:" tag instead:: + + Closes: https://example.com/issues/1234 optional-other-stuff + +Some bug trackers have the ability to close issues automatically when a +commit with such a tag is applied. Some bots monitoring mailing lists can +also track such tags and take certain actions. Private bug trackers and +invalid URLs are forbidden. + +Another kind of tag is used to document who was involved in the development of +the patch. Each of these uses this format:: tag: Full Name <email address> optional-other-stuff @@ -216,10 +234,12 @@ The tags in common use are: which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` Code without a proper signoff cannot be merged into the mainline. - - Co-developed-by: states that the patch was also created by another developer - along with the original author. This is useful at times when multiple - people work on a single patch. Note, this person also needs to have a - Signed-off-by: line in the patch as well. + - Co-developed-by: states that the patch was co-created by several developers; + it is a used to give attribution to co-authors (in addition to the author + attributed by the From: tag) when multiple people work on a single patch. + Every Co-developed-by: must be immediately followed by a Signed-off-by: of + the associated co-author. Details and examples can be found in + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. - Acked-by: indicates an agreement by another developer (often a maintainer of the relevant code) that the patch is appropriate for @@ -235,13 +255,27 @@ The tags in common use are: - Reported-by: names a user who reported a problem which is fixed by this patch; this tag is used to give credit to the (often underappreciated) people who test our code and let us know when things do not work - correctly. + correctly. Note, this tag should be followed by a Closes: tag pointing to + the report, unless the report is not available on the web. The Link: tag + can be used instead of Closes: if the patch fixes a part of the issue(s) + being reported. + + - A Suggested-by: tag indicates that the patch idea is suggested by the person + named and ensures credit to the person for the idea. This will, hopefully, + inspire them to help us again in the future. - Cc: the named person received a copy of the patch and had the opportunity to comment on it. -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. +Be careful in the addition of the aforementioned tags to your patches, as all +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the +person named. For those three implicit permission is sufficient if the person +contributed to the Linux kernel using that name and email address according +to the lore archives or the commit history -- and in case of Reported-by: +and Suggested-by: did the reporting or suggestion in public. Note, +bugzilla.kernel.org is a public place in this sense, but email addresses +used there are private; so do not expose them in tags, unless the person +used them in earlier contributions. Sending the patch |