Announcement: Renaming default branch to "main"

[mitchdenny]

What is happening?

The Azure SDK Engineering System team will be renaming the default branch (currently master) to main across all of the following repositories:

• Azure/azure-sdk-for-net
• Azure/azure-sdk-for-java
• Azure/azure-sdk-for-python
• Azure/azure-sdk-for-js
• Azure/azure-sdk-for-c
• Azure/azure-sdk-for-cpp
• Azure/azure-sdk-for-go
• Azure/azure-sdk-for-android
• Azure/azure-sdk-for-ios
• Azure/azure-sdk-tools
• Azure/azure-sdk

Some of these repositories also have private mirrors, those will also have their default branch renamed. We will use the built-in GitHub branch rename procedure and then rapidly work to address any breakages in the engineering system (preparation work has been underway for some time but we don't expect that we've found all of the potential issues).

When issues are discovered we will be prioritizing fixes as they relate to the current priority order:

1. Pull request validation
2. Release capability
3. CI / nightly builds
4. Private repository mirroring

The current plan is that we will perform the rename operations using GitHub's built in rename feature. This will rename the branch and repoint any PRs that are currently pointed at the master branch to the new main branch. It will also automatically introduce redirects to any links that point directly to files on master.

When is it happening?

We will rename the branches starting the 18th of June, 2021 (updated). The rename itself will not take long, however we expect that various elements of the engineering system will experience temporary outages as we work to address any issues resulting from the rename. Our recovery priorities are listed in the section above.

What to expect?

We will be posting awareness issues in each of the repositories that we are renaming, linking back to this issue which we will edit to contain any updated information and guidance.

What happens to my existing pull requests?

After the rename has occurred, your existing pull requests from your forks to our upstream will be updated to point to main instead of master (if they were targeting master to begin with). When updating your existing pull requests you will continue to push to the branch you created in your fork.

What happens when I submit a new pull request?

When you submit a new pull request, it will automatically point to the main branch as this is the new default branch in the target repositories.

What happens when I need to rebase?

When you need to rebase, after the rename has occurred you will instead rebase onto the main branch. Because the main branch represents the same commit history as the master branch the rebase will work just as it would have previously, only the name of the branch has changed.

What happens when I need to switch back to the main branch to start new work?

That Azure SDK workflow recommends that contributors work off a fork of the repository that they are contributing to and then submit pull requests back to the upstream repository from a branch other than master, then switch back to master and pull updates from upstream when starting new work. Typically this means that your local workspace has two remotes (origin and upstream). Assuming the name of the upstream repository which points to the Azure/azure-sdk-for-[lang] repository is called upstream, you can use the following commands to pull down the new main branch references:

Step 1: Rename the master branch in your fork (for each repository)

Visit https://github.com/[your username]/azure-sdk-for-net/settings/branches and rename master to main.

1. If the pop-up comes up informing you the parent default branch has changed, click "branch settings"

2. Alternatively, you can click on "branches" next to the branch dropdown if the popup is gone or doesn't show.

3. In the branches view, click the pencil button on the right for "master" and rename it to "main"

Step 2: Execute these commands in your local clone of your fork.

# Pull down new main branch (upstream should point to main repo `https://github.com/Azure/azure-sdk*` and not your fork)
git fetch upstream # Pulls all the commits/references from the upstream repository into your local clone.
git checkout main # Your local workspace will now contain the contents of the latest 
git push origin main

# If you want to clean up your master branches
git branch --delete master

If you have any issues following these instructions please let us know ASAP so we can revise them as necessary.

What if I don't want to update my existing clones and I just want to start fresh.

You still need to rename master to main in your fork but after that you can follow the steps listed at https://azure.github.io/azure-sdk/policies_repobranching.html#clone-forked-repo to setup a new clone.

When can I submit a PR after the rename?

We would encourage you to submit PRs as soon as you are ready as part of your normal workflow. Your PRs will help us flush out any remaining issues following the rename, and getting the PR process up and running again is the top priority for the engineering systems team.

How to prepare?

There is not explicit steps you need to take with your local Git workspace prior to the rename of the repository. The section above outlines some steps that you will need to do with your local clone in order to start having the main branch available to create branches from.

However, if you are aware of automation, configuration in the repositories that you work in that may encounter a problem as a result of the rename, please let the Azure SDK Engineering System team know by commenting on this issue or contacting us via our teams channel. We will work with you to address the issue.

[kurtzeborn]

Removed the date from the title in case we move it again. Current plan is June 18th, 2021.

[scbedd]

I just realized there is an additional piece of work here that we need to track. It may pan out to just be an email to relevant folks, but need to ensure it doesn't get lost in the shuffle. @danieljurek @mitchdenny for FYI.

For these repos:

• azure-sdk-for-net
• azure-sdk-for-java
• azure-sdk-for-python
• azure-sdk-for-js

We have docs samples integration set up via webhook. What happens here is that any commit to master triggers the samples pipeline to run. It scans the repo for any samples, checks if there are changes, and if there ARE, publishes an update to their backing samples repo.