Document new incoming email address format (EE)

doc/administration/incoming_email.md

@@ -15,43 +15,45 @@ GitLab has several features based on receiving incoming emails:
 
 ## Requirements
 
-Handling incoming emails requires an [IMAP]-enabled email account. GitLab
-requires one of the following three strategies:
+Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled
+email account. GitLab requires one of the following three strategies:
 
-- Email sub-addressing
-- Dedicated email address
+- Email sub-addressing (recommended)
 - Catch-all mailbox
+- Dedicated email address (supports Reply by Email only)
 
 Let's walk through each of these options.
 
-**If your provider or server supports email sub-addressing, we recommend using it.
-Most features (other than reply by email) only work with sub-addressing.**
-
-[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol
-
 ### Email sub-addressing
 
 [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is
-a feature where any email to `user+some_arbitrary_tag@example.com` will end up
-in the mailbox for `user@example.com`, and is supported by providers such as
-Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the
-[Postfix mail server] which you can run on-premises.
-
-[Postfix mail server]: reply_by_email_postfix_setup.md
+a mail server feature where any email to `user+arbitrary_tag@example.com` will end up
+in the mailbox for `user@example.com` . It is supported by providers such as
+Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the
+[Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises.
+
+TIP: **Tip:**
+If your provider or server supports email sub-addressing, we recommend using it.
+A dedicated email address only supports Reply by Email functionality.
+A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7,
+but sub-addressing is still preferred because only one email address is used,
+leaving a catch-all available for other purposes beyond GitLab.
 
-### Dedicated email address
+### Catch-all mailbox
 
-This solution is really simple to set up: you just have to create an email
-address dedicated to receive your users' replies to GitLab notifications.
+A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain
+receives all emails addressed to the domain that do not match any addresses that
+exist on the mail server.
 
-### Catch-all mailbox
+As of GitLab 11.7, catch-all mailboxes support the same features as
+email sub-addressing, but email sub-addressing remains our recommendation so that you
+can reserve your catch-all mailbox for other purposes.
 
-A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will
-"catch all" the emails addressed to the domain that do not exist in the mail
-server.
+### Dedicated email address
 
-GitLab can be set up to allow users to comment on issues and merge requests by
-replying to notification emails.
+This solution is relatively simple to set up: you just need to create an email
+address dedicated to receive your users' replies to GitLab notifications. However,
+this method only supports replies, and not the other features of [incoming email](#incoming-email).
 
 ## Set it up
 
@@ -162,14 +164,16 @@ for a real-world example of this exploit.
     gitlab_rails['incoming_email_idle_timeout'] = 60
     ```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
-    mailbox incoming@exchange.example.com
+    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
+    catch-all mailbox incoming@exchange.example.com
 
     ```ruby
     gitlab_rails['incoming_email_enabled'] = true
 
-    # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here
-    gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com"
+    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
+    gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"
 
     # Email account username
     # Typically this is the userPrincipalName (UPN)
@@ -281,15 +285,17 @@ for a real-world example of this exploit.
       idle_timeout: 60
     ```
 
-    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes
-    mailbox incoming@exchange.example.com
+    Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the
+    catch-all mailbox incoming@exchange.example.com
 
     ```yaml
     incoming_email:
       enabled: true
 
-      # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here
-      address: "incoming@exchange.example.com"
+      # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
+      # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
+      # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
+      address: "incoming-%{key}@exchange.example.com"
 
       # Email account username
       # Typically this is the userPrincipalName (UPN)

doc/user/project/issues/create_new_issue.md

@@ -39,25 +39,31 @@ It opens a new issue for that project labeled after its respective list.
 
 ## New issue via email
 
-*This feature needs [incoming email](../../../administration/incoming_email.md)
-to be configured by a GitLab administrator to be available for CE/EE users, and
-it's available on GitLab.com.*
+At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
+is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
 
-At the bottom of a project's issue page, click
-**Email a new issue to this project**, and you will find an email address
-which belongs to you. You could add this address to your contact.
+![Bottom of a project issues page](img/new_issue_from_email.png)
+
+When you click this link, an email address is displayed which belongs to you for creating issues in this project.
+You can save this address as a contact in your email client for easy acceess.
 
-This is a private email address, generated just for you.
-**Keep it to yourself** as anyone who gets ahold of it can create issues or
-merge requests as if they were you. You can add this address to your contact
-list for easy access.
+CAUTION: **Caution:**
+This is a private email address, generated just for you. **Keep it to yourself**,
+as anyone who gets ahold of it can create issues or merge requests as if they
+were you. If the address is compromised, or you'd like it to be regenerated for
+any reason, click **Email a new issue to this project** again and click the reset link.
 
 Sending an email to this address will create a new issue on your behalf for
-this project, where the email subject becomes the issue title, and the email
-body becomes the issue description. [Markdown] and [quick actions] are
-supported.
+this project, where:
 
-![Bottom of a project issues page](img/new_issue_from_email.png)
+- The email subject becomes the issue title.
+- The email body becomes the issue description.
+- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
+
+NOTE: **Note:**
+In GitLab 11.7, we updated the format of the generated email address.
+However the older format is still supported, allowing existing aliases
+or contacts to continue working._
 
 ## New issue via Service Desk **[PREMIUM]**
 
@@ -96,6 +102,3 @@ Follow these examples to form your new issue URL with prefilled fields.
 and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
 - For a new issue in the GitLab Community Edition project with a pre-entered title
 and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
-
-[Markdown]: ../../markdown.md
-[quick actions]: ../quick_actions.md

doc/user/project/service_desk.md

@@ -61,21 +61,28 @@ you can skip the step 1 below; you only need to enable it per project.
      you will see an option to set up Service Desk:
 
      ![Activate Service Desk option](img/service_desk_disabled.png)
+
 4.   Checking that box will enable Service Desk for the project, and show a
      unique email address to email issues to the project. These issues will be
      [confidential], so they will only be visible to project members.
 
-     **Warning**: as the screenshot below shows, this email address can be used
-     by anyone to create an issue on this project, whether or not they have
-     access to your GitLab instance. We recommend **putting this behind an
-     alias** so that it can be changed if needed, and
-     **[enabling Akismet][akismet]** on your GitLab instance to add spam
-     checking to this service.
+     **Warning**: this email address can be used by anyone to create an issue on
+     this project, whether or not they have access to your GitLab instance.
+     We recommend **putting this behind an alias** so that it can be changed if
+     needed, and **[enabling Akismet][akismet]** on your GitLab instance to add spam
+     checking to this service.  Unblocked email spam would result in many spam
+     issues being created, and may disrupt your GitLab service.
 
      ![Service Desk enabled](img/service_desk_enabled.png)
+
+     _In GitLab 11.7, we updated the format of the generated email address.
+     However the older format is still supported, allowing existing aliases
+     or contacts to continue working._
+
+
 5.   Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**:
 
-      ![Service Desk Navigation Item](img/service_desk_nav_item.png)
+     ![Service Desk Navigation Item](img/service_desk_nav_item.png)
 
 ## Using Service Desk