Add support for GitHub annotations in GitHub actions

[nijel]

• Add --github to format output according to https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
• Add REUSE_OUTPUT_FORMAT to override output from the environment, this is useful to change output in CI compared to when running in user environment.

• Added a change log entry in changelog.d/<directory>/.
• Added self to copyright blurb of touched files.
• Added self to AUTHORS.rst.
• Wrote tests.
• Documented my changes in docs/man/ or elsewhere.
• My changes do not contradict
  the current specification.
• I agree to license my contribution under the licenses indicated in the
  changed files.

[carmenbianca]

Wow, amazing PR @nijel ! Thank you for this work.

I wonder whether it makes sense to keep --lines in parallel to --github. They do effectively the same. For backward compatibility, we should probably keep both, though…

Do you know whether this GitHub format of errors is also consumed by other programs?

[nijel]

--lines is still more user friendly, so I'd keep both. I think gitlab has a similar format, but I have no experience with that. https://docs.astral.sh/ruff/settings/#output-format supports that in addition to GitHub...

[carmenbianca]

Some questions and feedback. The PR looks great overall.

I will write a few patch commits to fix the easy stuff that doesn't need discussion.

[carmenbianca]

There should be a documented order of precedence here. If both REUSE_OUTPUT_FORMAT and a CLI flag are used, which takes precedence?

As written in the code, I believe the env var takes precedence. I do not know if this is desirable behaviour.

[carmenbianca]

Additionally, should quiet be a valid value here?

[carmenbianca]

Additionally, what should happen if the value of REUSE_OUTPUT_FORMAT is invalid?

[nijel]

Ah, seems like I didn't notice this feedback, sorry.

With the current implementation, the environment variable takes precedence. This is intentional to allow having command line configuration and override it by environment if executed in environment which might want different output (as GitHub).

Unknown values are simply discarded, but it might be a better approach to issue a warning.

[ferdnyc]

@nijel

having command line configuration and override it by environment if executed in environment which might want different output (as GitHub).

That's an argument I've seen before, in other contexts, and it's always felt upside-down to me.

Typically the precedence goes config file -> envvar -> commmand-line flags. You can store your configuration in a file, but if need be can still override it by setting variables in the environment. Above all else, though, the arguments specified directly on the command line supersede any other sources.

It's a Principle of Least Astonishment thing. Using examples from some common build systems, if I run a command like,

$ cmake -B _build -S . -DCMAKE_INSTALL_PREFIX=/tmp

then for it to install somewhere else because I happened to have CMAKE_INSTALL_PREFIX="/var/tmp" set in the environment, then that's a very astonishing invisible override.

By the same token, it was a bug in Rust's Cargo a while back that a command like:

$ CARGO_BUILD_TARGET_DIR='env' cargo c --config myConfig.toml

...Would ignore a target dir specified in myConfig.toml. So, that was fixed.

BUT, that's actually another example of the previous form (command-line flags overriding the environment), because the config is loaded explicitly via the command-line args. Cargo has always, correctly, allowed a command like this:

$ CARGO_BUILD_TARGET_DIR='env' cargo c

...to override the target dir set in its default, autoloaded .cargo/config.toml file.

Seems to me that. if you want to set values via the environment, don't put them on the command line. Or, use the envvars on the command line, possibly with defaults.

For example:

make ${BUILD_TARGET:-all}

...will run make all unless ${BUILD_TARGET} is set in the environment.

But a make all should never ignore that explicit all and build something different, just because there's some value set in a config file or an environment variable. IMHO.

[nijel]

You're right, the precedence should be different. I thought about being able to override it when executed in GitHub actions, but reuse is there executed without a command line argument, so the environment would be used even if it is not a priority.

I see @carmenbianca has now made some changes on top of mine, so I'm not going to touch the PR unless it is desired to not interfere with other changes.