summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJohannes Weiner <hannes@cmpxchg.org>2014-08-05 23:32:56 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2014-08-09 09:13:40 -0700
commit7b9828d44194b2d90595ed4bd5131cacbf29b201 (patch)
tree17ca252aa5174a53e35716ac0cae0c760727630e /Documentation
parentd74aae4ea0257f3d6e94ef7a0420ef5074d6eb1e (diff)
Documentation: SubmittingPatches: overhaul changelog description
Maintainers often repeat the same feedback on poorly written changelogs - describe the problem, justify your changes, quantify optimizations, describe user-visible changes - but our documentation on writing changelogs doesn't include these things. Fix that. Signed-off-by: Johannes Weiner <hannes@cmpxchg.org> Acked-by: David S. Miller <davem@davemloft.net> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Acked-by: Ingo Molnar <mingo@kernel.org> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/SubmittingPatches38
1 files changed, 31 insertions, 7 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dcadffcab2dc..0a523c9a5ff4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -84,18 +84,42 @@ is another popular alternative.
2) Describe your changes.
-Describe the technical detail of the change(s) your patch includes.
-
-Be as specific as possible. The WORST descriptions possible include
-things like "update driver X", "bug fix for driver X", or "this patch
-includes updates for subsystem X. Please apply."
+Describe your problem. Whether your patch is a one-line bug fix or
+5000 lines of a new feature, there must be an underlying problem that
+motivated you to do this work. Convince the reviewer that there is a
+problem worth fixing and that it makes sense for them to read past the
+first paragraph.
+
+Describe user-visible impact. Straight up crashes and lockups are
+pretty convincing, but not all bugs are that blatant. Even if the
+problem was spotted during code review, describe the impact you think
+it can have on users. Keep in mind that the majority of Linux
+installations run kernels from secondary stable trees or
+vendor/product-specific trees that cherry-pick only specific patches
+from upstream, so include anything that could help route your change
+downstream: provoking circumstances, excerpts from dmesg, crash
+descriptions, performance regressions, latency spikes, lockups, etc.
+
+Quantify optimizations and trade-offs. If you claim improvements in
+performance, memory consumption, stack footprint, or binary size,
+include numbers that back them up. But also describe non-obvious
+costs. Optimizations usually aren't free but trade-offs between CPU,
+memory, and readability; or, when it comes to heuristics, between
+different workloads. Describe the expected downsides of your
+optimization so that the reviewer can weigh costs against benefits.
+
+Once the problem is established, describe what you are actually doing
+about it in technical detail. It's important to describe the change
+in plain English for the reviewer to verify that the code is behaving
+as you intend it to.
The maintainer will thank you if you write your patch description in a
form which can be easily pulled into Linux's source code management
system, git, as a "commit log". See #15, below.
-If your description starts to get long, that's a sign that you probably
-need to split up your patch. See #3, next.
+Solve only one problem per patch. If your description starts to get
+long, that's a sign that you probably need to split up your patch.
+See #3, next.
When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just