Add a new capability

Step-by-step guide to adding a new capability

This public content is an excerpt from Flutter staff GitHub docs. It is published as a reference to show how GitHub is used for inner source at Flutter.

Before you start

Make sure you:

Setting Up a New Capability

To set up a new capability, you’ll need the following information:

  • List of Repositories: GitHub repository names that belong to the capability.
  • Capability Name: The name of the capability.
  • Owner and Maintainers: GitHub usernames of the owner and maintainers.
  • Default Branching Strategy: The default branching strategy to be applied to the repositories.
  • Basic Repository Settings: Settings that adjust repository behavior for certain actions (e.g., deleting a branch after merge).

Example Capability Setup

We’ll use an example capability to illustrate the setup process.

Identified Repositories

The following repositories work together to provide a live video stream for our products:

  • broadcast-service
  • transcode-utils
  • video-config

Capability Details

Roles

From the capability details, we will add the user smith-john as an owner, and the users jones-ruben and brown-thomas as maintainers. CBG will create the team owner-cap-live-video for the owner and maintainers-cap-live-video for the maintainers, and add them to the repositories with the admin-on-demand permission role. The team all-flutter-global will also be added with write permissions to all the repositories, unless the contributors key is overridden in the repository configuration file.

Learn more about available roles in the Roles documentation.

Branching Strategy

We’ll use the Reviewed Source branching strategy because this capability has a critical production service. Expert maintainers will review all changes before release. Learn more in the Branching Strategy documentation.

The video-config repository will not require a CODEOWNERS review. We’ll override the default rule in its configuration file and disable contributions from the all-flutter-global team.

Repository Settings

  • All branches will be deleted after merging.
  • Feature branches will be squashed when merged into main.

Overall all the modifications will be applied like this:

Structuring for Codebase Governor

With all the information gathered, we’ll now structure it for Codebase Governor usage and write the configuration files.

The file structure in the org-config repository will be:

codebases/
    live-video/
        _defaults.yml
        broadcast-service.yml
        transcode-utils.yml
        video-config.yml

The capability name will serve as the root folder for our configuration files. The _defaults.yml file will include the default configuration for the capability, along with its owner and maintainers. The remaining files will contain repository-specific configurations. You can find all available properties on the Capability Defaults documentation page.

Based on our gathered information, the _defaults.yml file will look like this:

description: This capability enables live video streaming allowing for a centralized video distribution. 

owner: smith-john
maintainers:
  - jones-ruben
  - brown-thomas

defaults:
  # delete branches by default after a PR is merged
  delete-branch-on-merge: true

  # our normal flow uses feature branches squashed into main
  allow-pr-merge-options:
    squash: true

  # enforce no admins other than owner & maintainers
  admins: {}

  # allow contribution from any member of Flutter-Global
  contributors:
    teams:
      - all-flutter-global

  branch-protections:
  - patterns:
    - "main"
    parameters:
      required-reviews-count: 1
      requires-codeowner-reviews: true

The above configuration will apply to all repositories unless specifically overridden in a repository configuration file.

The broadcast-service and transcode-utils repositories will use the default branching strategy, so we’ll only add descriptions to their specific configuration files. You can find all available properties on the Repo Config documentation page.

broadcast-service.yml

description: Service responsible for the live video signal broadcast

transcode-utils

description: Set of utils to ease the video transcoding process

As previously mentioned, the branching strategy for the video-config repository can be simplified by excluding the CODEOWNERS review setting and it won’t allow outside contributions. We’ll override the defaults by adding repository-specific settings.

video-config.yml

description: Broadcast service configuration files

# Override the default setting for Contributors
contributors: {}

# Override default branch protection setting for the `main` branch
branch-protections:
  - patterns:
      - "main"
    parameters:
      required-reviews-count: 1

We’re now ready to open a pull request in the org-config repository. After being approved and merged, the Codebase Governor will start managing the repository capabilities.

Further Reading

Examples

Numerous capability and configuration examples can be viewed in the org-config repository.