Labs/Bespin/DesignDocs/TimeMachine

Time Machine

Time Machine is designed to solve 2 basic problems in Bespin: - Allow users to get the text back that someone else deleted - Allow viewing the evolution of some text over time

API

It is currently expected that we will need to create a new API and enhance another.

Historical Revision Information

This new server API allows clients to get at a list of changes to a file over time.

The URL would probably match the /preview/at and /file/at style, so we would use /history/at/project/path

A call to this URL would return a 404 or similar error if the request could not be completed. On success the JSON data structure would look like this:

[
  {
    source: [vcs|save|undo],
    id: "564129cea41d",
    date: "Mon Aug 17 2009",
    owner: "jwalker",
    size: 0.4,
    description: "Automated merge with ssh://hg.mozilla.org/labs/bespin/"
  },
  { /* further revisions */ }
]

The members are as follows:

• source: 'vcs' indicates that the change comes from the VCS system registered with the project. There can be at most one VCS repo per project. The date, owner and description fields probably come from a call to 'vcs log' or similar.
• id: An arbitary unique ID for use with revisions to the '/file/at' call. Most (all?) VCSs give revision identifiers. Bespin will generate IDs for save|undo sources.
• date: We will need to specify a format for the time.
• owner: VCS specified username for VCS originated change. Bespin specified for other types of change. To begin with, we do not expect to link VCS usernames to bespin usernames. This linkage could be useful over time.
• size: The size field comes from something like 'diff $file | wc -l' / 'cat $file | wc -l' (clearly that won't work exactly, but the point is the same).
• description: Simple in the VCS case. For the 'save' source we might take the users status on save. For the 'undo' source we might take an editor provided description of the action e.g. 'typing', 'format source'.

Issues

• How do we handle VCS rename/copy operations? Is it valid to include changes made under an old filename and ignore the fact that the file may no longer be valid in its new position.
• Can we tie bespin usernames to VCS usernames. Tying them together will helps colorization to be consistent.
• Can we create descriptions (e.g. 'typing', 'format source') out the back of mobwrite?
• Can we create descriptions for save commands?
• Is what comes out of mobwrite going to be too granular
• How are we going to store all this data?
• Can we create a useful size parameter? Is this going to be viable for SVN and other non-D VCSs?
• Is there any benefit in transmitting the diff with the rest of the history? We are currently assuming that there isn't because the files are easily accessible, and only a diff might be slow to make use of if you need to work from the start/end. Also diffs prevent us from interleaving sources.
• For none-D VCSs, what's the performance going to be like? Can we use git svn to mitigate the issues?

Access to older revisions

The current plan is to modify the '/file/at' URL to add a 'version' parameter, which specifies the version of the given file.

• /file/at/project/path?version=id

Issues

• Do we need to give access to deleted files. Is there an API for discovering what they are?
• We probably need to easily distinguish the source of a version id without needing to go to vcs / save history and mobwrite in turn.
• What is non-D VCS performance going to be like? (See above)

User Interface

See Dions's blog post for example UI:

Issues:

• Does the change/time scrubber only work when horizontal?
• Can we conserve vertical screen real-estate
• Can we have a fancy fish-eye visualization to save scrolling?