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>hifive-unleashed-5.1
parent
d74aae4ea0
commit
7b9828d441
|
@ -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
|
||||||
|
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.
|
||||||
|
|
||||||
Be as specific as possible. The WORST descriptions possible include
|
Describe user-visible impact. Straight up crashes and lockups are
|
||||||
things like "update driver X", "bug fix for driver X", or "this patch
|
pretty convincing, but not all bugs are that blatant. Even if the
|
||||||
includes updates for subsystem X. Please apply."
|
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
|
||||||
|
|
Loading…
Reference in New Issue