Include `List-Id` in Epics email notification
Problem to solve
We are not compliant with the "mailing list" type of emails when sending notifications for epics.
While we include a List-Unsubscribe
header, we are not including a List-Id
which makes creating email filters harder.
Intended users
- Sasha (Software Developer)
- Parker (Product Manager)
- Presley (Product Designer)
- Devon (DevOps Engineer)
- Sidney (Systems Administrator)
(basically anyone that receives email notifications as their normal workflow)
User experience goal
When opening and email from an Epics discussion, it should have a "Filter messages from this mailing list" as per: https://googlesystem.blogspot.com/2007/11/filter-messages-from-mailing-list-in.html
Proposal
Generate a List-Id
for Epics (and think about a pattern for other group-level notifications).
Based on existing one from projects:
headers['List-Id'] = "#{@project.full_path} <#{create_list_id_string(@project)}>"
We should either prefix or suffix what we we referring to. Because we are not using .projects
and .groups
as prefix, and breaking existing List-Ids are not ideal, I suggest we addopt suffix for group level things:
"List-Id: gitlab-org/-/epics <#{group.id}.groups.gitlab-org.gitlab.com>"
The chances that there will be a "project" under a group, named "groups" with the same base ID as the actual group, is almost zero. If that happens, the only side-effect will be that filtering just for List-Id
will bring notifications from the two sources together.
This proposal would not allow to filter the "type" of notification source (Epics vs other future group-level items)
This can be solved by addopting the following pattern instead:
"List-Id: gitlab-org/-/epics <#{epic.id}.epics.#{group.id}.groups.gitlab-org.gitlab.com>"
Further details
This is an example of the relevant data that is included for an email coming from a project:
X-GitLab-Project: GitLab Kramdown
X-GitLab-Project-Id: 5647182
X-GitLab-Project-Path: gitlab-org/gitlab_kramdown
List-Id: gitlab-org/gitlab_kramdown <5647182.gitlab-kramdown.gitlab-org.gitlab.com>
List-Unsubscribe: <https://gitlab.com/-/sent_notifications/.../unsubscribe?force=true>,<mailto:incoming+...-unsubscribe@incoming.gitlab.com>
X-GitLab-MergeRequest-ID: 58595022
X-GitLab-MergeRequest-IID: 37
X-GitLab-NotificationReason:
X-GitLab-Discussion-ID: c2a5557c2c4e38b318d8364fcc7e42dedb27fdc3
X-GitLab-Reply-Key: ...
And this is from an Epic:
X-GitLab-Group-Id: 9970
X-GitLab-Group-Path: gitlab-org
List-Unsubscribe: <https://gitlab.com/-/sent_notifications/.../unsubscribe?force=true>,<mailto:incoming+...-unsubscribe@incoming.gitlab.com>
X-GitLab-Epic-ID: 4883
X-GitLab-Epic-IID: 893
X-GitLab-NotificationReason:
X-GitLab-Reply-Key: ...
List-Id
syntax is governed by this RFC: https://tools.ietf.org/html/rfc2919