diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/development-process/5.Posting | 31 |
1 files changed, 28 insertions, 3 deletions
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting index dd48132a74dd..f622c1e9f0f9 100644 --- a/Documentation/development-process/5.Posting +++ b/Documentation/development-process/5.Posting | |||
@@ -119,7 +119,7 @@ which takes quite a bit of time and thought after the "real work" has been | |||
119 | done. When done properly, though, it is time well spent. | 119 | done. When done properly, though, it is time well spent. |
120 | 120 | ||
121 | 121 | ||
122 | 5.4: PATCH FORMATTING | 122 | 5.4: PATCH FORMATTING AND CHANGELOGS |
123 | 123 | ||
124 | So now you have a perfect series of patches for posting, but the work is | 124 | So now you have a perfect series of patches for posting, but the work is |
125 | not done quite yet. Each patch needs to be formatted into a message which | 125 | 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: | |||
146 | - One or more tag lines, with, at a minimum, one Signed-off-by: line from | 146 | - One or more tag lines, with, at a minimum, one Signed-off-by: line from |
147 | the author of the patch. Tags will be described in more detail below. | 147 | the author of the patch. Tags will be described in more detail below. |
148 | 148 | ||
149 | The above three items should, normally, be the text used when committing | 149 | The items above, together, form the changelog for the patch. Writing good |
150 | the change to a revision control system. They are followed by: | 150 | changelogs is a crucial but often-neglected art; it's worth spending |
151 | another moment discussing this issue. When writing a changelog, you should | ||
152 | bear in mind that a number of different people will be reading your words. | ||
153 | These include subsystem maintainers and reviewers who need to decide | ||
154 | whether the patch should be included, distributors and other maintainers | ||
155 | trying to decide whether a patch should be backported to other kernels, bug | ||
156 | hunters wondering whether the patch is responsible for a problem they are | ||
157 | chasing, users who want to know how the kernel has changed, and more. A | ||
158 | good changelog conveys the needed information to all of these people in the | ||
159 | most direct and concise way possible. | ||
160 | |||
161 | To that end, the summary line should describe the effects of and motivation | ||
162 | for the change as well as possible given the one-line constraint. The | ||
163 | detailed description can then amplify on those topics and provide any | ||
164 | needed additional information. If the patch fixes a bug, cite the commit | ||
165 | which introduced the bug if possible. If a problem is associated with | ||
166 | specific log or compiler output, include that output to help others | ||
167 | searching for a solution to the same problem. If the change is meant to | ||
168 | support other changes coming in later patch, say so. If internal APIs are | ||
169 | changed, detail those changes and how other developers should respond. In | ||
170 | general, the more you can put yourself into the shoes of everybody who will | ||
171 | be reading your changelog, the better that changelog (and the kernel as a | ||
172 | whole) will be. | ||
173 | |||
174 | Needless to say, the changelog should be the text used when committing the | ||
175 | change to a revision control system. It will be followed by: | ||
151 | 176 | ||
152 | - The patch itself, in the unified ("-u") patch format. Using the "-p" | 177 | - The patch itself, in the unified ("-u") patch format. Using the "-p" |
153 | option to diff will associate function names with changes, making the | 178 | option to diff will associate function names with changes, making the |