Flow/Functional Specifications/History

This document describes a set of functional requirements regarding the display of history pages in Topics and Posts for Flow.

This document should not be taken as a final descriptor for any one specific release of the software, though recommendations regarding inclusion in the "Minimum Viable Product".

"Diffs" and Edit Summaries
In many cases, Flow does not have a concept of a "diff" nor does it have a need for edit summaries. When replying within a conversation, the action is typically atomic: a single reply is posted. Since Topics themselves are an accretion of content objects rather than continual modification of a singular text blob, there is no easy, compelling, or usable way to display specific changes in the conversation structure.

For certain, if a text item is modified, a diff view must be provided, but in the bulk of cases and log lines this will not be possible or even desired.

Further, in most cases, edit summaries are not required. The content of the Post is just that; the edit summary remains along the logical lines of "a reply was posted". Change summaries are requested (or required) for certain edits (say, when closing a Topic, or deleting one) but it may be desirable to automate this as much as possible.

From this it becomes obvious that history logs for Topics (and Boards) will be different than standard MediaWiki history pages.

The first difference is one of scope. In Flow, histories can be scoped scoped along object lines (though this is not how users think of them):


 * Board
 * Topic
 * Post
 * Summary
 * Scratchpad

Some elements (Post, Summary, Scratchpad, Board headers) are atomic (and will have object-level histories), while others are conglomerate and will have collected histories.

For example, when viewing the history of a Topic, the view will also include the history lines for all the Posts that are contained within the Topic. Likewise, viewing a Board's history will also show information about Topics (but not necessarily about Posts).

Open Questions
An area of concern is information density and pollution, especially at the "highest" or super-set level of history view. Does it make sense to include Post-level changes when viewing the history at the Board level? Would it be too much clutter, or would lack of detail prove to be limiting and make the view useless?

Of further interest is the idea that a Board has relatively few actions that are "historical" to it. Topics are not really organic parts of a Board (that is, a Board is not comprised of Topics in the same way a Topic is comprised of Posts). Rather, Boards are more akin to containers of pointers to Topics.

Historic Events
A line in the history log shall be created when the following events happen. Suppression activities may change the visibility of a log line.

Board Level

 * The Board header is created
 * The Board header is modified
 * The Board header is deleted
 * An edit to the Board header is suppressed
 * A new Topic is created
 * A Topic is attached to the Board
 * A Topic is split (similar to created but logged as a different action)
 * Multiple Topics are merged
 * A Topic is hidden
 * A Topic is restored (unhide)
 * A Topic is deleted
 * A Topic is undeleted
 * A Topic is suppressed
 * A Topic is unsuppressed

Topic Level

 * The Topic is created
 * The Topic title is modified
 * The Topic is moved (between Boards)
 * The Topic is attached to a foreign Board
 * The Topic is closed
 * The Topic is re-opened
 * The Topic is hidden
 * The Topic is restored (unhide)
 * The Topic is deleted
 * The Topic is undeleted
 * The Topic is suppressed
 * The Topic is unsuppressed
 * The Topic is Summarized
 * The Topic Summary is modified

Post Level

 * The Post is created
 * The Post is edited
 * The Post is hidden
 * The Post is restored (unhide)
 * The Post is deleted
 * The Post is undeleted
 * The Post is suppressed
 * The Post is unsuppressed
 * The Post is moved to a new Topic (split or merged)

Scratchpad Level

 * A Scratchpad is created
 * The Scratchpad is edited
 * The Scratchpad is hidden
 * The Scratchpad is restored (unhide)
 * The Scratchpad is deleted
 * The Scratchpad is undeleted
 * The Scratchpad is suppressed
 * The Scratchpad is unsuppressed

Summary Level

 * A Summary is created (separately from Topic closure)
 * The Summary is edited
 * The Summary is hidden
 * The Summary is restored (unhide)
 * The Summary is deleted
 * The Summary is undeleted
 * The Summary is suppressed
 * The Summary is unsuppressed

General Thoughts
History pages for Flow should not be displayed as simply (and ugly) as normal Mediawiki history lines. They should be broken up with smaller headers for each month. They should be in tables, with hard column edges and row stripes.

Datestamps should be in full format (not time relative). This is a different viewing mode than the conversation mode.

Board History


Board histories will track only "Board level" events. Topic level events will not appear here, though links to the Topic history screens will exist.

Within the table, clicking on the Topic title (or the "view" link) will bring the user to the "Single Topic" view of the Topic. Clicking on the "History" link will zoom the user to the Topic history view.

Clicking on a datestamp should bring the user to the Board view as it existed at that time. This may not be performant, however (lots of extra calls).

In cases where a diff view is available, a link is provided to it. This will go to a standard Mediawiki diff page.

Note that many standard control options found on history pages are missing. This is either because they do not make sense in the context of the structured data format or because there are in-situ controls (e.g., restoring hidden posts). We do not want people mucking with content without actually seeing the content they are mucking with.

Affordance Issue
Typically, histories for pages are accessed via a "History" tab. However, Flow Boards are technically "Special" pages (which do not have histories). Most Flow Boards will be accessed through "talk" namespaces (which do have "History" tabs.) Whether or not there should be a "History" tab becomes a question.

For consistency's sake, it is the current recommendation to have a History tab on the Board, which then leads to the Board history. This may create user confusion, however - especially if experienced editors go to it assuming that they can find Topic-level histories.

Note that better options are being explored.

Topic History


Topic histories will typically open in modal dialogs, though they are in effect "pages".

Clicking on the "comment" link will bring the user to the Single Topic view of the page, scrolled to that specific Post. The Post will be highlighted. Clicking on any datestamp will bring the user to a permanent link for the Topic at that point in time.

Post History


Post histories shall behave in most regards like standard MediaWiki history pages. When accessed from the Flow interface, they will appear in modal dialogs. It is worth noting that the only way to access only a Post's history from the interface is if it has been edited. The only other way to access Post changes is through the Topic history.

In Situ Post Modification Notice
If a Post has been modified, a notice shall appear in the Post indicating that the Post has been modified, by whom, and when. This notice will contain an affordance that will show the user the diff between the two revisions (a normal MediaWiki diff) in a modal dialog as well as a link to the User page of the User who made the edit.

If multiple people have made edits to the Post, only the most recent editor will be named but the count of editors will be displayed ("Modified 25 minutes ago by Username and 2 others").