Removal of non-inclusive terminology from Ably codebases
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:
master | main | 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 |
|
whitelist | allowlist |
|
blacklist | denylist |
|
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:
1 | Pull in the current state of the "master" branch from origin. |
|
2 | Create a feature branch.
|
|
3 | Search for terms and replace them. This may well include release and contribution instructions. |
|
4 | Check that it still builds and that tests run. |
|
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. |
|
6 | Push the feature branch to origin. |
|
7 | Create a pull request. To ensure appropriate oversight we've required approval from at least two people:
| |
8 | Merge the pull request to master. | |
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. |
|
11 | Rename the primary development branch from "master" to "main". |
|
12 | Push the renamed branch to origin. |
|
13 | Change the Default branch from "master" to "main" (this option is under Branches in Settings for this repository). | |
14 | Delete the "master" branch. |
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
Easily rename your Git default branch from master to main (Scott Hanselman)
How to change the remote a branch is tracking? (Stack Overflow answer)
Setting the default branch (GitHub Docs)
Deleting a branch (GitHub Docs)