[bug#59217] [PATCH] guix: lint: Improve message in linter warning.

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

> Hi Maxim,
>
>> Personally, I'd prefer not having explanations directly in the output of
>> Guix lint; it should be terse, as it's involved often and repeatedly.
>
> I see your point. But, perhaps there should at least be a
> link. Something like
>
> /home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
> description should be followed by two spaces; possible infraction at 313
> (see
> https://guix.gnu.org/manual/en/html_node/guix-lint-errors.html#two-spaces
> for details)
>
> Or a lint error code that can be explained in detail in the manual:
>
> /home/arun/guix/gnu/packages/web.scm:8030:17: tissue@0.1.0: sentences in
> description should be followed by two spaces; possible infraction at 313
> (#12345)

I think I like the error code more; the link is too verbose to my taste,
and I prefer to stay outside of the browser as much as I can ;-).

It seems error codes that can be documented somewhere else are common
for linters (e.g., pylint).  It then also give some way to disable the
lint checks by annotating the source with e.g.

--8<---------------cut here---------------start------------->8---
;disable #12345
--8<---------------cut here---------------end--------------->8---

I'm not sure we'd want to do that, but that'd be an option for the
future if we had some documented codes for the checks.

> Or a --verbose flag that can enable longer explanations.

That's another interesting approach.  On the bad side, you'd probably
often run 'guix lint', then realize you needed --verbose, and have to
run it again (and it's slow).

> New users should not be baffled by error messages and should have some
> way of learning more without having to ask on the mailing list or do
> extensive research.

I agree there's merit to improving the situation!

-- 
Thanks,
Maxim