Merge request conventions for less cognitive load

After listening to Episode 18 of the Word Wrap Podcast, I was inspired to come up with a set of conventions for our internal merge request reviewing.

Each comment within a review will be prefixed with a category - this speeds up the review and also allows the developer receiving the feedback to compartmentalise the comments and address them in sections.

For example, one of the categories is discussion - this is a prompt for the developer to add the comment to be discussed in the next appropriate development meeting. This saves me having to type "not to be actioned but one for discussion" or similar and also allows the dev to skip over that point and address later.

The categories below are originally taken from Conventional Comments and adapted for our use.

  • suggestion - This is a non-blocking suggestion or update, it might be a "If I was doing this I would..." kind of comment or something that could change for future scaleability
  • issue - This is blocking and should be addressed before deployment
  • discussion - To be added as a discussion item in the next appropriate meeting (Dev club, Backend Developers Club etc.)
  • conventions - Non-blocking but it would be a change to bring it into line with our conventions (e.g case, indentation or file location change)
  • question - Genuine intrigue as to why a decision was made or checking edge cases had been considered
  • follow-up - Unrelated to this specific task, but this other thing was noted/found/discovered which should be a separate action point

View this post on Github

You might also enjoy…

Mike Street

Written by Mike Street

Mike is a CTO and Lead Developer from Brighton, UK. He spends his time writing, cycling and coding. You can find Mike on Mastodon.