Merge "Add User Docs for Sending Emails to Gerrit"

Documentation/intro-user.txt

@@ -712,6 +712,105 @@ In addition it is possible to customize the menu entries of the `My`
 menu. This can be used to make the navigation to frequently used
 screens, e.g. configured link:#dashboards[dashboards], quick.
 
+[[reply-by-email]]
+== Reply by Email
+
+Gerrit sends out email notifications to users and supports parsing back replies
+on some of them.
+
+Gerrit supports replies on these notification emails:
+
+* Notifications about new comments
+* Notifications about new labels that were applied or removed
+
+While Gerrit supports a wide range of email clients, the following ones have
+been tested and are known to work:
+
+* Gmail
+* Gmail Mobile
+
+Gerrit supports parsing back all comment types that can be applied to a change
+via the WebUI:
+
+* Change messages
+* Inline comments
+* File comments
+
+Please note that comments can only be sent in reply to a comment in the original
+notification email, while the change message is independent of those.
+
+Gerrit supports parsing a user's reply from both HTML and plaintext. Please note
+that some email clients extract the text from the HTML email they have received
+and send this back as a quoted reply if you have set the client to plaintext
+mode. In this case, Gerrit only supports parsing a change message. To work
+around this issue, consider setting a <<email-format,User Preference>> to
+receive only plaintext emails.
+
+Example notification:
+----
+Some User has posted comments on this change.
+(https://gerrit-review.googlesource.com/123123 )
+
+Change subject: My new change
+......................................................................
+
+
+Patch Set 3:
+
+Just a couple of smaller things I found.
+
+https://gerrit-review.googlesource.com/#/c/123123/3/MyFile.java
+File
+MyFile.java:
+
+https://gerrit-review.googlesource.com/#/c/123123/3/MyFile@420
+PS3, Line 420:     someMethodCall(param);
+Seems to be failing the tests.
+
+
+--
+To view, visit https://gerrit-review.googlesource.com/123123
+To unsubscribe, visit https://gerrit-review.googlesource.com/settings
+
+(Footers omitted for brevity, must be included in all emails)
+----
+
+Example response from the user:
+----
+Thanks, I'll fix it.
+> Some User has posted comments on this change.
+> (https://gerrit-review.googlesource.com/123123 )
+>
+> Change subject: My new change
+> ......................................................................
+>
+>
+> Patch Set 3:
+>
+> Just a couple of smaller things I found.
+>
+> https://gerrit-review.googlesource.com/#/c/123123/3/MyFile.java
+> File
+> MyFile.java:
+Rename this file to File.java
+>
+> https://gerrit-review.googlesource.com/#/c/123123/3/MyFile@420
+> PS3, Line 420:     someMethodCall(param);
+> Seems to be failing the tests.
+>
+Yeah, I see why, let me try again.
+>
+> --
+> To view, visit https://gerrit-review.googlesource.com/123123
+> To unsubscribe, visit https://gerrit-review.googlesource.com/settings
+>
+> (Footers omitted for brevity, must be included in all emails)
+----
+
+In this case, Gerrit will persist a change message ("Thanks, I'll fix it."),
+a file comment ("Rename this file to File.java") as well as a reply to an
+inline comment ("Yeah, I see why, let me try again.").
+
 
 GERRIT
 ------