You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@community.apache.org by cd...@apache.org on 2023/08/13 18:14:14 UTC
[comdev-site] branch feature/mailing-list-after-changed-defaults updated: Update mailing-lists.md
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch feature/mailing-list-after-changed-defaults
in repository https://gitbox.apache.org/repos/asf/comdev-site.git
The following commit(s) were added to refs/heads/feature/mailing-list-after-changed-defaults by this push:
new 938dec5 Update mailing-lists.md
938dec5 is described below
commit 938dec5489b1a9fdb2ae613e219a90918ff93b5d
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Sun Aug 13 20:14:10 2023 +0200
Update mailing-lists.md
Updated version of the documentation needed prior to sending out the email to all dev-lists about the changed defaults.
---
source/contributors/mailing-lists.md | 91 ++++++++++++++++++++++++------------
1 file changed, 62 insertions(+), 29 deletions(-)
diff --git a/source/contributors/mailing-lists.md b/source/contributors/mailing-lists.md
index f27a82d..4e54f1b 100644
--- a/source/contributors/mailing-lists.md
+++ b/source/contributors/mailing-lists.md
@@ -100,34 +100,7 @@ notifications:
### Configuring the subject lines of the emails being sent
-The defaults that the tooling uses seems a bit odd to me:
-
-```
-github:
- custom_subjects:
- new_pr: "Created: PR {repository}/#{pr_id}: {title}"
- close_pr: "Closed: PR {repository}/#{pr_id}: {title}"
- comment_pr: "Commented: PR {repository}/#{pr_id}: {title}"
- merge_pr: "Merged: PR {repository}/#{pr_id}: {title}"
- new_issue: "Created: Issue {repository} {title}"
- comment_issue: "Commented: Issue {repository} {title}"
- close_issue: "Closed: Issue {repository} {title}"
- catchall: "Updated: {repository}/#{issue_id}: {title}"
- new_discussion: "Created: Discussion {repository}: {title}"
- edit_discussion: "Edited: Discussion {repository}: {title}"
- close_discussion: "Closed: Discussion {repository}: {title}"
- close_discussion_with_comment: "Closed: Discussion with comment {repository}: {title}"
- reopen_discussion: "Reopened: Discussion {repository}: {title}"
- new_comment_discussion: "Commented: Discussion {repository}: {title}"
- edit_comment_discussion: "Edited a comment: Discussion {repository}: {title}"
- delete_comment_discussion: "Deleted a comment: Discussion {repository}: {title}"
-```
-However these result in emails that no email client I have come
-across is able to group to threads and I have not come acoss even one
-email where I got to what the email is about on my phone because all I
-could see was: "Commented: Discuss...".
-
-We therefore updated these in some projects to a lot shorter versions:
+If not explicitly managing the subject lines, the defaults are as follows (These are the new defaults which are valid starting October 1st 2023):
```
github:
@@ -136,7 +109,6 @@ github:
close_pr: "Re: [PR] {title} ({repository})"
comment_pr: "Re: [PR] {title} ({repository})"
merge_pr: "Re: [PR] {title} ({repository})"
- catchall: "Updated: {repository}/#{issue_id}: {title}"
new_issue: "[I] {title} ({repository})"
comment_issue: "Re: [I] {title} ({repository})"
close_issue: "Re: [I] {title} ({repository})"
@@ -150,9 +122,70 @@ github:
edit_comment_discussion: "Re: [D] {title} ({repository})"
delete_comment_discussion: "Re: [D] {title} ({repository})"
```
+In general, you can use any of the following variables in your custom subject lines (However some only apply to some types of messages. If this is the case, it is noted in the line what types of messages they apply to):
+
+- `{action}`: The generic action that happened (created/deleted/edited)
+- `{user}`: The GitHub user than initiated the action
+- `{title}`: The title of the discussion that was affected
+- `{category}`: The category slug for the discussion
+- `{url}`: The URL for the discussion or comment that was affected (Discussions)
+- `{link}`: The URL for the issue or pr that was affected (PRs and Issues)
+- `{body}`: The body of text, either the discussion itself or a comment.
+- `{action_human}`: If a comment happened, this is a human readable representation of the action
+- `{recipient}`: The mailing list this was sent to
+- `{unsub}`: The unsubscribe address of the mailing list this was sent to
+- `{pr_id}`: The GitHub pull-request id related to the action (PRs)
+- `{issue_id}`: The GitHub issue id related to the action (Issues)
+
If your project uses multiple github repositories, we recommend using the `repository` variable to let people know which repo the email is related to.
If your project is a single-repo project (or for the other repositories GitHub integration is not enabled or not used much) feel free to also remove that part.
+```
+github:
+ custom_subjects:
+ new_pr: "[PR] {title}"
+ close_pr: "Re: [PR] {title}"
+ comment_pr: "Re: [PR] {title}"
+ merge_pr: "Re: [PR] {title}"
+ new_issue: "[I] {title}"
+ comment_issue: "Re: [I] {title}"
+ close_issue: "Re: [I] {title}"
+ catchall: "[GH] {title}"
+ new_discussion: "[D] {title}"
+ edit_discussion: "Re: [D] {title}"
+ close_discussion: "Re: [D] {title}"
+ close_discussion_with_comment: "Re: [D] {title}"
+ reopen_discussion: "Re: [D] {title}"
+ new_comment_discussion: "Re: [D] {title}"
+ edit_comment_discussion: "Re: [D] {title}"
+ delete_comment_discussion: "Re: [D] {title}"
+```
+
+#### Using the old defaults (prior to October 1st 2023)
+
+If for any reason, you would like to use the old defaults that were valid till October 1st 2023, please use the following configuration:
+
+```
+github:
+ custom_subjects:
+ new_pr: "Created: PR {repository}/#{pr_id}: {title}"
+ close_pr: "Closed: PR {repository}/#{pr_id}: {title}"
+ comment_pr: "Commented: PR {repository}/#{pr_id}: {title}"
+ merge_pr: "Merged: PR {repository}/#{pr_id}: {title}"
+ new_issue: "Created: Issue {repository} {title}"
+ comment_issue: "Commented: Issue {repository} {title}"
+ close_issue: "Closed: Issue {repository} {title}"
+ catchall: "Updated: {repository}/#{issue_id}: {title}"
+ new_discussion: "Created: Discussion {repository}: {title}"
+ edit_discussion: "Edited: Discussion {repository}: {title}"
+ close_discussion: "Closed: Discussion {repository}: {title}"
+ close_discussion_with_comment: "Closed: Discussion with comment {repository}: {title}"
+ reopen_discussion: "Reopened: Discussion {repository}: {title}"
+ new_comment_discussion: "Commented: Discussion {repository}: {title}"
+ edit_comment_discussion: "Edited a comment: Discussion {repository}: {title}"
+ delete_comment_discussion: "Deleted a comment: Discussion {repository}: {title}"
+```
+
### Conclusion
The custom templates help make the GitHub content readable on your