Merge branch '346527-aqualls-refine-squash-merge' into 'master'

Revise commit templates page for tone and style

See merge request gitlab-org/gitlab!75579

app/views/projects/_merge_request_merge_commit_template.html.haml

@@ -3,7 +3,7 @@
 .form-group
   %b= s_('ProjectSettings|Merge commit message template')
   %p.text-secondary
-    - configure_the_merge_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md', anchor: 'merge-commit-message-template')
+    - configure_the_merge_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md')
     - configure_the_merge_commit_message_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_merge_commit_message_help_link_url }
     = s_('ProjectSettings|The commit message used when merging, if the merge method creates a merge commit. %{link_start}Learn more about syntax and variables.%{link_end}').html_safe % { link_start: configure_the_merge_commit_message_help_link_start, link_end: '</a>'.html_safe }
   .mb-2

app/views/projects/_merge_request_squash_commit_template.html.haml

@@ -3,7 +3,7 @@
 .form-group
   %b= s_('ProjectSettings|Squash commit message template')
   %p.text-secondary
-    - configure_the_squash_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md', anchor: 'squash-commit-message-template')
+    - configure_the_squash_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md')
     - configure_the_squash_commit_message_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_squash_commit_message_help_link_url }
     = s_('ProjectSettings|The commit message used when squashing commits. %{link_start}Learn more about syntax and variables.%{link_end}').html_safe % { link_start: configure_the_squash_commit_message_help_link_start, link_end: '</a>'.html_safe }
   .mb-2

doc/api/projects.md

@@ -1314,7 +1314,7 @@ POST /projects/user/:user_id
 | `jobs_enabled`                                              | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. |
 | `lfs_enabled`                                               | boolean | **{dotted-circle}** No | Enable LFS. |
 | `merge_commit_template`                                     | string  | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ |
-| `squash_commit_template`                                    | string  | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md#squash-commit-message-template) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ |
+| `squash_commit_template`                                    | string  | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ |
 | `merge_method`                                              | string  | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. |
 | `merge_requests_access_level`                               | string  | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. |
 | `merge_requests_enabled`                                    | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. |

doc/user/project/merge_requests/commit_templates.md

@@ -7,15 +7,42 @@ type: reference, howto
 
 # Commit message templates **(FREE)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.
+> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6.
 
-## Merge commit message template
+GitLab uses commit templates to create default messages for specific types of
+commits. These templates encourage commit messages to follow a particular format,
+or contain specific information. Users can override these templates when merging
+a merge request.
 
-As a project maintainer, you're able to configure merge commit message template. It will be used during merge to
-create commit message. Template uses similar syntax to 
+Commit templates use syntax similar to the syntax for
 [review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions).
 
-Default merge commit message can be recreated using following template:
+## Configure commit templates
+
+Change the commit templates for your project if the default templates don't
+contain the information you need.
+
+Prerequisite:
+
+- You must have at least the Maintainer role for a project.
+
+To do this:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > General** and expand **Merge requests**.
+1. Depending on the type of template you want to create, scroll to either
+   [**Merge commit message template**](#default-template-for-merge-commits) or
+   [**Squash commit message template**](#default-template-for-squash-commits).
+1. For your desired commit type, enter your default message. You can use both static
+   text and [variables](#supported-variables-in-commit-templates). Each template
+   is limited to a maximum of 500 characters, though after replacing the templates
+   with data, the final message may be longer.
+1. Select **Save changes**.
+
+## Default template for merge commits
+
+The default template for merge commit messages is:
 
 ```plaintext
 Merge branch '%{source_branch}' into '%{target_branch}'
@@ -27,40 +54,30 @@ Merge branch '%{source_branch}' into '%{target_branch}'
 See merge request %{reference}
 ```
 
-This commit message can be customized to follow any guidelines you might have.
-To do so, expand the **Merge requests** tab within your project's **General**
-settings and change the **Merge commit message template** text:
-
-![Custom commit message for merge commit](img/merge_commit_message_template_v14_5.png)
-
-You can use static text and following variables:
+## Default template for squash commits
 
-| Variable           | Description                                                                                                                                                                                                                               | Output example                                  |
-|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
-| `%{source_branch}` | The name of the branch that is being merged.                                                                                                                                                                                              | `my-feature-branch`                             |
-| `%{target_branch}` | The name of the branch that the changes are applied to.                                                                                                                                                                                   | `master`                                        |
-| `%{title}`         | Title of the merge request.                                                                                                                                                                                                               | Fix stuff                                       |
-| `%{issues}`        | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400`                    |
-| `%{description}`   | Description of the merge request.                                                                                                                                                                                                         | Merge request description.<br>Can be multiline. |
-| `%{reference}`     | Reference to the merge request.                                                                                                                                                                                                           | group-name/project-name!72359                                          |
-
-NOTE:
-Empty variables that are the only word in a line will be removed along with all newline characters preceding it.
+If you have configured your project to [squash commits on merge](squash_and_merge.md),
+GitLab creates a squash commit message with this template:
 
-Merge commit template field has a limit of 500 characters. This limit only applies to the template
-itself.
+```plaintext
+%{title}
+```
 
-## Squash commit message template
+## Supported variables in commit templates
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.
+Commit message templates support these variables:
 
-As a project maintainer, you're able to configure squash commit message template. It will be used during merge with
-squash to create squash commit message. It uses the same syntax and variables as merge commit message template.
+| Variable | Description | Output example |
+|----------|-------------|----------------|
+| `%{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` |
+| `%{title}`         | Title of the merge request. | `Fix tests and translations` |
+| `%{issues}`        | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` |
+| `%{description}`   | Description of the merge request. | `Merge request description.<br>Can be multiline.` |
+| `%{reference}`     | Reference to the merge request. | `group-name/project-name!72359` |
 
-![Custom commit message for squash commit](img/squash_commit_message_template_v14_6.png)
+Empty variables that are the only word in a line are removed, along with all newline characters preceding it.
 
-Default squash commit message can be recreated using following template:
+## Related topics
 
-```plaintext
-%{title}
-```
+- [Squash and merge](squash_and_merge.md).

doc/user/project/merge_requests/squash_and_merge.md

@@ -28,7 +28,8 @@ NOTE:
 The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in
 **Project Settings > General > Merge requests > Merge method > Fast-forward merge**.
 
-The squashed commit's default commit message is taken from the merge request title. It can be changed using [squash commit message template](commit_templates.md#squash-commit-message-template).
+The squashed commit's default commit message is taken from the merge request title.
+You can [edit the default message for squash commits](commit_templates.md).
 
 It can also be customized before merging a merge request.
 
@@ -123,6 +124,10 @@ NOTE:
 If your project is set to **Do not allow** Squash and Merge, the users still have the option to
 squash commits locally through the command line and force-push to their remote branch before merging.
 
+## Related topics
+
+- [Commit message templates](commit_templates.md).
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues