Git, Linters and SourceLevel: how tools enable a more inclusive language and diverse culture

SourceLevel is changing directions!

After October 1st, 2021, we will focus all our efforts on our (All-in-one) Analytics & Data Platform for Engineering Teams, thus we’re discontinuing the Automated Code Review feature.

Are terminologies meaningful in software development? Yes, a lot! As developers, we’re continually writing code, and we do that by passing messages. Each message carries a lot of context and semantics. Therefore we’re always evolving how to do it in a better way.

There is this vastly known anecdote that says that there are only two hard things in Computer Science: caching invalidation and naming things.

Terminology is in the roots of communication, and therefore is as vital for writing quality code as writing User Stories, documentation, and even naming branches.

If you care a lot about communicating effectively, I think we must use an inclusive language to do so.

Inclusive writing is the usage of the language with neutrality. Inclusiveness has a positive impact on our lives, as they don’t offend interlocutors based on abilities/disabilities, age, gender, sexuality, race, ethnicity, religion, etc.

It would be best to read this content guide that describes how to be more inclusive when writing. The impact of fostering more inclusive writing implies changes in how we write software. Besides, sooner or later, we see that it affects many aspects of everyday life communication. 🌱

Some time ago, a proposal regarding the master branch name in Git came up. I got pleased that the concern of an inclusive language arrived in the tool I use every day for development. The proposal addresses replacing the master branch name by a more inclusive one, such as main, primary, or principal.

At SourceLevel, we have opted for using main as the default branch name. Did you know you can change the default branch in your Git repositories? You can do it by both GitLab (Project Settings > Repository) and GitHub (Repository Settings > Branches).

Changing the default branch of your repositories may break some tools. In the case of SourceLevel, we already support the custom default branch, and it synchronizes with GitHub and GitLab. Changing on those tools automatically replicates in our tool.

Steps for changing your default branch

In the examples below, I rename the master branch to main. You should discuss with your team and find the name that better suits you.

Firstly, we need to rename it locally:

$ git branch -m master main
$ git push origin main -u

And you’re done! These two commands rename your local master branch and then push it to the remote server. It’s a secure way to start, once the commands don’t delete the remote master branch.

Note that after changing the name to main, everyone who clones the repository gets the new default branch set. However, people who had previously cloned the repository are still pointing to the master branch.

To move forward with the change, everyone in your team needs to run a few commands. For a complete guide, I strongly recommend reading Damien Cosset’s blog post.

Using SourceLevel as an Inclusive Language watchdog

Now that we have a more inclusive branch name, there may be references to other terms that we should avoid. They may appear in variables, methods, or even comments.

So, we need to look for them the whole codebase. This part can demand lots of hard work, depending on the size and terminology used throughout codebases.

Changing the existing code doesn’t prevent you or your team from using exclusive language again. What if a bot could notify you when a contravention appears? You can use the grep linter as a watchdog!

Configure your .sourcelevel.yml file adding rules that look for exclusive language and suggest more appropriate terms for each Pull or Merge Requests using SourceLevel’s automated code review feature. It should look something like this:

engines:
  grep:
    config:
      patterns:
        allowlist:
          pattern: "/white[_\\-]?list/i"
          annotation: Do not use 'Whitelist'. Prefer the term 'Allowlist'
          categories: Style
          path_patterns:
          - "**/*.ex"
          - "**/*.exs"
        blocklist:
          pattern: "/black[_\\-]?list/i"
          annotation: Do not use 'Blacklist'. Prefer the term 'Blocklist'
          categories: Style
          path_patterns:
          - "**/*.ex"
          - "**/*.exs"
    enabled: true

After pushing it to the main branch, SourceLevel can help you achieve a more inclusive language throughout the codebase!

In short

Using an inclusive language is crucial for fostering a diverse culture. Git has changed the naming conventions to be more language-inclusive, and so you should change. Our development tools, like GitHub and GitLab, already supports the change.

SourceLevel deals very nicely with repositories that changed the master branch to a more appropriate word. Besides, you can use the grep linter the look for exclusive terms contained in the source code.

As the inclusive language gap may happen in other aspects of our lives, have you already thought about them?

Raise the discussion in your team and use the tools to favor a more inclusive world 💚!

Weverton Timoteo

Co-founder and CTO at SourceLevel.

JRPG-fan that enjoys solving functional programming challenges.