Allow a reason comment for disabled rules

[NickLarsenNZ]

For example, I want to disable the line limit check for certain files and explain why. But if I add a comment with the disable, the disable is ignored.

# yamllint disable rule:line-length because we want to add links next to some items

I propose two options:

1. Add a reason directive, so:

   # yamllint disable rule:line-length reason:because we want to add links next to some items

2. Do it in the same way markdownlint does it, and allow an extra comment indicator after:

   # yamllint disable rule:line-length # because we want to add links next to some items

After writing them out, I think I prefer the second option (quotes would be superfluous in the first option, yet it looks weird without them).

[andrewimeson]

Why not just add a comment on the line above?

# Since Bob wrote this ugly YAML, and we miss him, we won’t touch it
# yamllint disable rule:line-length

[NickLarsenNZ]

Why not just add a comment on the line above?

# Since Bob wrote this ugly YAML, and we miss him, we won’t touch it
# yamllint disable rule:line-length

Because I have other comments, and I would like the reason to be tightly coupled with the disabling of the rule.

[adrienverge]

Hello!

I like @andrewimeson's proposal because it's handy, and already available :+1:

That being said, the proposed change seems acceptable (I also prefer the second option).

[andrewimeson]

because we want to add links next to some items

This isn't related to your original request, but can you share an example from the file where you need to disable the rule? You may be able to just adjust some of the line-length configuration in the yamllint configuration to get what you want, specifically allow-non-breakable-inline-mappings.

[NickLarsenNZ]

@andrewimeson, the case I had in mind looked like this (where default line limit is 80 chars, as much as I'd like it longer)...

  run_clippy:
    name: Run Clippy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
        with:
          submodules: recursive

      - uses: dtolnay/rust-toolchain@0e66bd3e6b38ec0ad5312288c83e47c143e6b09e # v1
        with:
          toolchain: ${{ env.RUST_VERSION }}
          components: clippy

      - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
        with:
          go-version: ${{ env.GO_VERSION }}

      - uses: Swatinem/rust-cache@23bce251a8cd2ffc3c1075eaa2367cf899916d84 # v2.7.3
        with:
          key: clippy

      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
        with:
          node-version: 18
          cache: yarn

So in this case, we'd like the tags in the comments to sit on the same line no matter of length.

In general I think rules being disabled should have a reason for posterity, and having it on the same line prevents it from drifting away or disappearing accidentally (sure, version control will keep a history, but looking through each change seems like a burden).

[andrewimeson]

In general I think rules being disabled should have a reason for posterity [...] version control will keep a history, but looking through each change seems like a burden).

A git blame (assuming useful commit messages) would be a relatively easy way to see why a line was added, but I still understand your need. Some things are better documented by a comment to the reader, and not just a commit message.

Do you want to create a PR to add the functionality, or is it something you're hoping for volunteers on?

[NickLarsenNZ]

I'd like to give it a go, but if I get stuck, I will reach out.