Skip to content

Update the default MR template: Say why, Slack documentation and announcement suggestions

Problem to solve

The current template includes a Why and Checklist section, both are sometimes not used or used to say what, not why. An example is in !85905 (comment 620970134)

Handbook updates can change a policy, or may be of interest for all team members, requiring an announcement in Slack or notifying a specific group or department.

Proposed Changes

To follow our transparency and efficiency value, I suggest the following changes to the default MR template.

Note: This is configured in the project settings as Markdown text, and not available in the .gitlab/merge_request_templates directory

image

Since this change affects the default MR template for both, the handbook and the website in this monorepo, assigning multiple DRIs to discuss and review. I have maintainer access and can make the edits after approval.

Current template

<!--Before proceeding, please check if you need to apply a specific MR description template from the dropdown menu above next to `Description` (e.g. blog post, website bug report).-->

## Why is this change being made?

<!--
Provide a detailed answer to question on why this change is being proposed, in accordance with our value of [Transparency][transparency].
-->

## Author Checklist
- [ ] Provided a concise title for the MR
- [ ] Added a description to this MR explaining the reasons for the proposed change, per [say-why-not-just-what][transparency]
- [ ] Assign this change to the correct 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 in 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][mr-buddies-slack].
    - ~~If the changes relate to any part of the project other than updates to content and/or data files please make sure to ping `@gl-static-site-editor` in a comment for a review and merge. For example changes to `.gitlab-ci.yml`, JavaScript/CSS/Ruby code or the layout files.~~ (this requirement has been removed pending identification of a new DRI for the handbook)

<!-- DO NOT REMOVE -->
[transparency]: https://about.gitlab.com/handbook/values/#transparency
[mr-buddies-slack]: https://gitlab.slack.com/archives/CLM8K5LF4

Proposed Template

  • More clear instructions on the why section
  • Instruct that Slack is not a knowledge base, document the conversation in the MR
  • Assign reviewers, instead of MR assignees
  • Add suggestion for announcements in Slack when applicable
<!-- Before proceeding, please check if you need to apply a specific MR description template from the dropdown menu above next to `Description` (e.g. blog post, website bug report). -->

## Why is this change being made?

<!--
Provide a detailed answer to question on **why** this change is being proposed, in accordance with our value of [Transparency][transparency].

Example: `We have discussed the topic in Slack - (copy of Slack conversation). The current process is not efficient, this MR makes the description of X more clear, and helps move Y forward.`
-->

## Author Checklist

<!-- Please verify the check list and ensure to tick them off before the MR is merged. -->

- [ ] Provided a concise title for the MR
- [ ] Added a description to this MR explaining the reasons for the proposed change, per [say-why-not-just-what][transparency]
  - Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added.
- [ ] Assign reviewers for this change to the correct DRI(s)
    - 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 in 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][mr-buddies-slack].
    - ~~If the changes relate to any part of the project other than updates to content and/or data files please make sure to ping `@gl-static-site-editor` in a comment for a review and merge. For example changes to `.gitlab-ci.yml`, JavaScript/CSS/Ruby code or the layout files.~~ (this requirement has been removed pending identification of a new DRI for the handbook)
- [ ] If the changes affect team members, or warrant an announcement in another way, please consider posting an update in [#whats-happening-at-gitlab][whats-happening-at-gitlab-slack] 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](company-fyi-slack). Please work with [internal communications](internal-communications) and check the handbook for examples. 

<!-- DO NOT REMOVE -->
[transparency]: https://about.gitlab.com/handbook/values/#transparency
[internal-communications]: https://about.gitlab.com/handbook/communication/internal-communications/
[mr-buddies-slack]: https://gitlab.slack.com/archives/CLM8K5LF4
[company-fyi-slack]: https://gitlab.slack.com/archives/C010XFJFTHN
[whats-happening-at-gitlab-slack]: https://gitlab.slack.com/archives/C0259241C

Diff View

Note: This is a manual diff using Markdown formatting, it helps with review and "simulates" a MR diff. Needs updates if the text above changes.

-<!--Before proceeding, please check if you need to apply a specific MR description template from the dropdown menu above next to `Description` (e.g. blog post, website bug report).-->
+<!-- Before proceeding, please check if you need to apply a specific MR description template from the dropdown menu above next to `Description` (e.g. blog post, website bug report). -->

 ## Why is this change being made?

 <!-- 
-Provide a detailed answer to question on why this change is being proposed, in accordance with our value of [Transparency][transparency].
+Provide a detailed answer to question on **why** this change is being proposed, in accordance with our value of [Transparency][transparency].
+
+Example: `We have discussed the topic in Slack - (copy of Slack conversation). The current process is not efficient, this MR makes the description of X more clear, and helps move Y forward.`
 -->

 ## Author Checklist
+
+<!-- Please verify the check list and ensure to tick them off before the MR is merged. -->
+
 - [ ] Provided a concise title for the MR
 - [ ] Added a description to this MR explaining the reasons for the proposed change, per [say-why-not-just-what][transparency]
+  - Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added.
-- [ ] Assign this change to the correct DRI
+- [ ] Assign reviewers for this change to the correct DRI(s)
     - 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 in 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][mr-buddies-slack].
     - ~~If the changes relate to any part of the project other than updates to content and/or data files please make sure to ping `@gl-static-site-editor` in a comment for a review and merge. For example changes to `.gitlab-ci.yml`, JavaScript/CSS/Ruby code or the layout files.~~ (this requirement has been removed pending identification of a new DRI for the handbook)
+- [ ] If the changes affect team members, or warrant an announcement in another way, please consider posting an update in [#whats-happening-at-gitlab][whats-happening-at-gitlab-slack] 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](company-fyi-slack). Please work with [internal communications](internal-communications) and check the handbook for examples.
 
 <!-- DO NOT REMOVE -->
[transparency]: https://about.gitlab.com/handbook/values/#transparency
+[internal-communications]: https://about.gitlab.com/handbook/communication/internal-communications/
[mr-buddies-slack]: https://gitlab.slack.com/archives/CLM8K5LF4
+[company-fyi-slack]: https://gitlab.slack.com/archives/C010XFJFTHN
+[whats-happening-at-gitlab-slack]: https://gitlab.slack.com/archives/C0259241C
Edited by Michael Friedrich