Bug#900710: a man page should be provided for kdeconnect-cli

[Pino Toscano]

Hi Nicholas,

In data giovedì 23 gennaio 2020 14:46:04 CET, Nicholas D Steeves ha scritto:
> > Date: Mon, 12 Nov 2018 08:41:46 +0000
> > From: Pino Toscano <pino at debian.org>
> > To: 900710-close at bugs.debian.org
> > Subject: Bug#900710: fixed in kdeconnect 1.3.3-1
> > 
> > Source: kdeconnect
> > Source-Version: 1.3.3-1
> >
> [snip]
> >  kdeconnect (1.3.3-1) unstable; urgency=medium
> [snip]
> >    * Drop the Debian-provided kdeconnect-cli man page: very outdated, not
> >      touched in the last 4 years, and thus not useful. (Closes: #900710)
> 
> This bug was closed in error at a time I was swamped with work, and I
> didn't notice until now.

No, this bug was definitely not closed in error. The original bug was
about the man page being very outdated (and it was), so the removal was
one possible way to fix this issue, in particular the one I chose.

Because of this, I disagree with the reopening of this old bug and
turning it into something else than it was originally. Opening a *new*
wishlist bug "please provide a man page" would had been a better idea.

> Please consult Policy §12.1 for why it was
> wrong to close it.  tldr;
> 
>     If no manual page is available, this is considered as a bug and
>     should be reported to the Debian Bug Tracking System (the
>     maintainer of the package is allowed to write this bug report
>     themselves, if they so desire). Do not close the bug report until
>     a proper man page is available.

It is a *should*, so there is no requirement on us to either ship a man
page, or even do the work to provide one as part of the Debian
packaging.

In general, we (Debian Qt/KDE) ought to *not* provide man pages
ourselves, as it has many drawbacks:

- the man page must be maintained by the team and, considering the huge
  amount of work the team already has, this means that a man page is
  rarely (if ever) updated after its first introduction; and this very
  reply of yours show this very well: if the person that adds a man
  page is busy or does not contribute to the team anymore, then nobody
  else will work on it

- the man page is available only to Debian users

- the man page is only in English

- the Debian-provided man page will silently overwrite an upstream
  provided one (!); this actually happened in two cases that I spotted
  when updating KDE Applications to 17.08 a couple of years ago

- unless the executable has any option other than the usual
  --help/--version/--author, a man page does not add any value to the
  package, and becomes just a bureaucratic formality than a real need

So our guideline for this ought to be:

- do not provide Debian-specific man page

- *iff* (if and only if) a man page is requested for a real reason [1],
  forward the request upstream to provide a man page, if they desire;
  optionally submitting one in DocBook format (in case of KDE projects)

- if there is no request it means there is no demand for it

[1] for "real reason" I mean that the request is justified because of
    the executable, and not requested like "lintian complains" or
    "Policy says"

Having a man page shipped by upstream has multiple advantages:

- the man page is available to all the users, not just Debian ones
  (and thus more people can read it and spot issues, provide
  enhancements, etc)

- the man page is available also in other languages

- upstream (the developers directly, or the KDE documentation team)
  will keep the man page up-to-date

- there is no additional work required on the Debian side, nor
  additional files in our debian/ directories

Hope this clarifies the situation.

-- 
Pino Toscano
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part.
URL: <http://alioth-lists.debian.net/pipermail/pkg-kde-talk/attachments/20200124/fb90a69a/attachment.sig>