Increasing GitHub issues value

[Brad Bishop]

> On Mar 15, 2018, at 6:08 AM, Alexander Amelkin <a.amelkin at yadro.com> wrote:
> 
> 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.
> 
> 

I agree these are all behaviors that lead to real value.  I have been
mostly focused on improving our commit messages.

The method I use to do that is I review code, and ask for a better commit
message in the review and explain the value of doing so.  Over time people
see that and they themselves might start to write better commit messages
and ask for it in code they review.  In the end I hope this effect snowballs
and we are all asking for and writing good commit messages.

I wonder if a similar approach could work here?  How do you feel about driving
this change into our culture?  I don’t have any other ideas - in my experience
there has to be repetitive follow-through in order to make something like
this stick.

This is obviously a big task, and I wouldn’t expect you to do it alone.  If
no-one helps you, then that is a sign the community either doesn’t agree with
the value it provides, or it does agree but feels the time is better spent
elsewhere.

Thoughts?

-brad