Build in table of MR template inheritance

To close off an old, old problem, let's describe the inheritance
of merge request templates.

doc/user/project/description_templates.md

@@ -46,10 +46,11 @@ and see if you can find your description template in the **Choose a template** d
 ## Create a merge request template
 
 Similarly to issue templates, create a new Markdown (`.md`) file inside the
-`.gitlab/merge_request_templates/` directory in your repository. Commit and
-push to your default branch.
+`.gitlab/merge_request_templates/` directory in your repository. Unlike issue
+templates, merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md)
+that depend on the contents of commit messages and branch names.
 
-To create a merge request description template:
+To create a merge request description template for a project:
 
 1. On the top bar, select **Main menu > Projects** and find your project.
 1. On the left sidebar, select **Repository**.
@@ -99,7 +100,7 @@ your merge request template with their values:
 | `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.` |
 | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` |
 | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` |
-| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` |
+| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md` <br><br> `Improved project description in readme file.` |
 | `%{source_branch}` | The name of the branch being merged. | `my-feature-branch`  |
 | `%{target_branch}` | The name of the branch that the changes are applied to. | `main` |
 
@@ -180,7 +181,7 @@ You can also provide `issues_template` and `merge_requests_template` attributes
 
 #### Priority of default description templates
 
-When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues)
+When you set [issue description templates](#set-a-default-template-for-merge-requests-and-issues)
 in various places, they have the following priorities in a project.
 The ones higher up override the ones below:
 
@@ -188,6 +189,9 @@ The ones higher up override the ones below:
 1. `Default.md` (case insensitive) from the parent group.
 1. `Default.md` (case insensitive) from the project repository.
 
+Merge requests have [additional inheritance rules](merge_requests/creating_merge_requests.md)
+that depend on the contents of commit messages and branch names.
+
 ## Example description template
 
 We use description templates for issues and merge requests in the

doc/user/project/merge_requests/creating_merge_requests.md

@@ -11,7 +11,7 @@ GitLab provides many different ways to create a merge request.
 
 NOTE:
 GitLab enforces [branch naming rules](../repository/branches/index.md#name-your-branch)
-to prevent problems, and provides 
+to prevent problems, and provides
 [branch naming patterns](../repository/branches/index.md#prefix-branch-names-with-issue-numbers)
 to streamline merge request creation.
 

doc/user/project/merge_requests/index.md

@@ -26,6 +26,22 @@ view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE).
 
 Learn the various ways to [create a merge request](creating_merge_requests.md).
 
+### Use merge request templates
+
+When you create a merge request, GitLab checks for the existence of a
+[description template](../description_templates.md) to add data to your merge request.
+GitLab checks these locations in order from 1 to 5, and applies the first template
+found to your merge request:
+
+| Name | Project UI<br>setting | Group<br>`default.md` | Instance<br>`default.md` | Project<br>`default.md` | No template |
+| :-- | :--: | :--: | :--: | :--: | :--: |
+| Standard commit message | 1 | 2 | 3 | 4 | 5 |
+| Commit message with an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) like `Closes #1234` | 1 | 2 | 3 | 4 | 5 \* |
+| Branch name [prefixed with an issue ID](../repository/branches/index.md#prefix-branch-names-with-issue-numbers), like `1234-example` | 1 \* | 2 \* | 3 \* | 4 \* | 5 \* |
+
+NOTE:
+Items marked with an asterisk (\*) also append an [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically).
+
 ## View merge requests
 
 You can view merge requests for your project, group, or yourself.