Improve the merge request guidelines and DoD in CONTRIBUTING.md

Signed-off-by: Rémy Coutable <remy@rymai.me>

1 files changed, 15 insertions, 11 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8cdf314ca4a..bd1e0d7f2f5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -439,13 +439,17 @@ request is as follows:
      "Description" field.
   1. If you are contributing documentation, choose `Documentation` from the
      "Choose a template" menu and fill in the template.
+  1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
+    `Closes #XXX` syntax to auto-close the issue(s) once the merge request will
+    be merged.
+1. If you're allowed to, set a relevant milestone and labels
 1. If the MR changes the UI it should include *Before* and *After* screenshots
 1. If the MR changes CSS classes please include the list of affected pages,
    `grep css-class ./app -R`
-1. Link any relevant [issues][ce-tracker] in the merge request description and
-   leave a comment on them with a link back to the MR
 1. Be prepared to answer questions and incorporate feedback even if requests
    for this arrive weeks or months after your MR submission
+  1. If a discussion has been addressed, select the "Resolve discussion" button
+    beneath it to mark it resolved.
 1. If your MR touches code that executes shell commands, reads or opens files or
    handles paths to files on disk, make sure it adheres to the
    [shell command guidelines](doc/development/shell_commands.md)
@@ -528,8 +532,7 @@ There are a few rules to get your merge request accepted:
 1. If you need polling to support real-time features, please use
    [polling with ETag caching][polling-etag].
 1. Changes after submitting the merge request should be in separate commits
-   (no squashing). If necessary, you will be asked to squash when the review is
-   over, before merging.
+   (no squashing).
 1. It conforms to the [style guides](#style-guides) and the following:
     - If your change touches a line that does not follow the style, modify the
       entire line to follow it. This prevents linting tools from generating warnings.
@@ -548,16 +551,16 @@ the feature you contribute through all of these steps.
 
 1. Description explaining the relevancy (see following item)
 1. Working and clean code that is commented where needed
-1. Unit and integration tests that pass on the CI server
+1. [Unit and system tests][testing] that pass on the CI server
 1. Performance/scalability implications have been considered, addressed, and tested
-1. [Documented][doc-styleguide] in the /doc directory
-1. Changelog entry added
+1. [Documented][doc-styleguide] in the `/doc` directory
+1. [Changelog entry added][changelog]
 1. Reviewed and any concerns are addressed
-1. Merged by the project lead
-1. Added to the release blog article
+1. Merged by a project maintainer
+1. Added to the release blog article if relevant
 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/) if relevant
 1. Community questions answered
-1. Answers to questions radiated (in docs/wiki/etc.)
+1. Answers to questions radiated (in docs/wiki/support etc.)
 
 If you add a dependency in GitLab (such as an operating system package) please
 consider updating the following and note the applicability of each in your
@@ -580,7 +583,7 @@ merge request:
     - string literal quoting style **Option A**: single quoted by default
 1.  [Rails](https://github.com/bbatsov/rails-style-guide)
 1.  [Newlines styleguide][newlines-styleguide]
-1.  [Testing](doc/development/testing.md)
+1.  [Testing][testing]
 1.  [JavaScript styleguide][js-styleguide]
 1.  [SCSS styleguide][scss-styleguide]
 1.  [Shell commands](doc/development/shell_commands.md) created by GitLab
@@ -657,6 +660,7 @@ available at [http://contributor-covenant.org/version/1/1/0/](http://contributor
 [license-finder-doc]: doc/development/licensing.md
 [GitLab Inc engineering workflow]: https://about.gitlab.com/handbook/engineering/workflow/#labelling-issues
 [polling-etag]: https://docs.gitlab.com/ce/development/polling.html
+[testing]: doc/development/testing.md
 
 [^1]: Please note that specs other than JavaScript specs are considered backend
       code.