Recommendations for the Component Maintenance Working Group

Owned by Kate Lynch
Last updated: Sept 25, 2020

Executive summary

This report provides a recommended approach for changing the default branch name of Core Component repositories from “master” to “main,” in line with the naming convention approach shared with the community in August 2020, along proposed next steps for coordinating with the Branch Renaming Working Group (BRWG)

In addition to updating the CCWG on our group’s progress since July 2020 toward our charter’s goals, this document should provide materials for users to become familiar with the process of changing a repository’s default branch name and correcting areas of potential breaking changes.  Beginning when they reconvene in January 2021, the BRWG will work with the CCWG to determine a timeline for when to plan for the complete removal of the “master” branch in “samvera” and “samvera-labs” GitHub organizations, factoring in availability of resources in the community to do so.

Note that while the Branch Renaming Working Group will be on hiatus from October 2020 until the beginning of January 2021, we can still help in an advisory capacity, work with folks on the tools we have experimented with, and generally collect feedback at any time.  Members of the community are encouraged to reach out to us on the #branch-renaming-wg channel on Slack.

Branch renaming process

To rename the default branch, we recommend using the github-default-branch.

In the remote repository on GitHub, this tool will automatically:

  • Rename the default branch from master to main
  • Remove references to master in the branch interface
  • Copy branch protection rules on master to main
  • Update open pull requests pointing to master, to point to main
  • Update references in issues from master to main

It also offers the ability for most local copies to update against the remote with a series of short commands, which would need to be done locally for each local copy that contains an outdated reference to master.

This tool will not:

  • Reliably propagate changes to the default branch across forks of the repository
  • Correct references to master in the repository’s wiki
  • Update references to the main branch for automation and deployment workflows with tools such as Jenkins, Ansible
  • Update external integrations with tools such as circleci, coveralls, Slack integrations, etc.
  • Update hard-coded references to the outdated branch in code (eg Gemfile pins)

For more in-depth information, review our Effectiveness of Tools document.

To track progress, we have a spreadsheet for branch renaming in the “samvera” and “samvera-labs” GitHub organizations, and welcome the CCWG to use this to track progress as well.

Next steps

  • Prioritize repositories for renaming.
  • Determine a method for tracking and sharing out progress.
  • Agree upon a communication strategy to stay in touch with the BRWG while that group is on hiatus.
  • When the BRWG reconvenes in January 2021, check in on the process of renaming, and what options are available based on newly-available tools in GitHub.  The BRWG will schedule and facilitate this.
  • In 2021, schedule a date when the "master" branch will no longer be available in the “samvera” and “samvera-labs” GitHub organizations, factoring in availability of resources within the community for this.