adulau/aha
1
0
Fork 0
mirror of https://github.com/adulau/aha.git synced 2024-12-27 03:06:10 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: Encourage better changelogs in the development process document

Browse source 
Add a couple of paragraphs to the "patch formatting" section on how patches
should be described.  This text is shamelessly cribbed from suggestions
posted by Rusty Russell.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet 2009-04-21 13:33:06 -06:00
parent bbb0a4247a
commit 5d98932ab0
1 changed files with 28 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
Documentation/development-process/5.Posting
View file

@ -119,7 +119,7 @@ which takes quite a bit of time and thought after the "real work" has been
done. When done properly, though, it is time well spent. done. When done properly, though, it is time well spent.
5.4: PATCH FORMATTING 5.4: PATCH FORMATTING AND CHANGELOGS
So now you have a perfect series of patches for posting, but the work is So now you have a perfect series of patches for posting, but the work is
not done quite yet. Each patch needs to be formatted into a message which not done quite yet. Each patch needs to be formatted into a message which
@ -146,8 +146,33 @@ that end, each patch will be composed of the following:
- One or more tag lines, with, at a minimum, one Signed-off-by: line from - One or more tag lines, with, at a minimum, one Signed-off-by: line from
the author of the patch. Tags will be described in more detail below. the author of the patch. Tags will be described in more detail below.
The above three items should, normally, be the text used when committing The items above, together, form the changelog for the patch. Writing good
the change to a revision control system. They are followed by: changelogs is a crucial but often-neglected art; it's worth spending
another moment discussing this issue. When writing a changelog, you should
bear in mind that a number of different people will be reading your words.
These include subsystem maintainers and reviewers who need to decide
whether the patch should be included, distributors and other maintainers
trying to decide whether a patch should be backported to other kernels, bug
hunters wondering whether the patch is responsible for a problem they are
chasing, users who want to know how the kernel has changed, and more. A
good changelog conveys the needed information to all of these people in the
most direct and concise way possible.
To that end, the summary line should describe the effects of and motivation
for the change as well as possible given the one-line constraint. The
detailed description can then amplify on those topics and provide any
needed additional information. If the patch fixes a bug, cite the commit
which introduced the bug if possible. If a problem is associated with
specific log or compiler output, include that output to help others
searching for a solution to the same problem. If the change is meant to
support other changes coming in later patch, say so. If internal APIs are
changed, detail those changes and how other developers should respond. In
general, the more you can put yourself into the shoes of everybody who will
be reading your changelog, the better that changelog (and the kernel as a
whole) will be.
Needless to say, the changelog should be the text used when committing the
change to a revision control system. It will be followed by:
- The patch itself, in the unified ("-u") patch format. Using the "-p" - The patch itself, in the unified ("-u") patch format. Using the "-p"
option to diff will associate function names with changes, making the option to diff will associate function names with changes, making the