Formatting and Linting

Workflows recommends using 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:
    - lint:

Workflows lint's //... by default using the linting rules setup via rules_lint, however the targets can be manually defined by setting the targets attribute:

.aspect/workflows/config.yaml

tasks:
    - lint:
          targets:
              - //foo/...
              - //bar/...

Failure modes

A blocking linting change can be frustrating for developers, therefore it may be useful to set the failure_strategy. There are three modes available:

• hard: Always fail the build for lint issues.
• soft: Allows lint issues to be reported during the build, but does not cause it to fail.
• hold_the_line: Lint issues are reported during the build, and manifest as failures on pull requests, but not on a branch build. This setting, coupled with only_changed_regions, ensures that no new lint issues are introduced, but allows existing lint issues to remain until that area is changed.

.aspect/workflows/config.yaml

tasks:
    - lint:
        failure_strategy: 'hold_the_line'

Annotating and Suggestions on GitHub pull requests

To annotate a GitHub pull request with lint failures, the Aspect Github App must be enabled in the given repository. Following that, add github notifications to the Aspect configuration.

For annotations, specify experimental_annotations: true.

To receive suggestions (review comments) containing automatic fixes from linters, specify experimental_suggestions: true.

.aspect/workflows/config.yaml

notifications:
    github:
        experimental_annotations: true
        experimental_suggestions: true

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_changed_regions to false.

.aspect/workflows/config.yaml

tasks:
    - lint:
          only_changed_regions: false
notifications:
    github:
        experimental_annotations: true

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.