Merge branch 'branch-name/docs' into 'master'

Add documentation for the default initial branch name setting

Closes #221013

See merge request gitlab-org/gitlab!35659

doc/user/admin_area/settings/index.md

@@ -43,6 +43,7 @@ Access the default page for admin area settings by navigating to
 
 | Option | Description |
 | ------ | ----------- |
+| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name-core-only) | Set a custom branch name rather than master for all the new repositories created within your instance. |
 | [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. |
 | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. |
 | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. |

doc/user/project/repository/branches/index.md

@@ -41,17 +41,51 @@ See also:
 ## Default branch
 
 When you create a new [project](../../index.md), GitLab sets `master` as the default
-branch for your project. You can choose another branch to be your project's
+branch of the repository. You can choose another branch to be your project's
 default under your project's **Settings > Repository**.
 
-The default branch is the branch affected by the
-[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
-which means that _an issue will be closed when a merge request is merged to
-the **default branch**_.
+When closing issues directly from merge requests through the [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
+the target is the project's **default branch**.
 
-The default branch is also protected against accidental deletion. Read through
-the documentation on [protected branches](../../protected_branches.md#protected-branches)
-to learn more.
+The default branch is also initially [protected](../../protected_branches.md#protected-branches)
+against accidental deletion and forced pushes.
+
+### Custom initial branch name **(CORE ONLY)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2.
+> - It's deployed behind a feature flag, enabled by default.
+> - It's enabled on GitLab.com.
+> - It cannot be enabled or disabled per-project.
+> - It's recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name-core-only). **(CORE ONLY)**
+
+By default, when you create a new project in GitLab, the initial branch is called `master`.
+For self-managed instances, a GitLab administrator can customize the initial branch name to something
+else. This way, every new project created from then on will start from the custom branch name rather than `master`. To do so:
+
+1. Go to the **{admin}** **Admin Area > Settings > Repository** and expand **Default initial
+   branch name**.
+1. Change the default initial branch to a custom name of your choice.
+1. **Save Changes**.
+
+#### Enable or disable custom initial branch name **(CORE ONLY)**
+
+Setting the default initial branch name is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md)
+can opt to disable it for your instance.
+
+To disable it:
+
+```ruby
+Feature.disable(:global_default_branch_name)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:global_default_branch_name)
+```
 
 ## Compare