Include URLs in errors that explains the error and provide possible solutions
I just read a mailing list post where someone (P) recommended using sq inspect
to identify problems with the poster's (O's) OpenPGP certificate. P showed the following example output:
$ gpg --export 0x7C34B4E14CE4F655 | sq inspect
-: OpenPGP Certificate.
Fingerprint: 1745 1D0F BB5E 88F4 0AC0 08F6 7C34 B4E1 4CE4 F655
Invalid: No binding signature at time 2020-11-18T22:41:24Z
Public-key algo: DSA (Digital Signature Algorithm)
Public-key size: 1024 bits
Creation time: 2001-08-03 17:34:53 UTC
UserID: Phil Pennock [censored email address in this list post]
Invalid: Policy rejected non-revocation signature (PositiveCertification)
because: SHA1 is not considered secure since 2013-01-01T00:00:00Z
Bad Signature: [ snip long error which doesn't matter here ]
I imagined being O and reading that. Yes, it is clear that there is a problem (certainly clearer than reading the output of gpg --list-packets
, which was the other suggestion), but it won't be clear to O how to rectify the situation. Most people won't know what a binding signature is, etc.
One way to make this actionable would be to include a URL similar to rustc that points the user to some additional documentation. This can be added directly where the error occurs (i.e., in sequoia-openpgp, not by sq inspect
), or perhaps where the error type is declared. In the latter case, we probably need a lot more error types. I think having lots of error types is not a problem, but adding new errors would probably break the API.