From b18fa48c89027c7d98f639888c6098e4e023d10c Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Thu, 1 Mar 2012 17:23:18 -0800
Subject: [PATCH] Move documentation about X-Herald-Rules to an article

Summary:
  - We have a lot of headers now; document them.
  - Remove the one random protip from like 3 years ago from all Differential
mail.

Test Plan: generated; read documentation

Reviewers: btrahan

Reviewed By: btrahan

CC: aran, epriestley

Maniphest Tasks: T931

Differential Revision: https://secure.phabricator.com/D1748
---
 .../mail/base/DifferentialMail.php            |  2 -
 src/docs/userguide/mail_rules.diviner         | 72 +++++++++++++++++++
 2 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 src/docs/userguide/mail_rules.diviner

diff --git a/src/applications/differential/mail/base/DifferentialMail.php b/src/applications/differential/mail/base/DifferentialMail.php
index 51eab73957..6e506d6486 100644
--- a/src/applications/differential/mail/base/DifferentialMail.php
+++ b/src/applications/differential/mail/base/DifferentialMail.php
@@ -199,8 +199,6 @@ MANAGE HERALD DIFFERENTIAL RULES
 WHY DID I GET THIS EMAIL?
   {$xscript_uri}
 
-Tip: use the X-Herald-Rules header to filter Herald messages in your client.
-
 EOTEXT;
     }
 
diff --git a/src/docs/userguide/mail_rules.diviner b/src/docs/userguide/mail_rules.diviner
new file mode 100644
index 0000000000..07bb07bc51
--- /dev/null
+++ b/src/docs/userguide/mail_rules.diviner
@@ -0,0 +1,72 @@
+@title User Guide: Managing Phabricator Email
+@group userguide
+
+How to effectively manage Phabricator email notifications.
+
+= Overview =
+
+Phabricator uses email as a major notification channel, but the amount of email
+it sends can seem overwhelming if you're working on an active team. This
+document discusses some strategies for managing email.
+
+By far the best approach to managing mail is to **write mail rules** to
+categorize mail. Essentially all modern mail clients allow you to quickly
+write sophisticated rules to route, categorize, or delete email.
+
+= Reducing Email =
+
+You can reduce the amount of email you receive by turning off some types of
+email in ##Settings -> Email Preferences##. For example, you can turn off email
+produced by your own actions (like when you comment on a revision), and some
+types of less-important notifications about events.
+
+= Mail Rules =
+
+The best approach to managing mail is to write mail rules. Simply writing rules
+to move mail from Differential, Maniphest and Herald to separate folders will
+vastly simplify mail management.
+
+Phabricator also sets a large number of headers (see below) which can allow you
+to write more sophisticated mail rules.
+
+= Mail Headers =
+
+Phabricator sends a variety of mail headers that can be useful in crafting rules
+to route and manage mail.
+
+Many of these headers contain lists. A list containing two items, ##1## and
+##15## will generally be formatted like this:
+
+  X-Header: <1>, <15>
+
+The intent is to allow you to write a rule which matches against "<1>". If you
+just match against "1", you'll incorrectly match "15", but matching "<1>" will
+correctly match only "<1>".
+
+The headers Phabricator adds to mail are:
+
+  - ##X-Phabricator-Sent-This-Message##: this is attached to all mail
+    Phabricator sends. You can use it to differentiate between email from
+    Phabricator and replies/forwards of Phabricator mail from human beings.
+  - ##X-Phabricator-To##: this is attached to all mail Phabricator sends.
+    It this shows the PHIDs of the original "To" line, before any mutation
+    by the mailer configuration.
+  - ##X-Phabricator-Cc##: this is attached to all mail Phabricator sends.
+    It shows the PHIDs of the original "Cc" line, before any mutation by the
+    mailer configuration.
+  - ##X-Differential-Author##: this is attached to Differential mail and shows
+    the revision's author. You can use it to filter mail about your revisions
+    (or other users' revisions).
+  - ##X-Differential-Reviewers##: this is attached to Differential mail and
+    shows the reviewers. You can use it to filter mail about revisions you
+    are reviewing, versus revisions you are explicitly CC'd on or CC'd as
+    a result of Herald rules.
+  - ##X-Differential-CCs##: this is attached to Differential mail and shows
+    the explicit CCs on the revision.
+  - ##X-Phabricator-Mail-Tags##: this is attached to some mail and has
+    a list of descriptors about the mail. (This is fairly new and subject
+    to some change.)
+  - ##X-Herald-Rules##: this is attached to some mail and shows Herald rule
+    IDs which have triggered for the object. You can use this to sort or
+    categorize mail that has triggered specific rules.
+