Create a new page describing default branches

The information about default branches is about to become very
important; start carving it off into its own page.

doc/api/groups.md

@@ -769,7 +769,7 @@ Parameters:
 
 ### Options for `default_branch_protection`
 
-The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable master branch, as described in the following table:
+The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table:
 
 | Value | Description |
 |-------|-------------------------------------------------------------------------------------------------------------|

doc/api/projects.md

@@ -1127,7 +1127,7 @@ POST /projects
 | `ci_config_path`                                            | string  | **{dotted-circle}** No | The path to CI configuration file. |
 | `container_expiration_policy_attributes`                    | hash    | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
 | `container_registry_enabled`                                | boolean | **{dotted-circle}** No | Enable container registry for this project. |
-| `default_branch`                                            | string  | **{dotted-circle}** No | `master` by default. |
+| `default_branch`                                            | string  | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
 | `description`                                               | string  | **{dotted-circle}** No | Short project description. |
 | `emails_disabled`                                           | boolean | **{dotted-circle}** No | Disable email notifications. |
 | `external_authorization_classification_label` **(PREMIUM)** | string  | **{dotted-circle}** No | The classification label for the project. |
@@ -1276,7 +1276,7 @@ PUT /projects/:id
 | `ci_forward_deployment_enabled`                             | boolean        | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending |
 | `container_expiration_policy_attributes`                    | hash           | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). |
 | `container_registry_enabled`                                | boolean        | **{dotted-circle}** No | Enable container registry for this project. |
-| `default_branch`                                            | string         | **{dotted-circle}** No | `master` by default. |
+| `default_branch`                                            | string         | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. |
 | `description`                                               | string         | **{dotted-circle}** No | Short project description. |
 | `emails_disabled`                                           | boolean        | **{dotted-circle}** No | Disable email notifications. |
 | `external_authorization_classification_label` **(PREMIUM)** | string         | **{dotted-circle}** No | The classification label for the project. |

doc/user/admin_area/settings/index.md

@@ -46,7 +46,7 @@ Access the default page for admin area settings by navigating to **Admin Area >
 
 | Option | Description |
 | ------ | ----------- |
-| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name) | Set a custom branch name rather than master for all the new repositories created within your instance. |
+| [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) | Set a custom branch name for new repositories created in 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/application_security/security_dashboard/index.md

@@ -152,7 +152,7 @@ found in those projects' default branches.
 ## Keeping the dashboards up to date
 
 The Security Dashboard displays information from the results of the most recent
-security scan on the [default branch](../../project/repository/branches/index.md#default-branch),
+security scan on the [default branch](../../project/repository/branches/default.md),
 which means that security scans are performed every time the branch is updated.
 
 If the default branch is updated infrequently, scans are run infrequently and the

doc/user/group/index.md

@@ -387,16 +387,10 @@ because the project cannot be moved.
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6.
 
-By default, when you create a new project in GitLab, the initial branch is called `master`.
-For groups, a group owner can customize the initial branch name to something
-else. This way, every new project created under that group from then on starts from the custom branch name rather than `master`.
-
-To use a custom name for the initial branch:
-
-1. Go to the group's **Settings > Repository** page.
-1. Expand the **Default initial branch name** section.
-1. Change the default initial branch to a custom name of your choice.
-1. Select **Save changes**.
+When you create a new project in GitLab, a default branch is created with the
+first push. The group owner can
+[customize the initial branch](../project/repository/branches/default.md#group-level-custom-initial-branch-name)
+for the group's projects to meet your group's needs.
 
 ## Remove a group
 
@@ -467,7 +461,7 @@ For more information, [see this issue](https://gitlab.com/gitlab-org/gitlab/-/is
 
 To ensure only people from your organization can access particular
 resources, you can restrict access to groups by IP address. This setting applies to all subgroups,
-projects, issues, and so on. 
+projects, issues, and so on.
 
 IP access restrictions can be configured at the group level only.
 

doc/user/group/repositories_analytics/index.md

@@ -69,7 +69,7 @@ For each day that a coverage report was generated by a job in a project's pipeli
 If the project's code coverage was calculated more than once in a day, we will take the last value from that day.
 
 NOTE:
-[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch.
+[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md). In earlier versions, it is taken from the `master` branch.
 
 <!-- ## Troubleshooting
 

doc/user/project/issues/managing_issues.md

@@ -199,7 +199,7 @@ can be closed automatically when the commit reaches the project's default branch
 
 If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern),
 all issues referenced in the matched text are closed. This happens when the commit
-is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch),
+is pushed to a project's [**default** branch](../repository/branches/default.md),
 or when a commit or merge request is merged into it.
 
 For example, if `Closes #4, #6, Related to #5` is included in a Merge Request

doc/user/project/protected_branches.md

@@ -26,7 +26,7 @@ By default, a protected branch does these things:
 - GitLab administrators are allowed to push to the protected branches.
 - Users with [Developer permissions](../permissions.md) are allowed to
   create a project in a group, but might not be allowed to initially
-  push to the [default branch](repository/branches/index.md#default-branch).
+  push to the [default branch](repository/branches/default.md).
 
 The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
 

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

+---
+stage: Create
+group: Source Code
+info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
+type: concepts, howto
+---
+
+# Default branch
+
+When you create a new [project](../../index.md), GitLab creates a default branch
+in the repository. A default branch has special configuration options not shared
+by other branches:
+
+- It's [initially protected](../../protected_branches.md#protected-branches) against
+  accidental deletion and forced pushes.
+- When a merge request uses an
+  [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically)
+  to close an issue, the work is merged into this branch.
+
+The name of your [new project's](../../index.md) default branch depends on any
+instance-level or group-level configuration changes made by your GitLab administrator.
+GitLab checks first for specific customizations, then checks at a broader level,
+using the GitLab default only if no customizations are set:
+
+1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name.
+1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name.
+1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name.
+1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)**
+1. If no custom default branch name is set at any level, GitLab defaults to:
+   - `main`: Projects created with GitLab 14.0 or later.
+   - `master`: Projects created before GitLab 14.0.
+
+In the GitLab UI, you can change the defaults at any level. GitLab also provides
+the [Git commands you need](#update-the-default-branch-name-in-your-repository) to update your copy of the repository.
+
+## Change the default branch name for a project
+
+To update the default branch name for an individual [project](../../index.md):
+
+1. Sign in to GitLab as a user with [Administrator](../../../permissions.md) permissions.
+1. In the left navigation menu, go to **Settings > Repository**.
+1. Expand **Default branch**, and select a new default branch.
+1. (Optional) Select the **Auto-close referenced issues on default branch** check box to close
+   issues when a merge request
+   [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically).
+1. Select **Save changes**.
+
+API users can also use the `default_branch` attribute of the
+[Projects API](../../../../api/projects.md) when creating or editing a project.
+
+## Change the default branch name for an instance or group
+
+GitLab administrators can configure a new default branch name at the
+[instance level](#instance-level-custom-initial-branch-name) or
+[group level](#group-level-custom-initial-branch-name).
+
+### Instance-level custom initial branch name **(FREE SELF)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2.
+> - It's deployed behind a feature flag, enabled by default.
+> - 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).
+
+GitLab [administrators](../../../permissions.md) of self-managed instances can
+customize the initial branch for projects hosted on that instance. Individual
+groups and subgroups can override this instance-wide setting for their projects.
+
+1. Go to **Admin Area > Settings > Repository**.
+1. Expand **Default initial branch name**.
+1. Change the default initial branch to a custom name of your choice.
+1. Select **Save changes**.
+
+Projects created on this instance after you change the setting use the
+custom branch name, unless a group-level or subgroup-level configuration
+overrides it.
+
+#### Enable or disable custom initial branch name **(FREE SELF)**
+
+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)
+```
+
+### Group-level custom initial branch name **(FREE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6.
+
+Administrators of groups and subgroups can configure the default branch name for a group:
+
+1. Go to the group **Settings > Repository**.
+1. Expand **Default initial branch name**.
+1. Change the default initial branch to a custom name of your choice.
+1. Select **Save changes**.
+
+Projects created in this group after you change the setting use the custom branch name,
+unless a subgroup configuration overrides it.
+
+## Update the default branch name in your repository
+
+WARNING:
+Changing the name of your default branch can potentially break tests,
+CI/CD configuration, services, helper utilities, and any integrations your repository
+uses. Before you change this branch name, consult with your project owners and maintainers.
+Ensure they understand the scope of this change includes references to the old
+branch name in related code and scripts.
+
+When changing the default branch name for an existing repository, you should preserve
+the history of your default branch by renaming it, instead of deleting it. This example
+renames a Git repository's (`example`) default branch.
+
+1. On your local command line, navigate to your `example` repository, and ensure
+   you're on the default branch:
+
+   ```plaintext
+   cd example
+   git checkout master
+   ```
+
+1. Rename the existing default branch to the new name (`main`). The argument `-m`
+   transfers all commit history to the new branch:
+
+   ```plaintext
+   git branch -m master main
+   ```
+
+1. Push the newly created `main` branch upstream, and set your local branch to track
+   the remote branch with the same name:
+
+   ```plaintext
+   git push -u origin main
+   ```
+
+1. If you plan to remove the old default branch, update `HEAD` to point to your new default branch, `main`:
+
+   ```plaintext
+   git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
+   ```
+
+1. Sign in to GitLab as an [administrator](../../../permissions.md) and follow
+   the instructions to
+   [change the default branch for this project](#change-the-default-branch-name-for-a-project).
+   Select `main` as your new default branch.
+1. Protect your new `main` branch as described in the [protected branches documentation](../../protected_branches.md).
+1. (Optional) If you want to delete the old default branch:
+   1. Verify that nothing is pointing to it.
+   1. Delete the branch on the remote:
+
+      ```plaintext
+      git push origin --delete master
+      ```
+
+      You can delete the branch at a later time, after you confirm the new default branch is working as expected.
+
+1. Notify your project contributors of this change, because they must also take some steps:
+
+   - Contributors should pull the new default branch to their local copy of the repository.
+   - Contributors with open merge requests that target the old default branch should manually
+     re-point the merge requests to use `main` instead.
+1. In your repository, update any references to the old branch name in your code.
+1. Update references to the old branch name in related code and scripts that reside outside
+   your repository, such as helper utilities and integrations.
+
+## Resources
+
+- [Discussion of default branch renaming](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/)
+  on the Git mailing list
+- [March 2021 blog post: The new Git default branch name](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/)

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

@@ -24,7 +24,9 @@ With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request
 
 For more information on managing branches using the GitLab UI, see:
 
-- [Default branches](#default-branch)
+- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a
+  default branch for the repository. You can change this setting at the project,
+  subgroup, group, or instance level.
 - [Create a branch](../web_editor.md#create-a-new-branch)
 - [Protected branches](../../protected_branches.md#protected-branches)
 - [Delete merged branches](#delete-merged-branches)
@@ -41,55 +43,6 @@ See also:
 - [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation.
 - [Getting started with Git](../../../../topics/git/index.md) and GitLab.
 
-## Default branch
-
-When you create a new [project](../../index.md), GitLab sets `master` as the default
-branch of the repository. You can choose another branch to be your project's
-default under your project's **Settings > Repository**.
-
-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 initially [protected](../../protected_branches.md#protected-branches)
-against accidental deletion and forced pushes.
-
-### Custom initial branch name **(FREE SELF)**
-
-> - [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). **(FREE SELF)**
-
-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 starts from the custom branch name rather than `master`. To do so:
-
-1. Go to the **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 **(FREE SELF)**
-
-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
 
 To compare branches in a repository:

doc/user/project/settings/index.md

@@ -21,7 +21,7 @@ functionality of a project.
 
 ### General project settings
 
-Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and topics:
+Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics:
 
 ![general project settings](img/general_settings.png)
 

ee/app/views/projects/settings/ci_cd/_pipeline_subscriptions.html.haml

@@ -9,7 +9,7 @@
     %button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
       = expanded ? _('Collapse') : _('Expand')
     %p
-      - default_branch_docs = link_to(_("default branch"), help_page_path('user/project/repository/branches/index.md', anchor: 'default-branch'))
+      - default_branch_docs = link_to(_("default branch"), help_page_path('user/project/repository/branches/default.md'))
       = _("Pipeline subscriptions trigger a new pipeline on the default branch of this project when a pipeline successfully completes for a new tag on the %{default_branch_docs} of the subscribed project.").html_safe % { default_branch_docs: default_branch_docs }
     %p
       = _("A limit of %{ci_project_subscriptions_limit} subscriptions to or from a project applies.").html_safe % { ci_project_subscriptions_limit: @project.actual_limits.ci_project_subscriptions }