Readability

This repository contains per-language readability requirements and also serves as the source of truth for current readability members.

Standards

Language-specific standards are available in the WiKi.

Proposing new readability

To propose new readability:

1. Find the associated language YAML file in the terraform directory. For example, to Go readability file is in terraform/go.yaml.

2. Propose a new membership under the members section:

   github_username: 'member'

   for example:

   sethvargo: 'member'

3. Create a Pull Request - GitHub will automatically assign the appropriate reviewers.

   If the Pull Request reports errors, inspect the output and fix errors. Usually these errors are due to improper formatting or invalid YAML.

Enforcing readability on a project

By default, readabilty is not enforced. To enforce readability:

1. Grant @abcxyz/<lang>-readability triage or greater permissions on your repository.

2. Add the following line(s) to your CODEOWNERS file:

   *.ext    @abcxyz/<lang>-readability

   for example, for Go readability:

   *.go    @abcxyz/go-readability

   if your language has multiple file extensions, add them all:

   *.java     @abcxyz/java-readability
   *.scala    @abcxyz/java-readability

3. Ensure you have branch protection rules to require a minimum number of reviewers. Specifically "Require review from Code Owners".

Adding a new language

There are two types of languages used by abcxyz. Languages with broad adoption that are a standard part of our technology stack (i.e. Go, Terraform, etc.) and languages with limited use or that are in early adoption (i.e. Python, Dart, etc.).

Limited use / early adoption languages

For new languages that we are uncertain about their widespread adoption, we will add targeted individuals as the CODEOWNERS for new repos. We will only convert them to a group and establish the standard readability practice after the usage of that language exceeds 5 repositories or 50k lines of code.

When a language exceeds the limited use phase a group will be created for it as is documented below.

Add a new language for widespread adoption

1. Manually create two teams in the organization.

   • Main readability team: - This is the team that will have people that have been granted readability.

     • Name: <lang>-readability (e.g. go-readability), all lowercase.
     • Description: <lang> readability (e.g. Go readability), normal case.
     • Parent team: readability.

   • Readability approvers team: - This is the team that has permission to grant other people readability.

     • Name: <lang>-readability-approvers (e.g. go-readability-approvers), all lowercase.
     • Description: <lang> readability approvers (e.g. Go readability approvers), normal case.
     • Parent team: readability.

2. Go to the team's settings page for each team and click on "Code review" in the sidebar.

   • Only notify requested team members: Checked.
   • Enable auto assignment: Checked.
   • How many team members should be assigned to review?: 1.
   • Routing algorithm: Load balance.
   • Team review assignment: Uncheck.

   Leave all other options as the default.

3. (Optional) On the team's settings page, upload a logo.

4. Update terraform/main.tf and add a new readabilty option to the for_each.

5. Create a new YAML file terraform/<lang>.yaml and add at least one maintainer. If you are the language owner, you can add yourself.

6. Propose a Pull Request with the changes.