= Formatting Bug Notifications = * Created: 2005-05-23 * Author: BradBollenbach * Contributors: BjornTillenius, MatthewPaulThomas, ChristianReis * Status: DraftSpecification, MaloneSpecification, ImplementedSpecification * Queue: ChristianReisQueue * Implementation branch: `brad.bollenbach@canonical.com/launchpad--FormattingBugNotifications--0` == Introduction == There are various events in Malone (e.g. filing a bug, adding a comment to a bug, adding a task to a bug, resolving a task, etc.) which generate a notification email, sent to the BugNotificationRecipients list. This document describes the formatting of those emails. If you came here to learn about how emails are threaded in Malone, please see BugNotificationsThreading instead. === Rationale === Currently, the notification emails that get sent (particularly for things like filing a bug, adding a comment, etc.) are not particularly easy to read. It is our goal to address this problem for MaloneOneDotZero. == Use Cases == ''(Editor's note: We will merge BugEditNotifications into this spec after MaloneOneDotZero, but for now, this spec mainly addresses the remaining email formatting issues that weren't solved with BugEditNotifications.)'' In this document, we give particular focus to the formatting of the notification emails that get sent after one or more of the following events occur in Malone: * filing a bug * commenting on a bug * adding a task to a bug * adding a web link * adding a cve ref * adding a external bug watch We will ignore spec'ing out infestation notifications until we better understand how we intend to use them in Malone. == Implementation Plan == === Schema Changes === There are no schema changes to make. === Data Migration === There is no data migration to be done. === UI Changes === The format of these emails completely disregards trying to be consistent with the look and feel of the MaloneCommandInterface (much like BugEditNotifications.) Trying to honour the MaloneCommandInterface when formatting notification emails makes them harder to read. '''Notification Headers''' {{{ Date: Mon, 23 May 2005 14:24:26 -0700 Subject: [Bug 42] Firefox loses form content To: mark@canonical.com From: Mark Shuttleworth via Malone <42@bugs.ubuntu.com> }}} The From: header will contain the name of the person that made the change. It is intended to help someone scanning their Inbox to "weight" each mail. We intend for users to take advantage of the X-Malone-BugXXX headers to filter and sort their mail if they want to, but being able to quickly scan your "critical" folder for reports from your manager can be quite useful. :) It's also intended to be clear that this email came through Malone ("...via Malone") and show the email address that will be replied to, rather than confusing the user with Reply-To trickery. A bugmail will be delivered to each recipient individually. By avoiding including the entire recipient list in the To and/or Cc, we avoid the issues that come up with Reply-To-All and users receiving two messages. We plan to user test this approach to see how people like it, and adapt it to their needs, as necessary. For the time being, we will also ignore any bugmail Cc's that aren't subscribers of the Malone bug. E.g. if you followup to comment and Cc bob@example.com on that reply, Malone will ''not'' include bob@ in its system notification email. This behaviour is subject to change. For a deeper discussion of the notification headers see BugNotificationsHeaders. '''Notification of bug filed''' {{{ Public bug reported: https://launchpad.ubuntu.com/malone/bugs/42 Affects: mozilla-firefox (Ubuntu) Severity: Critical Priority: Normal Status: New Description: I enter some data into Bugzilla, using Firefox. I accidentally submit it. I click back to make changes, and whoop, the data I entered is gone! }}} A bug filing could also add more than one task at once: {{{ Private bug reported: https://launchpad.ubuntu.com/malone/bugs/42 Affects: mozilla-firefox (Ubuntu) Severity: critical Priority: normal Status: new Explanation: This is a big problem in Ubuntu because the bug occurs on every page of the ubuntu.com store. Affects: Mozilla Firefox (upstream) Severity: major Priority: high Assignee: thom Status: New Description: I enter some data into Bugzilla, using Firefox. I accidentally submit it. I click back to make changes, and whoop, the data I entered is gone! }}} It would be nice to include a footer in this email that gives a link to Malone (and a small note about why you got this email) but I don't think I'd want to see a link to a Malone front page in an email until MaloneFrontPages is implemented. '''Notification of comment added''' An example of how this might look if the user created the comment by replying to an email: {{{ Public bug report changed: http://localhost:8086/malone/bugs/6 Comment: On Mon, 23 May 2005 14:24:26 -0700, Mark Shuttleworth via Malone <42@bugs.ubuntu.com> wrote: > I enter some data into Bugzilla, using Firefox. I accidentally submit > it. I click back to make changes, and whoop, the data I entered is > gone! Is the URL you're accessing an http or https? Cheers, -- Brad Bollenbach }}} An example of how this might look if the user created the comment via the web UI (note that there's no "made changes to" line because, other than adding the comment, the user didn't actually "make changes" to the bug): {{{ Private bug report changed: http://localhost:8086/malone/bugs/6 Comment: Is the URL you're accessing an http or https? }}} '''General add/edit notification''' {{{ Public bug report changed: http://localhost:8086/malone/bugs/6 Title changed to: Loss of form data when going back to HTTPS page Bug watches changed: + https://bugzilla.mozilla.org/show_bug.cgi?id=123 CVE references changed: + CAN-2004-0648 [some title] - CAN-2004-0718 [some title] Summary changed to: This is a big fat bug that nobody cared to fix and now it's too late. Description changed to: I enter some data into Bugzilla, using Firefox. I accidentally submit it. I click back to make changes, and whoop, the data I entered is gone! This only happens for HTTPS URLs. Visibility changed to: Private Changed in: mozilla-firefox (Ubuntu) Status: New => Accepted Explanation: Probably won't get to this myself for Breezy, any takers? Also affects: Mozilla Firefox (upstream) Severity: Normal Priority: Normal Status: New Target: 1.0.5 Comment: This bug rocks. }}} This example demonstrates the layout when many things are edited at once. Though the web UI doesn't currently support this, I feel that it should some day soon. The email UI is designed to allow the edits of many things at once too. === Code Changes === {{{canonical.launchpad.mailnotification.generate_bug_edit_email}}} will be renamed to {{{generate_bugdelta_email}}}, because its purpose is not limited only to when bugs are edited, and because one of its arguments will be an {{{IBugDelta}}}. We will take the following steps to set up our object created/modified bugmail handlers to support "batching" of change notifications (i.e. so that modifying two tasks and the description on a bug will generate exactly one bugmail, instead of three!): 1. The code in the existing subscriber functions in {{{canonical.launchpad.mailnotification}}} (including, but not limited to {{{notify_bugtask_edited}}}, {{{notify_bug_comment_added}}}, {{{notify_bug_external_ref_added}}}, etc.) will be moved into the relevant view classes for their respective object add/edit screens. Logically, this means that the ZCML configuration that had these functions subscribed to {{{SQLObjectCreatedEvent}}} and {{{SQLObjectModifiedEvent}}} will be removed, as it's no longer relevant. 1. Each callsite (callsite == any place where an {{{IBugDelta}}} is calculated) will publish a new event, {{{IBugDeltaEvent}}}, passing the {{{IBugDelta}}} when the event is published. 1. {{{generate_bugdelta_mail}}} will subscribe to this {{{IBugDelta}}} event. 1. {{{generate_bugdelta_mail}}} will be modified to support the notification format specified further down. We've already done most of the hard work of coding this when we implemented BugEditNotifications. We have an {{{IBugDelta}}} and utility functions to calculate bug and task deltas. Most of the coding work will be in modifying {{{generate_bug_edit_email}}}. == Discussion == Some things to keep in mind for down the road: * (from bradb): I had a brainstorm idea to make it such that bugmail should be addressed To: assignees and the submitter directly, and Cc'd to anyone else in the recipient list. mpt thought this was an "excellent idea". stub liked it too, though pointed out the problems that reply-to-all could pose if anything other than just the bugaddress is in the To: line. There's the possibility of [[http://cr.yp.to/proto/replyto.html|using the Mail-Followup-To field]] though not all mail clients support it. OTOH, launchpad@ seems to be configured to work this way by default. :) * (from bradb): I've put the address bugs.ubuntu.com in this example, because that's what I've been told is our bugmail address hostname at the time I was writing this. But I feel that this might be a poorly branded address for an email that claims that it came from Malone. mpt also agreed that this "sounds like an address for mail about bugs in Ubuntu exclusively." For the time being, we've agreed to leave the address as is, but we may have more news on this in the near future.