Skip to main content

Bioconductor Packages: Development, Maintenance, and Peer Review

27 Branch Rename FAQs

The Bioconductor project has chosen ‘devel’ to be the default branch for GitHub and git repositories. To prepare for this transition, we have compiled a list of Frequently Asked Questions (FAQs) below with instructions on how to rename the default branch both on local clones and on GitHub.

27.1 What is changing?

The Bioconductor core team will only rename the default branch to ‘devel’ on the Bioconductor git repository at git.bioconductor.org. All other repository clones including those on hosting platforms such as GitHub, GitLabs, etc. will not be directly affected by the core team’s change; however, we highly recommend that maintainers and developers update their local and cloud repository clones to match the default branch name.

27.2 Who is affected by this change?

Bioconductor developers and maintainers are affected by this change. Bioconductor users are not affected.

27.3 What repositories are affected by this change?

Note that there may exist several clones of a single repository, e.g., on different servers and workstations. Only the repository that resides in the Bioconductor server hosted at git.bioconductor.org will be affected. The default branch for all packages in the Bioconductor git server will be set to devel. Maintainers and collaborators will be responsible for updating local and cloud repository clones.

We recommend synchronizing the default branch changes to the GitHub-hosted repository to simplify workflows.

For typical setup scenarios, see the tidyverse blog post.

27.4 What do I need to change?

We recommend Bioconductor developers to rename default branches on their local repositories to ‘devel’. Optionally (and highly encouraged), GitHub and other local copies of affected repositories, including those from collaborators, should have their branches renamed.

Bioconductor users will not need to do anything.

Note. The minority of maintainers without a GitHub repository should rename and set the ‘HEAD’ as follows:

git branch -m master devel
git fetch origin
git branch -u origin/devel devel
git remote set-head origin -a

All other maintainers with GitHub repositories should see the sections How do I set ‘devel’ as the default branch on GitHub? and How do I set ‘devel’ as the default local ’branch?, respectively.

27.5 What if I am an RStudio user?

Maintainers that use RStudio should be familiar with running git commands via the Terminal tab in RStudio. The commands shown in this documentation can be entered in the Terminal tab, e.g., git fetch --all to obtain all updates from available remotes.

27.6 What if I create a fresh clone of my repository?

It is possible to create a fresh clone of the repository but you may lose any working changes in the old local repository. This should only be done if you are comfortable with git and would like to start afresh. You will also need to set up the git remotes as below.

27.7 What should my Git remotes look like?

As a reminder, maintainers who use GitHub should have the following recommended setup. The command git remote -v should display an origin remote that points to the GitHub location and an upstream remote that points to the Bioconductor git repository. For example, this is the set up for BiocGenerics:

git remote -v
# origin    git@github.com:Bioconductor/BiocGenerics (fetch)
# origin    git@github.com:Bioconductor/BiocGenerics (push)
# upstream  git@git.bioconductor.org:packages/BiocGenerics (fetch)
# upstream  git@git.bioconductor.org:packages/BiocGenerics (push)

Note. As maintainers, we use the SSH protocol for both remotes.

27.8 How do I sync my Git remotes?

Before making updates to local branches, make sure that both remotes origin and upstream are in sync with:

git checkout master
git pull origin master
git pull upstream devel:master

Note. These commands are to be run on the old local repository and do not apply to freshly cloned repositories.

27.9 How do I set ‘devel’ as the default branch on GitHub?

For maintainers who manage GitHub repositories and would like to use streamlined commands, we recommend synchronizing the default branch changes to their GitHub repositories. To this end, GitHub has provided a convenient way to rename the default branch of any repository. First, go to https://github.com/{username}/{repo}/branches where username and repo correspond to your GitHub username and repository, respectively.

Then, click on the ‘edit’ pencil 🖊 to rename the branch (seen here at the bottom right corner) and rename the branch to ‘devel’:

That’s it! The default branch on GitHub is now set to devel.

Follow the instructions in the How do I set ‘devel’ as the default local branch? to sync local repository clones.

27.10 What if I already have a ‘devel’ branch on GitHub?

Simply select the “switch default branch” button (which looks like exchange arrows 🔄) at the top right of the “Default branch” box when navigating to https://github.com/{username}/{repo}/branches where username and repo correspond to your GitHub username and repository, respectively.

27.11 How do I set ‘devel’ as the default local branch?

In order to keep commands simple and avoid confusion, we recommend making the same default branch changes to the GitHub repository. This allows minimal commands such as

git push origin
git push upstream

to simply work without specifying additional parameters, (e.g., main:devel) when pushing to GitHub and Bioconductor.

For maintainers who wish to make changes on GitHub as well, we recommend performing the rename operation on GitHub first, then performing an adjustment (rename) of the local branch(es).

Note. This step is not necessary if you cloned a fresh copy from the Bioconductor git server though you will have to re-specify the origin and upstream remotes (as described above) with a fresh copy.

Once the branch is renamed on GitHub, use the GitHub-provided commands to update the local copy of the repository:

git branch -m master devel
git fetch origin
git branch -u origin/devel devel
git remote set-head origin -a

Note. Change ‘master’ to ‘main’ if the repository has ‘main’ as the default branch:

git branch -m main devel
git fetch origin
git branch -u origin/devel devel
git remote set-head origin -a

27.12 How do I push to Bioconductor after renaming?

To push upstream to Bioconductor, the developer will simply push to the devel branch:

## branch should already exist
git checkout devel
#### <commit changes and bump version etc.>
git push upstream devel

27.13 Clean up: How do I get rid of stale remote-tracking branches?

After the rename, there will remain stale references in the origin remote. See all the local and remote branches with git branch -a:

git branch -a
# * devel
# remotes/origin/HEAD -> origin/devel
# [...]
# remotes/origin/master

Run the following to get rid of the stale reference to “master” in the origin remote:

git remote prune origin --dry-run

Note. Remove the --dry-run option after making sure that the correct remote reference is listed.

27.14 What if I have a GitLab repository?

It is possible to also change the default branch on GitLab. See the change default branch instructions. Once complete, you can update the local repository similarly to the above instructions.