BC Linter

User Guide

Summary

The BC Linter aims to reduce backward compatibility-breaking changes in the PyTorch codebase by detecting BC-breaking changes early (at PR time). The linter codebase is located here.

Engineering perspective

This is a linter (similar to black) that is invoked on Github PRs. This linter analyzes changes in function signatures and, if they are backward-incompatible, reports them as inline warnings in Github file view (example).

The linter is designed to identify and report issues such as function deletion, parameter removal, renaming, or reordering, changes in parameter requiredness, and removal of support for variadic parameters.

Suppression

The linter can be suppressed:

• by adding labels suppress-api-compatibility-check or suppress-bc-linter to the PR;
• by having #suppress-api-compatibility-check or #suppress-bc-linter in the commit message.

Note

When suppressed, the "BC Lint" action failure will not show up in Dr.CI. and will not block the merge.

Caution

Please don't suppress the linter if you are not absolutely sure that the API you're changing is not used (or that the error is a false positive). Instead, tag the module owner for review or create a thread in the BC-linter support group.

Integration

To use the BC-linter action in your project, add the following step to your GitHub Actions workflow file:

- name: Run BC Lint Action
  uses: pytorch/test-infra/.github/actions/bc-lint@main
  with:
    repo: ${{ github.event.pull_request.head.repo.full_name }}
    base_sha: ${{ github.event.pull_request.base.sha }}
    head_sha: ${{ github.event.pull_request.head.sha }}
    suppression: ${{ contains(github.event.pull_request.labels.*.name, 'suppress-api-compatibility-check') }}
    docs_link: 'https://example.com/docs'

Specify the repository you want to check in your workflow, and 'https://example.com/docs' with the actual link to the documentation.

An example of the integration can be found here.