Formatting and Linting

Workflows uses Aspect's rules_lint to setup linting and formatting rules. Follow the instructions in that repository to install it.

Formatting

The simplest configuration for a format check looks like this:

.aspect/workflows/config.yaml

tasks:
    - format:

Workflows will run bazel run //:format and verify that no changes are made to any source files. If changes are made, the task will fail, and will recommend that the developer remediate it by running bazel run //:format.

Warning vs Error

Getting a red CI for formatting nits can be frustrating for developers, as there is nothing wrong with the code. Formatting is fast enough to be performed as a pre-commit hook, which ensures files are formatted before the CI system sees them. See Install as a pre-commit hook for information on setting this up.

If you have a pre-commit hook then we recommend setting this to be a warning instead, using soft_fail:

.aspect/workflows/config.yaml

tasks:
    - format:
          soft_fail: true

Specify targets

The two format targets may be customized in the configuration:

.aspect/workflows/config.yaml

tasks:
    - format:
          # Workflows will 'bazel run' this target to format the files
          target: //path/to:format-check
          # Developers will be asked to 'bazel run' this target to format their files
          fix_target: //path/to:formater

Linting

A minimal configuration for the lint task is shown below:

.aspect/workflows/config.yaml

tasks:
    # Run linters over all targets
    - lint:

Specific target patterns to be linted may be manually defined by setting the targets attribute:

.aspect/workflows/config.yaml

tasks:
    # Run linters over specific target patterns
    - lint:
          targets:
              - //foo/...
              - //bar/...

Failure modes

rules_lint honors the warning/error settings for your linter tools. However, blocking pull requests on linting errors can be frustrating for developers, therefore it may be useful to set the failure_strategy. There are three modes available:

• hard: Fail the build for lint errors (any lint tool exiting with a non-zero return code).
• soft: Report lint issues during the build, but ignore the linter exit codes.
• hold_the_line (recommended): Lint issues are reported during the build, and manifest as failures on pull requests if and only if the lint issues fall within file regions changed in the pull requests. Lint issues do not manifest as failures on branch builds.

.aspect/workflows/config.yaml

tasks:
    - lint:
        failure_strategy: 'hold_the_line'

Annotating and Suggestions on GitHub pull requests

Marvin can annotates a pull request with lint results. Follow those setup instructions to enable the bot.

To disable annotations, specify annotations: false.

To stop receiving suggested fixes from linters, specify suggestions: false.

.aspect/workflows/config.yaml

notifications:
    github:
        annotations: false
        suggestions: false

GitHub Limits

GitHub imposes a limit of 10 suggestions (review comments) and 25 annotations per pull request to avoid overwhelming the normal review cycle.

Filtering annotations

By default, the annotations displayed are filtered to only show for files and regions that have been explicitly changed by the in the pull request. To instead show all lint annotations (within the limit), set only_annotate_changed_regions to false.

.aspect/workflows/config.yaml

tasks:
    - lint:
          only_annotate_changed_regions: false
notifications:
    github:

Disabling reproduction / fix commands

To stop showing reproduction commands as part of the Aspect GitHub App, set show_aspect_cli_commands to false.

.aspect/workflows/config.yaml

notifications:
    github:
        show_aspect_cli_commands: false

Buildifier

Buildifier is a formatter and linter for Bazel code (BUILD and *.bzl files).

Buildifier is a special case, because rules_lint only runs linters over *_library targets, while BUILD files are not included in any such target. Workflows has a separate task for buildifier.