Waivers

A waiver accepts a violation that a project has decided to live with, from outside the source. -- vsg_off signal_008 suppresses a rule at a place in the code; a waiver does the same from a file, which is what makes it possible to adopt a rule set on a codebase that does not follow it yet. Waived violations are counted, never reported, and never affect the exit code.

Adopting a rule set on existing code

vsg-rs --recursive src --fix                           # first fix what can be fixed
vsg-rs --recursive src --generate_waivers waivers.yaml # then accept what is left
vsg-rs --recursive src --waivers waivers.yaml          # from now on: only new violations

Fix before generating. Layout and style rules are almost all fixable, and a waiver file that accepts thousands of layout violations is both enormous and pointless: --fix removes them for good. What is worth waiving is the rest: generated code, vendor sources, or a rule a team disagrees with in one directory.

The file

waivers:
  - rule: signal_008
    files: 'generated/**/*.vhd'
    lines: [12, 45]
    reason: generated by hdl-registers
  - rule: '*'
    files: 'vendor/**/*.vhd'
    reason: third-party, not ours to reformat

Key	Meaning
rule	Rule id, or * for every rule. Required.
files	Glob against the reported file name (?, *, **). A bare file name also matches that file under a longer path. Omit to match every file.
lines	Lines the waiver covers. Omit to waive the rule in the whole file, which survives the code moving.
reason	Why. Optional, and the only reason a waiver file stays trustworthy.

--waivers takes several files, so a repository-wide waiver file and a directory's own can be passed together.

Keeping waivers honest

• --generate_waivers writes exact line numbers and reason: TODO. Replace the reasons: a file full of TODO is a list of problems nobody has read, not a set of decisions.
• Lines rot: when code moves, a line-scoped waiver stops matching and the violation comes back. That is the point. Delete lines: when the waiver is about the file rather than the line.
• --show_waived lists what was waived, with its reason, so a review can see what the file is hiding. Without it a run only prints how many violations were waived.
• A waiver never hides a syntax error or an internal error; those are not violations.

From the editor

In an editor that runs the language server, a finding offers to be waived on its line, in its file or everywhere, asks why, and writes the entry to vsg-rs-waivers.yaml. Pass that file to --waivers in CI and the editor and the command line agree about what has been accepted.