= Activity Log Interleaving =

== Preamble ==

We would like to display all bug activity interleaved with the comments on the main bug page, and ditch the +activity page.

But first we need to think about how we record activity because there are some issues there.


== Recording activity ==

Currently we use the `BugActivity` table, but this has a ''far'' from complete record of activity. By contrast, the `BugNotification` table (which references `Message` and thus `MessageChunk`) contains a fairly consistent and comprehensive record which can be readily parsed. However, it only contains information about events that subscribers have been notified of.

In short, many events which we would like to show in the UI are not being recorded.

Some ideas:

 1. Derive entire activity log from `BugNotification`. Events that we currently do not record would be recorded in `BugNotification` too, but marked using a new ''not a notification'' field, or by replacing `BugNotification.is_comment` with an enum. `BugActivity` would be dropped.

 2. Derive entire activity log from `BugActivity`. This would mean recording many more events in `BugActivity` than we currently do. It would also mean that a lot of activity information will be recorded in both `BugNotification` and `BugActivity`.

 3. Derive a lot of the activity log from `BugNotification`, and use `BugActivity` for other events. This would mean recording a few more events in `BugActivity` than we currently do.

After much discussion, we've come to the conclusion that we can actually use the existing `BugActivity` table, with some work having been done on it, to provide the data we need for interleaving changes with comments in the UI. See [[VersionThreeDotO/Bugs/CompleteActivityLog|CompleteActivityLog]] for details of what we intend to do.

Additionally, we require that all activity logs are recorded purely as '''text''', with the exception of the person performing the action, for which a field already exists in `BugActivity`. The alternative is to have a column for every possible activity reference, but we felt that was overkill. We only require that the activity log be useful for human consumption, and that it is correct at the time of recording activity.


=== Guidelines ===

 1. The existing fields of `BugActivity` should be used, with the exception of `message`, which is deprecated.
 1. The `what_?changed` field currently often specifies `"bug"` as what changed, but this is somewhat implied by the naming of the table, and is often inaccurate. Rather, `what_changed` should be a record of what kind of ''activity'' has occurred, for example:
  * `subscriber added`, `subscriber removed`
  * when a bugtask is altered: `$bugtarget_name: $property_name`
  * `branch linked`, `branch unlinked`
  * ...
 1. `oldvalue` and `newvalue` should be used for every entry. For additions, like `subscriber added`, `newvalue` should be populated. Likewise, `oldvalue` should be populated for removals.


== Displaying activity ==

 * Activity should be grouped by person and time, so that multiple changes in one request are displayed as one action.
 * They should be placed in a similar style box as comments.
 * To simplify implementation, they don't need to be visually merged with any corresponding comments.
 * `bugtask-index.pt` loops over the results of `getBugCommentsForDisplay()`, passing each comment to the `comment-box` macro. This view method could be changed to `getBugDialogueForDisplay()`, which would return a list of interleaved comments and activities.
 * We can display activity records as pure text for the time being, something like this:

{{attachment:bug_comments.jpg}}

{{{
+--------------------------------------------+---------------------+
| malone: importance Undecided --> Critical  | Foo Bar, 1 hour ago |
| malone: assignee Nobody --> Foo Bar        +---------------------+
| malone: status New --> Confirmed                                 |
+------------------------------------------------------------------+
}}}

 * For large blocks of text, we could display an expandable box:

{{{
+---------------------------------------------+---------------------+
| > Description Updated                       | Foo Bar, 1 hour ago |
+---------------------------------------------+---------------------+
}}}

 * When this is expanded, we'll see:

{{{
+---------------------------------------------+---------------------+
| V Description Updated                       | Foo Bar, 1 hour ago |
|                                             +---------------------+
| This is the new description. We don't show the old one here, at   |
| least not in the first iteration of implementing this spec.       |
+-------------------------------------------------------------------+
}}}

 * Changes to Summary and Description will always be shown in their own expander boxes, even when the changes have been made at the same time.

 * To display these correctly, we'll define a `BugActivityView` and subclass it for each different type of `BugActivity` that needs to be displayed distinctly from the others. These views can then use templates to render the `BugActivity` records correctly.