Skip to content
This repository has been archived by the owner on Sep 5, 2023. It is now read-only.

Latest commit

 

History

History
132 lines (90 loc) · 6.02 KB

README.md

File metadata and controls

132 lines (90 loc) · 6.02 KB
Raw

[DEPRECATED] Master to Main

[DEPRECATED] A CLI tool to rename master branch to main for GitHub repos.

Github has made it easier to rename branches since this repo was created.

Overall the process is:

  1. Rename existing branch to main on GitHub
  2. Update CI (typically GitHub Actions)
  3. Update CD (typically RiffRaff)
  4. Update Snyk
  5. Perform a deploy to ensure everything is still working
  6. Inform your team to update their clone

This repo is no longer maintained

Quick Start

master-to-main can be installed using either npm or yarn

npm install -g @guardian/master-to-main

yarn global add @guardian/master-to-main

It can then be run as follows

$ m2m [OWNER/REPO] [TOKEN]
running command...

View all options and help information

$ m2m --help
...

View installed version

$ m2m (-v|--version)
master-to-main/0.0.0 darwin-x64 node-v14.9.0

It can also be used directly via npx

npx @guardian/master-to-main --help

Running

This tool requires two arguments.

Argument Description
accessToken A GitHub personal access token. See the auth section for more details
repoName The name of the repository to migrate in the form owner/repository

This tool can also be run with a number of options. The following table lists them all.

Option Short Description Default
from -f The current name of the branch master
to -t The new name of the branch main
force - Disable any user prompts false
execute -x Execute the migration false
verbose - Output debug logs false
guardian - Run the guardian specific steps around build configuration. Disable using --no-guardian true
issues - Open issues for any further changes required. Disable using --no-guardian true

As well as this, the --version option can be used to display the current version install and the --help option can be used to display the help information.

Details

This tool is built on top of the oclif library to provide CLI functionality.

It interfaces with the GitHub API to carry out the necessary steps for the migration (more information below). It makes use of the octokit library.

Execution

By default, the app runs in dry run mode. This will perform GET requests and log all steps as if they were to be executed. This can be useful both to see how the process works without making changes and to run checks to reduce the chance of encountering an error partway through the process. To execute the change, pass the -x or --execute flag.

Auth

Authentication and authorisation is handled using GitHub Personal Access Tokens (PATs). You will need to provide this as the second argument (after the repo name) when you run the tool.

N.B. Treat your tokens like passwords and keep them secret. Consider using environment variables to store tokens during use and remove any tokens that are not in use.

You can create a token from the Developer settings tab within GitHub settings. For public repos, the public_repo scope will suffice. For private repos, the repo scope is needed.

It is recommended that a new token is created specifically for the purpose of running this tool, so that the token can be removed from your account immediately after the process is complete.

Steps

The process carries out the following steps in order:

  1. Check if the repository exists (by getting the repo object)
  2. Check that the old branch name exists
  3. Check if the new branch name already exists
  4. Check if the user is an admin (by getting the username from the access token and then calling the get repository permissions for user endpoint)
  5. Get the number of open PRs and check with that user that they're happy to proceed
  6. Rename the branch using the new rename a branch API
  7. Check if a riff-raff.yaml file is present and open an issue if it is (unless the --no-guardian option is passed)
  8. Check for any files that reference the old branch name and open an issue if any exist
  9. Open an issue to cover any (other) build configuration that may need updating

Developing

We follow the script/task pattern, find useful scripts within the script directory for common tasks.

  • ./script/setup to install dependencies
  • ./script/start to run the Jest unit tests in watch mode
  • ./script/lint to lint the code using ESLint
  • ./script/test to run the Jest unit tests
  • ./script/build to compile TypeScript to JS

There are also some other commands defined in package.json:

  • yarn lint --fix attempt to autofix any linter errors
  • yarn format format the code using Prettier

However, it's advised you configure your IDE to format on save to avoid horrible "correct linting" commits.

Testing

The master-to-main-demo repository can be used to test this tool. It includes a number of elements to allow the key functionality to be validated.