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

[Darren Hart]

On Wed, Jun 08, 2016 at 10:27:20PM +0200, Pali RohÃr wrote:
> 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@xxxxxxxxx>
> > > > > > 
> > > > > > 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.

Great, that works for me. Reason was readability and providing context.

I'm just getting to the series now, if it's otherwise ready, I'll include this
myself. If changes are required, I'll leave it to you. Thanks Pali.

-- 
Darren Hart
Intel Open Source Technology Center