Yesterday, I wrote about how much I loved working with the team at Cloud Four on a recent project. One of the things they do very well that most dev teams I’ve worked with do not is make full use of GitHub’s PR Templates feature. In my consulting work, I see a lot of PRs that include either a one-line comment or not description at all. But Cloud Four’s PRs always include a rich amount of detail that makes it much easier for the reviewer to understand what’s going on and what to look at.
  • Kissaki@programming.devEnglish
    1·
    12 hours ago

    When PRs begin with a headline and checklist the GitHub hover-preview becomes useless. When the PR description begins with the summation of the change, it is very useful.

    Most of the time I see headlines and check lists in tickets I create or contributions I create PRs for, I feel stifled and like I have to produce something very inefficient or convoluted.

    The worst I have seen is when, at work, I had to create bug tickets for a new system in a service desk to a third party, and they had a very excessive, guided, formalized submission form [for dumb users]. More than once, I wrote the exact same thing three times into three separate text boxes that required input. (Something like “describe what is wrong”, “describe what happens”, “describe how to reproduce”.) Something that I could have described well, concise, fully and correctly in one or two sentences or paragraphs became an excessively spread, formalized mess. I’m certainly not your average end user, but man that annoyed me. And the response of “we found this necessary” was certainly not for my kind of users, maybe not even experience with IT personnel.

    At work, I’m glad I have a small and close enough team where I can guide colleagues and new team members into good or at least decent practice.

    Checklists can be a good thing, if processes can be formalized, can serve as guidance for the developer, and proof of consideration for the reviewer. At the same time, they can feel inappropriate and like noise in other cases.

    I’ve been using horizontal line separators to separate description from test description and aside/scoping/wider context and considerations - maybe I will start adding headlines on those to be more explicit.