Announcement: Renaming default branch to "main"

[zhenglaizhang]

What is happening?

The Azure SDK Swagger & Tools team will be renaming the default branch (currently master) to main for the following repo:

• Azure/azure-rest-api-specs

This repo will 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

General renaming plan

1. We already prepared the main branch which is syncing daily with master branch
2. Downstream dependents update their services or pipelines to point to the main branch if their business logic permits or use the GitHub repo API to get default branch (e.g. https://api.github.com/repos/azure/azure-rest-api-specs), this is to decouple the original tight coupling between the master branch with downstream ahead of time.
3. During the renaming, we will firstly delete the main branch in this repo, and then 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.
4. We will update the spec repo related PR validation pipelines, and repository mirroring to point to the new main branch

When is it happening?

We will rename the branches starting the 2021-08-02 9:00 AM GMT+8. 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 we need your help?

To prepare for the smooth default branch renaming, we need your help on following aspects:

1. If you are aware of downstream partners, 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 Swagger & Tools team know by commenting on this issue. We will work with you to address the issue.
2. If you own any downstream consumers of the spec repo master branch, please update it to point to main branch or use the default_branch of GitHub repo API response, mentioned above, before the renaming date 30th of July, 2021.
3. Right after the renaming, you need update your local fork to switch to work on main branch, detailed steps will be listed as below.
4. If you own any wiki or documentation hard code the master branch, you need to update if applicable. Note GitHub already supports Links to deleted branches now redirect to the default branch

What to expect?

We will be posting the progress in 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 spec repo review 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-rest-api-specs 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-rest-api-specs/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-rest-api-specs` 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 below to setup a new clone.

# clone your forked repo locally which will setup your origin remote
git clone https://github.com/<your-github-username>/azure-rest-api-specs.git

# add an upstream remote to the main repository.
cd azure-rest-api-specs
git remote add upstream https://github.com/Azure/azure-rest-api-specs.git

git remote -v
# origin    https://github.com/<your-github-username>/azure-rest-api-specs.git (fetch)
# origin    https://github.com/<your-github-username>/azure-rest-api-specs.git (push)
# upstream  https://github.com/Azure/azure-rest-api-specs.git (fetch)
# upstream  https://github.com/Azure/azure-rest-api-specs.git (push)

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.

[leni-msft]

We already prepared the main branch which is syncing daily with master branch

@anthony-c-martin @jorgecotillo Please be aware of the default branch renaming and modify the schema auto-gen pipeline for both ARM template and Bicep.

[zhenglaizhang]

@mikhailshilkov Please be aware of this, and check if this will impact native Pulumi Azure provider generation, if so please help do accordingly.

[mikhailshilkov]

@zhenglaizhang thank you for the heads-up, we will adjust our integration accordingly 👍

[anthony-c-martin]

We already prepared the main branch which is syncing daily with master branch

@anthony-c-martin @jorgecotillo Please be aware of the default branch renaming and modify the schema auto-gen pipeline for both ARM template and Bicep.

Thanks for the heads-up!

[zhenglaizhang]

We already prepared the main branch which is syncing daily with master branch

@anthony-c-martin @jorgecotillo Please be aware of the default branch renaming and modify the schema auto-gen pipeline for both ARM template and Bicep.

Thanks for the heads-up!

Hi @anthony-c-martin any updates for schema auto-gen pipeline? I noticed that you have create one PR to update but not merged yet.

[zhenglaizhang]

@zhenglaizhang thank you for the heads-up, we will adjust our integration accordingly 👍

Hi @mikhailshilkov any update on your side?

[mikhailshilkov]

@zhenglaizhang We are ready to change it as soon as you do, so we shouldn't block you.

[anthony-c-martin]

We already prepared the main branch which is syncing daily with master branch

@anthony-c-martin @jorgecotillo Please be aware of the default branch renaming and modify the schema auto-gen pipeline for both ARM template and Bicep.

Thanks for the heads-up!

Hi @anthony-c-martin any updates for schema auto-gen pipeline? I noticed that you have create one PR to update but not merged yet.

Submitted Azure/azure-resource-manager-schemas#1810 for this, but no need to wait for us.

[zhenglaizhang]

To minimal potential risk, we decided to update the branch renaming time from 2021-07-30 to 2021-08-02

[zhenglaizhang]

Hi all, now the spec repo default branch has been renamed as main.
Thanks for all your support!

[zhenglaizhang]

As now the renaming is done, and no other issues, closing the PR.