#978552 lintian: report outdated maintainer manual pages

Package:
lintian
Source:
lintian
Submitter:
Andrius Merkys
Date:
2021-02-25 14:15:03 UTC
Severity:
wishlist
Tags:
#978552#5
Date:
2020-12-28 14:43:48 UTC
From:
To:
Maintainer manual pages are already reported by lintian in pedantic mode
[1]. Such manual pages may be OK per se, but, if outdated, they may
cause confusion for downstream users. Thus I think it is important to
report outdated maintainer manual pages. The same consensus seems to
have been reached on debian-med@, in a thread on manual page maintenance
[2]. I think the severity of such hint should be warning, as outdated
manual pages may be misleading to the downstream users.

To implement this hint, already existing code for locating maintainer
manual pages could be re-used. For every located maintainer manual page,
lintian should extract and compare the date and source package version
in .TH line to the actual date and version provided in the d/changelog.
Possible heuristics: upstream parts of the versions must match, date in
the manual page must be more recent than the last upload of previous
upstream release.

[1] https://lintian.debian.org/tags/maintainer-manual-page.html
[2] https://lists.debian.org/debian-med/2020/12/msg00224.html

Andrius
#978552#10
Date:
2021-02-05 09:52:06 UTC
From:
To:
As explained in [1], there actually are conventions for writing man
pages given in 'man 7 man-pages'. Thus .TH line can be trusted to
contain the date of last non-trivial change:

date:

The date of the last nontrivial change that was made to the man page.
(Within the man-pages project, the necessary updates to these timestamps
are handled automatically by scripts, so there is no need to manually
update them as part of a patch.) Dates should be written in the form
YYYY-MM-DD.

[1] https://lists.debian.org/debian-devel/2021/02/msg00040.html

Andrius
#978552#15
Date:
2021-02-05 22:13:36 UTC
From:
To:
Hi Andrius,

I like your idea, but how can the dates—being handled
automatically—ever be wrong? Do the scripts neglect to adjust manual
pages provided by Debian's maintainers?

Kind regards
Felix Lechner
#978552#20
Date:
2021-02-06 07:13:37 UTC
From:
To:
Hi Felix,

Thanks for reviewing my proposal!

My proposal aims at the manpages that are written manually or
semi-automatically. Particularly 'man-pages' project is not the aim
here, I cite their conventions just to show that Debian manpages are
supposed to follow the conventions of .TH structure.

Best wishes,
Andrius
#978552#25
Date:
2021-02-22 15:00:42 UTC
From:
To:
Hello,

I am interested in giving this feature a shot. I have started work on my
fork [1], and will submit a MR upon completion.

[1]
https://salsa.debian.org/merkys/lintian/-/commits/978552-report-outdated-manual-pages

Andrius