Bugs/Specs/FormattingBugNotifications

Not logged in - Log In / Register

Formatting Bug Notifications

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:

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 <thom.landis@example.com>
         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.

  2. Each callsite (callsite == any place where an IBugDelta is calculated) will publish a new event, IBugDeltaEvent, passing the IBugDelta when the event is published.

  3. generate_bugdelta_mail will subscribe to this IBugDelta event.

  4. 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:

Bugs/Specs/FormattingBugNotifications (last edited 2009-07-22 09:08:01 by allenap)