Increasing GitHub issues value

[Alexander Amelkin]

Hi everyone!

While trying to write a customer-readable Change Log and Release Notes,
I've been browsing through a lot of git commit logs, some of them
referencing GitHub issues. I have noticed one common problem shared by
almost all issues that makes it extremely painful to create the document
I was trying to make. That is a total lack of reasoning behind the
conducted changes. A typical issue looks like an imperative "Change
everything" without even a slight hint as to "why do that" and "what was
wrong with the original code".

There are lots of such issues by almost all the members.

My proposal is to enforce verbose desriptions in GitHub issues.

From my previous experience of working on DO-178B certified projects,
the following approach helps a lot when doing a retrospective of the
changes or investigating why a certain part of code is present and/or
works as it does (was it intended, or is it a mistake):

1. As the initial description (first comment) for the issue, write as
many words as you can to explain the original problem, trying as hard as
possible to make this description clear to a non-member, a
non-programmer (admin), or even a non-technical person. Be as much
user-centric in the description as possible, but don't forget to include
all the technical details that you have as well, for they will be needed
for the engineer assigned to this issue or even yourself later when you
come back to this issue 3 years later in search of a root cause for some
problem.

2. When you get to working on the issue, write a verbose "Analysis"
comment describing what you have discovered while investigating the
original problem. Any quotes from e-mail correspondence, links to
mailing list posts, etc. are very welcome in this part. Filling out this
part often helps to realize that you've been actually going a wrong way
or that the original problem is not a problem at all.

3. Once you come up with a solution, write a comment (verbose again)
that describes what exactly you're going to do and why (although "why"
should have mostly been covered in the "Analysis" part). This greatly
helps in clearing your own mind and obtaining a precise understanding of
your changes before you actually push them, helps reviewers to review
the pushed code, and later helps to fix bugs in it that passed the review.

4. Preferably describe in a separate comment the impact on the end user
experience that your change is going to have (i.e. what change in system
behavior or UI does it yield). If all the issues (or better yet commit
logs) had this part, writing Release Notes would be a breeze.

What do you guys think?

With best regards,
Alexander.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20180315/66d7897b/attachment.sig>