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@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@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
signature.asc
Description: PGP signature