Merge tag '1.20170520'

tagging package debug-me version 1.20170520

# gpg: Signature made Sat 20 May 2017 22:31:39 BST
# gpg:                using RSA key 28A500C35207EAB72F6C0F25DB12DB0FF05F8F38
# gpg: Good signature from "Joey Hess <joeyh@joeyh.name>" [full]
# Primary key fingerprint: E85A 5F63 B31D 24C1 EBF0  D81C C910 D922 2512 E3C7
#      Subkey fingerprint: 28A5 00C3 5207 EAB7 2F6C  0F25 DB12 DB0F F05F 8F38

1 files changed, 30 insertions, 10 deletions

diff --git a/doc/faq.mdwn b/doc/faq.mdwn
index c9b46ea..6884ec0 100644
--- a/doc/faq.mdwn
+++ b/doc/faq.mdwn
@@ -6,20 +6,28 @@
 
 #### Should I let John Doe connect to my debug-me session? I don't know that guy.
 
-When a developer connects to your debug-me session, it will display
-their GnuPG key, and the number of people who have signed it. It will
-also list the names of some of those people (the best connected ones).
-
-If the developer of software you use is connecting to debug-me,
-their software documentation might say what their GnuPG key is. Then you
-can simply check that the GnuPG key ids match.
+When a developer connects to your debug-me session, debug-me will display
+their GnuPG key, and information about it, including
+the number of people who have signed it. It will also list the names
+of some of those people (the best connected ones).
+
+Suppose you're using Debian, and debug-me says "John Doe is a Debian
+developer". Then it's probably safe to let this person connect,
+because you already trust this guy implicitly, since you're using software
+he develops.
+
+How does debug-me know that John Doe is a Debian developer? It's checked
+that his gpg key is in the keyring at
+`/usr/share/debug-me/keyring/a_Debian_developer.gpg`, which is provided by
+Debian. Other software projects that are installed on your computer can
+also put keyrings in that directory, and then debug-me will be able to
+tell then a developer of a project is connecting.
 
 If debug-me says that "John Doe is probably a real person", it means
 that he's connected to the strong set of the GnuPG web of trust.
 Other people, who certianly are real, have verified his identity.
-So even if you don't know his name, it can be safe to let him connect.
-
-But it's a gut call. If in doubt, don't let the developer connect.
+So even if you don't know his name, it can be safe to let him connect,
+but if in doubt, don't let him.
 
 If debug-me says "identity cannot be verified!", it means that the GnuPG
 key couldn't be downloaded at all, or the developer is not connected to the
@@ -67,6 +75,18 @@ Here's a quick checklist:
 * Include your GnuPG key id in your project's documentation, so users
   will know which key is yours. It also helps to sign git tags,
   tarballs, git commits, etc with your key.
+* Make your software package install a gpg keyring of its developers to
+  /usr/share/debug-me/keyring/.
+  
+  A file there named "a_Foo_developer.gpg"
+  will make debug-me tell the user that "Your Name is a Foo developer." 
+  when you connect to their debug-me session, and so the user will be more
+  likely to trust you and let you connect.
+
+  For example:
+  
+  	gpg --export-options export-minimal --export C910D9222512E3C7 > a_Foo_developer.gpg
+
 * When a user has a bug that you need more information to reproduce and
   understand, ask if they'll use debug-me.