[Starlingx-discuss] Please Review: Requirements for commit messages

[Jeremy Stanley]

On 2019-09-13 15:10:42 +0000 (+0000), Khalil, Ghada wrote:
[...]
https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines
[...]
> I personally don't see a big barrier to creating a generic
> storyboard for spelling or cleanup tasks. Happy to hear from
> others their opinion. I'm not terribly concerned about a few small
> updates without a link, but we should all aim to favor
> traceability (and document the purpose for the changes we're
> making).
[...]

This topic comes up with some frequency in a variety of free/libre
open-source projects to which I contribute, and from what I've seen
every bit of bureaucracy you add around submitting a contribution is
that much less fun the process becomes for people. Some amount of
red tape and process overhead is unfortunately always going to be
necessary, but I find it helps to make compromises to reduce that
complexity wherever and whenever you possibly can.

Not that I have a horse in this race, but I find it's hard to
overstate the value of a well-written commit message, and it can be
worth 10x more than a link to a disorganized pile of notes in a
defect tracker. I realize a lot of developers don't take the time to
provide thorough exposition in their commit messages, but this is
something for which I consistently review. The commit message should
tell me everything I need to know about a change without needing to
follow links to defect reports or mailing list posts.

Links to external references can be useful citations to help paint
the bigger picture and provide background on decisions which were
made, but if the commit message is sufficiently explanatory then it
saves time both for people reviewing the proposed change *and* for
folks looking back through the commit history years down the line.
What if some unfortunate disaster befalls the materials linked from
the commit message? Or what if I'm on a plane/train/boat with a
clone of the Git repository but no viable access to the Internet?
Linking to additional information is certainly a good thing to do
when it's available, but it's no substitute for clearly describing
in a commit message why that change was needed.

And if the commit message already tells people everything they need
to know about the change, why bother making extra work for
developers by requiring them to file a defect (which in many cases
may only be a considered a "defect" through a significant stretch of
imagination) in a separate system only to immediately mark it as
done? The wiki article you linked gives these two reasons:

    The story/bug will give reviewers context for the code changes.
    This will also be used to help determine the relative priority
    of the code changes.

If the commit is written at the same time the defect is reported,
what additional context can the report really provide if the same
information is included in the commit message already? As for
prioritization, what if it's not a high-priority change to begin
with? What difference does filing a defect reference for it make in
that case? Perhaps if a developer feels their change should be a
higher review priority, then a corresponding tracked task is
warranted; but if they don't create one they are basically saying,
"here's a patch, review it when you have time, it's not urgent."

One other reason that wiki page doesn't mention but can be important
is if the change fixes a bug in the software which a user is likely
to notice in an earlier release and may consider filing a defect
report about themselves, since it can save them some time when they
go to file it and find there's already one there marked fixed in a
later release. This can of course be addressed by having reviewers
recommend and developers be diligent about incorporating clear
release notes for fixes which fit these criteria, since those users
are similarly likely to check release notes first, but depending on
the situation reviewers could still be well within reason to request
(or create, since this is a collaboration, right?) a corresponding
defect report to go with the change.

Anyway, sorry for the lengthy soapbox speech. It doesn't really
impact me either way as a mostly outside observer, but I do think
that it's in the best interests of community health to try and keep
the process of collaborating as enjoyable as possible. Having strict
rules that even the tiniest change also requires task tracking
erodes that enjoyment, and degrades the overall contributor
experience. It's something to keep in mind.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20190913/3163d05f/attachment.sig>