[PATCH] doc/DETAILS: clarify forward-compatible expectations

Daniel Kahn Gillmor dkg at fifthhorseman.net
Sat Sep 17 17:34:35 CEST 2016

* doc/DETAILS: encourage better parsers/interpreters of with-colons
  and status-fd output.

Signed-off-by: Daniel Kahn Gillmor <dkg at fifthhorseman.net>
 doc/DETAILS | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/DETAILS b/doc/DETAILS
index b5431d0..8303cc6 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -35,7 +35,9 @@ Note that new version of GnuPG or the use of certain options may add
 new fields to the output.  Parsers should not assume a limit on the
 number of fields per line.  Some fields are not yet used or only used
 with certain record types; parsers should ignore fields they are not
-aware of.
+aware of.  New versions of GnuPG or the use of certain options may add
+new types of records as well.  Parsers should ignore any record whose
+type they do not recognize for forward-compatibility.
 The double =--with-fingerprint= prints the fingerprint for the subkeys
 too.  Old versions of gpg used a slightly different format and required
@@ -357,8 +359,10 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
   Every line is prefixed with "[GNUPG:] ", followed by a keyword with
   the type of the status line and some arguments depending on the type
-  (maybe none); an application should always be prepared to see new
-  keyworkds or more arguments in future versions.
+  (maybe none); an application should always be willing to ignore
+  unknown keywords that may be emitted by future versions of GnuPG.
+  Also, new versions of GnuPG may add arguments to existing keywords.
+  Any additional arguments should be ignored for forward-compatibility.
 ** General status codes
 *** NEWSIG [<signers_uid>]

More information about the Gnupg-devel mailing list