Skip to content

Add Reviewers Checklist to default MR template (say why not just what, team member announcements for important changes (controlled docs, etc.))

Michael Friedrich requested to merge default-mr-template-reviewers-checklist-transparency into master

Why is this change being made?

There are increasing numbers of handbook MRs that lack transparency (examples in !125765 (merged) and https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/34107) and miss to say why, not just what. Especially for controlled documents, transparency is required for team members to learn about changes async. Back and forth in Slack, and many different SSoTs is not transparent and inefficient, creating uncertainty.

We have discussed some ideas with codeowners review enforcements, following an update to update the review requirements for controlled documents. #32287 (comment 1378655775) cc @ipedowitz

This MR is part of the updates for controlled document reviews, and adds a general Reviewers Checklist to the default MR template which requires reviewers to follow a check list too.

  1. Review for transparency, and say why not just what.
  2. Review whether the change requires an announcement in Slack and the company newsletter.

This change warrants an update for all team members, when merged. Created another MR which updates the controlled document review section with the same guidelines: !127695 (merged)

Author Checklist

  • Provided a concise title for this Merge Request (MR)
  • Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
    • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
  • Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
    • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
    • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
    • The when to get approval handbook section explains the workflow in more detail
  • If the changes affect team members, or warrant an announcement in another way, please consider posting an update in #whats-happening-at-gitlab linking to this MR
    • If this is a change that directly impacts the majority of global team members, it should be a candidate for #company-fyi. Please work with internal communications and check the handbook for examples.
Edited by Michael Friedrich

Merge request reports