Update default template for merge requests to improve quality

Status

The template has been applied and is now in use.

The default template in GitLab is not handled via a file but via configuration. The secondary templates are managed via files.

I put the existing template and my proposed new one in a file so that we could collaborate on it via an MR, but applying it was not a merge request but instead a configuration update.

This is why this MR was closed vs being merged.

What are we planning to do?

We want to update the default template for merge requests to encourage behavior changes in order to improve quality via reducing technical debt at MR creation (vs later in the process). More details on a discussion on this topic here: https://docs.google.com/document/d/1Ncwg6h1DlFZPRU-CqWOqJMieAjElenJ46Z0G2EQ7j04/edit#

In order to do so, we are adding a checklist of items to remind authors and reviewers/maintainers what things should be considered from a quality perspective.

Why do we think this will work?

Using checklists has been proven to improve quality in not only engineering but also disciplines such as healthcare (surgery) and transportation (airline pilots). (More information on this in "checklist manifesto": http://atulgawande.com/book/the-checklist-manifesto/)

It is common to misconceive how checklists function in complex lines of work. They are not comprehensive how-to guides, whether for building a skyscraper or getting a plane out of trouble. They are quick and simple tools aimed to buttress the skills of expert professionals. - Atul Gawande

A checklist for checklists can be found here: https://www1.nyc.gov/assets/doh/downloads/pdf/em/gawande_checklist.pdf. Most notably for our checklist for software quality we have analyzed:

• Is a step that is critical and in danger of being missed?
• Is a step not adequately checked by other mechanisms?
• Is each step actionable?
• Has each step been concisely written and is it easy to understand?
• Does each section of the checklist have fewer than 10 items?
• Does each check detect potential errors at the time they can be corrected?
• Does the checklist fit the flow of work?

What is the process for vetting and doing the update?

This MR is being used to collaborate on updates to the default template for merge requests.

When complete, this MR will not be merged, as the template is stored via configuration per https://docs.gitlab.com/ee/user/project/description_templates.html#set-a-default-template-for-merge-requests-and-issues. Instead the default template will be updated here: https://gitlab.com/gitlab-org/gitlab/edit under Merge Requests : Default description template for merge requests

The current template has been copied to here: https://gitlab.com/gitlab-org/gitlab/-/blob/0f462b16bd7a0f10c01f880391305e7ee4e213d6/.gitlab/merge_request_templates/current_default_mr_template.md

The proposed template can be found here: !68892 (diffs)

Creation and initial review

• @whaber Creates the proposed template update
• @tstadelhofer reviews it and provides feedback
• @cdu1 reviews it and provides feedback
• @whaber Posts about it in #vp-development to ask for additional feedback
• @whaber Posts about it in EWIR (engineering week in review) to ask for additional feedback

Template update and socialization

ETA is to start this portion is 6-Sep based on vacation schedules.

• @whaber Review and consider all feedback received so far
• @whaber Create a short youtube video describing the why and what of the change and announce the change in Slack and EWIR
• @whaber Updates the template

Measuring impact

After it is updated and is in use for a while (a month?) the effectiveness of the updates will be measured (in terms of both the reduction in technical debt and in the extra work it creates for the MR authors, reviewers, and maintainers).

Screenshots or Screencasts (strongly suggested)

Before

After

cc @clefelhocz1