Removal of non-inclusive terminology from Ably codebases

Created by Matthew O'Riordan
Last updated: 2021-05-17 by Paddy Byers

Terms to be replaced

Terms and their replacements may appear in a few different contexts including:

  • Git branch names

  • file names

  • code entity names: classes, interfaces, properties, methods, fields, functions

  • code commentary

  • build scripts and CI system configuration files

  • documentation, readme files and other instructions

Depending on the context that the term appears, the choice of replacement may differ:

Term

Replacement(s)

Notes

Term

Replacement(s)

Notes

master

main
primary
active
coordinator
parent
trunk

The focus of much of the approach detailed in this document is around renaming the primary development branch for code repositories, meaning the focus is on replacement of this term with "main".

slave

backup
secondary
standby
subordinate
replica
worker
helper
child

 

whitelist

allowlist
permit

 

blacklist

denylist
blocklist
block

 

General Approach per Repository

For our GitHub repositories, where the primary development branch was called "master", the approach we've taken at Ably has followed the following general trajectory:

Task

Git command(s)

Task

Git command(s)

1

Pull in the current state of the "master" branch from origin.

git checkout master
git pull

2

Create a feature branch.

 

git checkout -b feature/rename-to-main

3

Search for terms and replace them. This may well include release and contribution instructions.

git grep mastergit grep slave

4

Check that it still builds and that tests run.

git checkout mastergit pull

5

If required, add any additional commits to fix build or tests, potentially doing a local rebase in order to fix history up before pushing to origin in the next step.

git rebase -i origin/master

6

Push the feature branch to origin.

git push -u origin feature/rename-to-main

7

Create a pull request.

To ensure appropriate oversight we've required approval from at least two people:

  1. A maintainer of this repository.

  2. One of our lead engineers who works across multiple codebases and has oversight over the coordinated effort to remove these terms.

Github.com

8

Merge the pull request to master.

Github.com

9

Notify those actively developing against this repository about the impending branch name change. Perhaps instruct them on how to modify their remote branch pointers.

 

10

Pull in the new state of the "master" branch from origin, now that the feature branch has been merged.

git checkout mastergit pull

11

Rename the primary development branch from "master" to "main".

git branch -m master main

12

Push the renamed branch to origin.

git push -u origin main

13

Change the Default branch from "master" to "main" (this option is under Branches in Settings for this repository).

Github.com

14

Delete the "master" branch.

Github.com

We've included a Git Command(s) column in the above table, however your mileage may vary. These commands are typical for the repositories we maintain but you might have an alternative workflow, which may include different naming conventions.

Where these cells display "GitHub", this is a step that you need to perform using GitHub's browser-based user interface.

Additional Considerations

  • Check CI systems after branch name change(s) have been made.

  • Use GitHub's UI to search pull requests and issues for terms which need replacing.

  • Deep links to GitHub resources (e.g. files within repositories) that include branch or tag names that use terms that need replacing can either be renamed to use the new branch name or changed so that they use a permalink.

Searching for Multiple Terms Simultaneously

Were you to create a file called terms.txt in your home folder containing with the following contents (a term per line):

master
slave
whitelist
blacklist

Then you could run the following command from the root of a repository you're checking to find out if any of those terms were in use, ignoring case:

git grep -i -f ~/terms.txt

Creating a New Repository

The default behaviour of git init is to configure the new repository to have a branch called master. Newer versions of git support changing this, run git config --global init.defaultBranch main. Repos created on GitHub already default to main.

For one time overriding:

git init --initial-branch=main

For most of us at the time of writing, using older Git clients, we can still change this behaviour by running an additional command after init but before any commits are created:

git init
git symbolic-ref HEAD refs/heads/main

References