Effectiveness of Tool: GitHub native rename - Samvera Branch Renaming Working Group

Summary of Observations

• Renaming in GitHub does not change localhost, links to master from wiki pages, issues, or PR comments.
• Renaming in GitHub does change branch name, branch settings, PR base branch.
• Renaming a branch other than master that is in a PR waiting to merge into another branch, closes the PR.
• Once renamed, instructions are provided for renaming at localhost.  Once those are cleared, I couldn't find a way to get them back.  I tried renaming another branch, but they still were not shown again.
• Once master is renamed, a user can push master to the repo again.  There were no settings in Settings → Branches → add rule, that would prevent the master branch from being created again in the repo.

Setup

• Create a test repo with a master branch, issues, PRs - See samvera-labs/branch-renaming-wg for a script to do this.  This script sets up conditions in the test repo:
  • Default branch is master
  • add branch settings for master branch under Settings → Branches
• Conditions to set up manually:
  • Within the test repo, create a wiki page that references a branch in master. -- link in Home page accessed from Wiki in header menu
  • Create a Fork of the test repo. -- samvera-labs/branch-renaming-test-1
  • Clone the test repo to your local machine.
  • Clone the Fork to your local machine.
  • Create a second repo with a pin in the Gemfile to a master sha in the repo having the branch renamed -- N/A The test app is not setup as a gem.

Tool: gitHub-default-branch

Reference: 

• Renaming the default branch from master (official GitHub documentation)

Usage:

• navigate to the test repo in github (e.g. YOUR_GITHUB_USERNAME/branch-renaming-test)

• click branches link

• click pencil icon beside master branch
• set name to main

Checklist:

• renames master to main
  • branch dropdown defaults to main
  • master is not in the branch dropdown
• Settings → Branches
  • main is the default branch
  • branch rules were copied over to main
  • master branch is not in the branch dropdown under Default branch
  • master branch is not listed in the Branch protection rules area
• updates issues
  • changes reference to a sha in master to the same sha in main
  • changes links to code in master branch to the same code in main -- NO -- (NOTE: Even though the link text and URL were not changed, GitHub forwards to the renamed branch which is main.)
• updates PRs
  • updates 'commit into' branch to main for all PRs
  • updates links to code in master branch to the same code in main -- NO -- (NOTE: Even though the link text and URL were not changed, GitHub forwards to the renamed branch which is main.)
• documentation
  • in wiki page, updates links to code in master branch to the same code in main -- NO -- (NOTE: Even though the link text and URL were not changed, GitHub forwards to the renamed branch which is main.)
  • in README, updates links to code in master branch to the same code in main -- NO -- (NOTE: Even though the link text and URL were not changed, GitHub forwards to the renamed branch which is main.)
• local git repo
  • commit/push without changing branch name locally automatically DOES NOT recreate the old branch name -- NO -- IT DOES recreate master
  • commit/push without changing branch name locally automatically goes to new branch name -- NO -- IT GOES to master branch
    • AND all links directed at master no longer autoforward to main; they go to master branch
  • updates local master tracking origin/master to local main tracking origin/main -- NO -- nothing locally automatically updates

• after following instructions for updating local git repo

  git branch -m master main
  git fetch origin
  git branch -u origin/main main

  • updates branches based on origin/master to origin/main
  • updates branches based on local master to local main -- NOTE: The link to master is based on the sha and the sha doesn't change with the renaming, so this is a no-op.
  • in second repo, updates pin to master sha in the repo having the branch renamed (NOT TESTED)
• working with Forks

  • after rename in parent, fork default branch is also renamed -- NO -- the default branch continues to be master, but there is a note telling you that the default branch was renamed to main in the source repo.
    

    

  • PRs from fork into source repo are updated to merge into main branch

Rename non-master branch:

• renames rename_me branch to renamed branch
  • branch dropdown lists renamed
  • rename_me is not in the branch dropdown
• Settings → Branches
  • does not change the default branch
  • branch rules for rename_me were copied over to renamed
  • rename_me branch is not in the branch dropdown under Default branch
  • rename_me branch is not listed in the Branch protection rules area
• updates issues
  • changes reference to a sha in rename_me to the same sha in renamed
  • changes links to code in rename_me branch to the same code in renamed (NOTE: Even though the link text and URL were not changed, GitHub forwards to the renamed branch which is renamed.)
• updates PRs
  • updates 'commit into' branch for PRs going to rename_me to renamed for all PRs
  • updates 'from' branch for PRs going from rename_me to renamed for all PRs -- NO UPDATE and CLOSES the PRs
  • updates links to code in rename_me branch to the same code in renamed (NOTE: Even though the link text and URL were not changed, GitHub forwards the renamed branch which is renamed.)
• wiki updated
  • updates links to code in rename_me branch to the same code in renamed (NOTE: Even though the link text and URL were not changed, GitHub forwards all 404 to the default branch which is main.)
• local git repo
  • commit/push without changing branch name locally automatically DOES NOT recreate the old branch rename_me
  • commit/push without changing branch name locally automatically goes to new branch renamed 
  • updates to local rename_me tracking origin/master to local renamed tracking origin/renamed
  • updates branches based on origin/rename_me to origin/renamed
  • updates branches based on local rename_me to local renamed
  • in second repo, updates pin to rename_me sha in the repo having the branch renamed
• working with Forks
  • TBD

Additional areas not tested

• automated builds and deployments that reference master branch
  • building images that aren't from tags but from branches
  • Jenkins
  • Ansible
• other tooling that references master branch
  • git aliases
  • local shell scripts
  • maintenance scripts for github API
  • git reflow or other 3rd party tools
• Integrations
  • Github hooks, coveralls, code climate, hound, circleci
  • mirroring with other sources (e.g. gitlab mirroring github)
  • notifications to tools (e.g. slack integration)
• documentation (eg. raw.github.com URLs)
  
  • samvera.github.io
  • samvera.org
  • github pages for the project
  • Contributing
• references to master in code
  • Gemfile pins
  • To possible JSON documents in Github repos
• forks
  • Within "usual" contributors
  • Other "users"
    • In particular, Browse Everything has utility outside of Samvera's adopters