[UX] Be more verbose about what is being checked

[webknjaz]

Hi, I noticed that when checking a single commit (or a range that only has one), gitlint does not output its hash. This is confusing when it's used in a CI because it doesn't give contributors enough context in the job log, on what's wrong. Just a number and an error message without specifying what it refers to.

This is how I'm trying to work around the problem and make the output better digestible: https://github.com/cherrypy/cheroot/pull/579/files. Check out the workflow summary under Checks to see more — I'm adding a job summary there.

But how could gitlint itself improve this? I think, there should be a way to output more info, like the commit contents being checked (at least for the commits with violations), so the readers could see what's up without having to guess this by looking things up locally, detached from the CI run.

One more thing could be linking to the error explanation pages in docs, similar to what pip is starting to do, and what Rust and eslint ecosystems have. Such docs pages could include information on what a rule is looking for and suggestions on how to fix the corresponding violations.

Also, in the context of GHA, gitlint could autodetect it and make use of https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#grouping-log-lines to collapse blocks of output or/and https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary to additionally produce colorful markdown explanations. This could also be a feature of a GitHub Action idea the project board mentions but it doesn't have to be — it'd be also useful for when folks run gitlint as a standalone command.

[jorisroovers]

Thoughts:

• gitlint --debug does provide a bunch more output, but this obviously serves a different use-case entirely. Just calling it out.
• An extra level of verbosity could be added that output some of these things, but I don’t think that’s the solution here
• I think the real solution to this problem is custom output formatters, as described in Custom note to explain title-match-regex rule. #45, and then gitlint potentially having a few of those output formatters as built-in presets. This would also allow for structured output formatters that are more machine-parseable (e.g. JSON Outputter). FWIW, I’ve thought about making the output formatter concept even more generic into EventHandler concept, of which OutputEventHandler could just be a subtype. I believe I got that idea from briefly looking at the flake8 codebase, but it’s been a while so not sure anymore.
• I like the idea of pointing the the docs for specific errors/rule violations, this idea is already somewhere buried in the Kanban backlog…
• For more GHA specific output, that would then just become a specific OutputFormatter/Handler I think. I prefer to keep specific environment detection (like github/gitlab/jenkins, etc) outside of the core gitlint code to keep it elegant, but this use-case fits the pluggable system nicely.