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/05/16 13:18:28 UTC
[comdev-site] branch feature/mailinglist-configuration updated: Update mailing-lists.md
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch feature/mailinglist-configuration
in repository https://gitbox.apache.org/repos/asf/comdev-site.git
The following commit(s) were added to refs/heads/feature/mailinglist-configuration by this push:
new 5dcbaea Update mailing-lists.md
5dcbaea is described below
commit 5dcbaeab2b0f9303d08681d98534786ebfb6bfa9
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Tue May 16 15:18:24 2023 +0200
Update mailing-lists.md
Added some content on configuring mailinglists
---
source/contributors/mailing-lists.md | 117 ++++++++++++++++++++++++++++++++++-
1 file changed, 116 insertions(+), 1 deletion(-)
diff --git a/source/contributors/mailing-lists.md b/source/contributors/mailing-lists.md
index 4014746..2b5d81b 100644
--- a/source/contributors/mailing-lists.md
+++ b/source/contributors/mailing-lists.md
@@ -52,5 +52,120 @@ beginners to break into your project, and find out what's going on.
Here's some configuration tips for your mailing lists to cut through the
noise and make your project's lists more approachable and welcoming.
-*To Be Written*
+Infra is providing some tooling to implement the automatically sent emails.
+There are generally two important parts:
+
+1. Where should stuff be sent
+2. How should the subject lines be built up
+
+Both these settings are done in your repositories `.asf.yaml` file.
+The full documentation of all features are documented [here](https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features)
+
+### Configuring where to send things
+
+In order to configure where to send emails, please add or update the
+`notifications` section in your `.asf.yaml`.
+
+```
+notifications:
+ commits: commits@foo.apache.org
+ issues: dev@foo.apache.org
+ pullrequests: dev@foo.apache.org
+ jobs: dev@foo.apache.org
+ discussions: dev@foo.apache.org
+```
+This will sort of make everything go to your `dev`-list.
+Some projects have sent some of these to other lists, as the amount
+of emails sent from GitHub was too excessive. I will explain in the
+next chapter how to make this flood of emails manageable.
+
+One thing that might be anoying, expecially for project with many
+third party dependencies, might be that dependabot will also be
+flooding your mailinglist with pretty atomic mini pull-requests.
+
+In many projects we therefore forward dependabot emails to the
+commits list.
+
+```
+notifications:
+ commits: commits@foo.apache.org
+ issues: dev@foo.apache.org
+ pullrequests: dev@foo.apache.org
+ jobs: dev@foo.apache.org
+ discussions: dev@foo.apache.org
+ # Send dependabot PRs to commits@ instead
+ pullrequests_bot_dependabot: commits@foo.apache.org
+```
+
+### 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:
+
+```
+github:
+ custom_subjects:
+ new_pr: "[PR] {title} ({repository})"
+ 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})"
+ catchall: "[GH] {title} ({repository})"
+ new_discussion: "[D] {title} ({repository})"
+ edit_discussion: "Re: [D] {title} ({repository})"
+ close_discussion: "Re: [D] {title} ({repository})"
+ close_discussion_with_comment: "Re: [D] {title} ({repository})"
+ reopen_discussion: "Re: [D] {title} ({repository})"
+ new_comment_discussion: "Re: [D] {title} ({repository})"
+ edit_comment_discussion: "Re: [D] {title} ({repository})"
+ delete_comment_discussion: "Re: [D] {title} ({repository})"
+```
+For some reason, the `repository` is required to be part of the pattern.
+Moving this to the end made the emails a lot more readable.
+
+### Conclusion
+
+The custom templates help make the GitHub content readable on your
+mailinglist it will therefore not feel as overwhelming as with the
+defaults. Moving dependabot to the commits lists, helped reduce the
+content with very little information.
+
+We would strongly encourage projects to keep as much of the discussions
+on their main mailingslist. If it's a larger project and still the
+volumne is so high, it's overwhelming people, think about directing
+some of the content to other lists.
+Simply directing all GitHub content to dedicated mailing lists or
+lists nobody reads doesn't help with keeping the community knowledge
+available. Even if it's "on the list" someweere, it doesn't really
+serve the reasoning behind the "If if didn't happen on the list,
+it didn't happen".