Bug#796293: insufficient/confusing documentation for pgpsigurlmangle

[Daniel Kahn Gillmor]

Hi Thomas--

Thanks for the useful feedback.  The documentation tries to be short but
complete, and clearly we have a ways to go for improvement.

I'll answer your questions below -- maybe you can propose a patch that
would make these answers clearer without bloating or overcomplicating
uscan(1) ?

On Fri 2015-08-21 09:13:02 +0200, Thomas Koch wrote:
> There are a few related shortcomings with the documentation of
> pgpsigurlmangle and the related lintian tag
> debian-watch-may-check-gpg-signature.
>
> 1) The uscan manpage says:
> "This signature must be made  by  a  key  found  in  the keyring
> debian/upstream/signing-key.pgp  or the armored keyring
> debian/upstream/signing-key.asc."

A keyring is a linear concatenation of OpenPGP Transferable Public Keys

  https://tools.ietf.org/html/rfc4880#section-11.1

> - - What is an armored keyring?

The difference between an armored keyring and a non-armored keyring is
ASCII armoring:

  https://tools.ietf.org/html/rfc4880#section-6.2

> - - Isn't it, that the .asc file is just one public key as produced by
> gpg --armor --export $KEYID?

No, you can have multiple signing keys in the file -- for example, some
projects have multiple release managers.

> - - Please give an example how to correctly produce this file.

 gpg --export-options export-minimal --armor --export $FINGERPRINT > debian/upstream/signing-key.asc

> - - How can I produce a keyring .pgp file?

Same as above, but without --armor.

> - - Which format should be preferred? I don't like choices.

The currently encouraged format is the armored one:

  debian/upstream/signing-key.asc

We support the other options because they already exist in the archive:

 debian/upstream/signing-key.pgp
 debian/upstream-signing-key.pgp
 debian/upstream-signing-key.asc
 
Maybe what we could do is find all of them in the archive, get them
switched over, and then drop support for the old ones to make it less
confusing for new adopters?

I'm having a hard time finding these files via codesearch, but maybe i'm
just searching wrong.

> 2) There is no example of a full watch file with a pgpsigurlmangle
> option. I needed several tries to get it right because it was the
> first time that I had to produce a non trivial watch file with an
> option. I believe that many others might be in the same situation.
> Please add an example to the uscan manpage or the lintian tag or
> both.

agreed, fully!  The openssh debian/watch file is probably fine:

0 dkg at alice:~/src/openssh/debian$ cat debian/watch 
version=3
opts=pgpsigurlmangle=s/$/.asc/ \
ftp://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-(.*)\.tar\.gz
0 dkg at alice:~/src/openssh/debian$ 

> 3) The lintian tag says:
> "verified against a keyring stored in debian/upstream-signing-key.asc"
> The manpage does not mention this file. It seems that the code
> still uses it, but it is confusing.

yes, we should adjust the lintian tag info.

> 4) How about a script, that checks all watch files, tries GET
> requests against $URL.sig, $URL.asc and proposes a new watch file
> to the maintainer in case it finds something?

I believe uscan already does this autosearch, but doesn't propose an
explicit watch file edit.  patches to uscan for this?

         --dkg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 948 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/devscripts-devel/attachments/20150821/e08da62c/attachment-0001.sig>