Re: [PATCH 2/4] dell-wmi: Sort WMI event codes and update comments

Pali Rohár
2016-06-08T20:27:28Z

[-- Attachment #1: Type: Text/Plain, Size: 3327 bytes --]

On Wednesday 08 June 2016 22:15:18 Darren Hart wrote:
> On Wed, Jun 08, 2016 at 09:57:26PM +0200, Pali Rohár wrote:
> > On Wednesday 08 June 2016 21:48:24 Darren Hart wrote:
> > > On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote:
> > > > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote:
> > > > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com>
> > > > >
> > > > > My guess is that Darren won't let you off without at least a
> > > > > short commit message.
> > > >
> > > > I have no idea what else to write. I think that description is
> > > > enough.
> > >
> > > There is always something. For example, why? See
> > > Documentation/SubmittingPatches section "14) The canonical patch
> > > format" for an explanation.
> > >
> > > "Traceability" of changes is important. If it's worth preparing
> > > the patch, it's worth documenting why.
> >
> > In my opinion current description is enough and cover everything
> > what this patch is doing. I think it is clear from my description
> > what this patch is doing and so it is documented.
> >
> > But if it is not clear and something is missing, let me know or
> > show what is wrong and how you change it... It is just my
> > assumption that "Sort WMI event codes and update comments" is
> > clear...
>
> The patch summary accurately states what it does. It does not explain
> why it does it, or why it is necessary. I understand this is a
> trivial change, but also understand that both maintainers and people
> doing maintenance and regression analysis will appreciate
> understanding the motivation and intent of the patch, in addition to
> the content of the patch.
>
> From the maintainer perspective, whether we have 20 or 200 patches to
> review, we will naturally merge the ones that require the least
> effort first. This maximizes our efficiency and benefits the most
> people with what time we have available. For many of us, this is our
> nights and weekends (guessing that's the case for you as well). It
> is in the submitter's best interest to take the time document the
> why, what, and how of each patch in a way that minimizes the effort
> on the part of the maintainer to decide if the patch should be
> merged. It is also a matter of scale, if every patch conforms to
> these guidelines, the workflow is much more efficient.
>
> In this case, I don't know why you decided to sort the event codes or
> update the comments. I assume the comments were wrong before, but
> maybe something changed. Do you care about alphabetically order or
> optimizing the switch statements? Is it purely for legibility? Etc.
>
> If that isn't sufficient, then just do it out of self-interest,
> because I will not send patches to Linus that do not provide both a
> summary and a description in the commit which meet the guidelines of
> section 14 referenced above.
>
> Thanks,

I fully understand your maintainer perspective. I just though that my
one line explain everything what is needed about my patch...

So do you want to include reason for my patch? What about this
additional description?

===
For better readability of keymap table, sort events by codes and also
update comments for events to be more informative.
===

--
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]