lkml.org 
[lkml]   [2014]   [Jul]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [patch] Documentation: SubmittingPatches: overhaul changelog howto
From
Date
On Wed, 2014-07-30 at 17:11 -0400, Johannes Weiner wrote:
> 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.

Agreed. Maybe other software projects can use this as well...


> Signed-off-by: Johannes Weiner <hannes@cmpxchg.org>
> ---
> Documentation/SubmittingPatches | 38 +++++++++++++++++++++++++++++++-------
> 1 file 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.

Very nicely put. I would also add that past patches or attempts to solve
a related (or even the same) issue. What's different in my approach?
What are the past issues that cause original approaches not to get
merged? etc.



\
 
 \ /
  Last update: 2014-07-31 00:01    [W:3.073 / U:0.488 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site