1. 9

  2. 4

    One thing I changed in my work PRs is explaining in details why this PR exist and what are the big changes, what can break, what to pay attention to… instead of just referencing a ticket. I think it makes it easier to review.

    1. 7

      Having worked on a code base that is on its 3rd version control system and 4th ticketing system, I’ll tell you - put the comment in the commit message! It’s more likely that the info will survive there than migrated correctly in the ticketing system. This can make for some duplication, but isn’t too bad.

      The other point I usually make in favor of commit messages is that unlike other code comments, they reflect an exact point in time and

      1. 1

        they reflect an exact point in time and


        1. 3

          oops, thanks for catching that.

          an exact point in time and

          code changes afterwards might make them (obviously) out of sync with the comment. Regular comments can linger past the code they are commenting, but a commit message is tied to the code at that time.

      2. 4

        I have found that often my “rationale” sections on PRs are the longest-lasting written description of the business reasons behind changes. JIRA is not a reliable source of human information so much as it is a glorified to-do list on most projects I’ve been on.

      3. 2

        To encourage high quality PRs, I’ve started using a pull request template with just two sections to fill out - explicitly asking people to write down their motivation makes it so much easier to understand why a PR has just appeared out of the blue:

        <!-- PR title should start with '[fix]', '[improvement]' or '[break]' if this PR would cause a patch, minor or major SemVer bump. Omit the prefix if this PR doesn't warrant a standalone release. -->
        ## Before this PR
        <!-- Describe the problem you encountered with the current state of the world (or link to an issue) and why it's important to fix now. -->
        ## After this PR
        <!-- Describe at a high-level why this approach is better. -->
        <!-- Reference any existing GitHub issues, e.g. 'fixes #000' or 'relevant to #000' -->