From 55286d49e8ec74e03b3bdbd5374e50415b2fab48 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Wed, 6 Feb 2019 06:19:12 -0800
Subject: [PATCH] Clarify "metamta.default-address" instructions and lock the
 option

Summary: This option no longer needs to be configured if you configure inbound mail (and that's the easiest setup approach in a lot of cases), so stop telling users they have to set it up.

Test Plan: Read documentation and configuration help.

Reviewers: amckinley

Reviewed By: amckinley

Differential Revision: https://secure.phabricator.com/D20104
---
 .../PhabricatorMetaMTAConfigOptions.php       | 23 +++++++++++++-
 .../configuring_outbound_email.diviner        | 31 +++++++++++++------
 2 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/src/applications/config/option/PhabricatorMetaMTAConfigOptions.php b/src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
index ce24d48ead..7e6978dfd8 100644
--- a/src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
+++ b/src/applications/config/option/PhabricatorMetaMTAConfigOptions.php
@@ -182,6 +182,25 @@ EODOC
     $mailers_description = $this->deformat(pht(<<<EODOC
 Define one or more mail transmission services. For help with configuring
 mailers, see **[[ %s | %s ]]** in the documentation.
+EODOC
+      ,
+      PhabricatorEnv::getDoclink('Configuring Outbound Email'),
+      pht('Configuring Outbound Email')));
+
+    $default_description = $this->deformat(pht(<<<EODOC
+Default address used as a "From" or "To" email address when an address is
+required but no meaningful address is available.
+
+If you configure inbound mail, you generally do not need to set this:
+Phabricator will automatically generate and use a suitable mailbox on the
+inbound mail domain.
+
+Otherwise, this option should be configured to point at a valid mailbox which
+discards all mail sent to it. If you point it at an invalid mailbox, mail sent
+by Phabricator and some mail sent by users will bounce. If you point it at a
+real user mailbox, that user will get a lot of mail they don't want.
+
+For further guidance, see **[[ %s | %s ]]** in the documentation.
 EODOC
       ,
       PhabricatorEnv::getDoclink('Configuring Outbound Email'),
@@ -192,7 +211,9 @@ EODOC
         ->setHidden(true)
         ->setDescription($mailers_description),
       $this->newOption('metamta.default-address', 'string', null)
-        ->setDescription(pht('Default "From" address.')),
+        ->setLocked(true)
+        ->setSummary(pht('Default address used when generating mail.'))
+        ->setDescription($default_description),
       $this->newOption(
         'metamta.one-mail-per-recipient',
         'bool',
diff --git a/src/docs/user/configuration/configuring_outbound_email.diviner b/src/docs/user/configuration/configuring_outbound_email.diviner
index 4d18ba0eb2..6f5212680e 100644
--- a/src/docs/user/configuration/configuring_outbound_email.diviner
+++ b/src/docs/user/configuration/configuring_outbound_email.diviner
@@ -47,18 +47,31 @@ not. For more information on using daemons, see
 @{article:Managing Daemons with phd}.
 
 
-Basics
-======
+Outbound "From" and "To" Addresses
+==================================
 
-Before configuring outbound mail, you should first set up
-`metamta.default-address` in Configuration. This determines where mail is sent
-"From" by default.
+When Phabricator sends outbound mail, it must select some "From" address to
+send mail from, since mailers require this.
 
-If your domain is `example.org`, set this to something
-like `noreply@example.org`.
+When mail only has "CC" recipients, Phabricator generates a dummy "To" address,
+since some mailers require this and some users write mail rules that depend
+on whether they appear in the "To" or "CC" line.
 
-Ideally, this should be a valid, deliverable address that doesn't bounce if
-users accidentally send mail to it.
+In both cases, the address should ideally correspond to a valid, deliverable
+mailbox that accepts the mail and then simply discards it. If the address is
+not valid, some outbound mail will bounce, and users will receive bounces when
+they "Reply All" even if the other recipients for the message are valid. In
+contrast, if the address is a real user address, that user will receive a lot
+of mail they probably don't want.
+
+If you plan to configure //inbound// mail later, you usually don't need to do
+anything. Phabricator will automatically create a `noreply@` mailbox which
+works the right way (accepts and discards all mail it receives) and
+automatically use it when generating addresses.
+
+If you don't plan to configure inbound mail, you may need to configure an
+address for Phabricator to use. You can do this by setting
+`metamta.default-address`.
 
 
 Configuring Mailers