Commit 7b9828d4 authored by Johannes Weiner's avatar Johannes Weiner Committed by Linus Torvalds

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: default avatarJohannes Weiner <hannes@cmpxchg.org>
Acked-by: default avatarDavid S. Miller <davem@davemloft.net>
Acked-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: default avatarIngo Molnar <mingo@kernel.org>
Signed-off-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent d74aae4e
...@@ -84,18 +84,42 @@ is another popular alternative. ...@@ -84,18 +84,42 @@ is another popular alternative.
2) Describe your changes. 2) Describe your changes.
Describe the technical detail of the change(s) your patch includes. 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
Be as specific as possible. The WORST descriptions possible include motivated you to do this work. Convince the reviewer that there is a
things like "update driver X", "bug fix for driver X", or "this patch problem worth fixing and that it makes sense for them to read past the
includes updates for subsystem X. Please apply." 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 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 form which can be easily pulled into Linux's source code management
system, git, as a "commit log". See #15, below. system, git, as a "commit log". See #15, below.
If your description starts to get long, that's a sign that you probably Solve only one problem per patch. If your description starts to get
need to split up your patch. See #3, next. 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 When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just complete patch description and justification for it. Don't just
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment