Re: Atom revision tracking extension

[Alistair Miles <[e-mail]>]

Hi James,

Very glad to hear you're still interested. 

On Tue, Nov 02, 2010 at 11:17:53AM -0700, James Snell wrote:
> Very nice to see some of this old work being revisited. I am all for
> updating and revitalizing the draft so long as there are people taking the
> time to implement and provide feedback. If you can, please post a note here
> with any issues you think need to be resolved and I will update the draft
> accordingly.

I know you've suggested some changes already in [1], but to start with let me
just describe the issues we encountered and how we worked around them, I'll
respond to your suggestions in [1] in a separate mail.

To begin with, our use cases all fit into the following pattern: 

A set of one or more users is editing a web resource. The edits to the
resource are sequential. The resource might, e.g., be a blog entry, or a
metadata record describing methods used in a scientific study, or a table of
scientific data, or a record of some data processing operation. 

At some point, one of the users wants to retrieve and view a summary of
the revision history for the resource. The summary should contain for each
revision, a revision number, when the revision was made (datetime), the user
who made the edit, and a revision comment. Typically, the revision history
is displayed as a table, something like:

| Revision Number | When                      | User   | Comment     | Link                  |
==============================================================================================
| 1               | 2010-10-15T16:34:32+01:00 | aliman | first draft | [link to view revision]
| 2               | 2010-10-16T17:44:32+01:00 | audrey | 2nd draft   | [link to view revision]
| etc.

The user may then want to view a specific revision, and possibly navigate
to view previous or subsequent revisions.

A - revision author identity

The main issue we had with the current draft [2] was how to reliably represent
the identity of the user who was responsible for a specific revision. We
naturally thought to include that information within the ar:revision element,
but [2] defines ar:revision as an atomTextConstruct, so the only way we could
think to capture the user identity for each revision (without our own extension
element) was in the ar:comment element which permitted atom:author as a child.

However, to ensure that the revision author identity was always present and
unambiguous and could not be interfered with by clients, we had to place
the ar:comment element under server control. I.e., when a client makes an
update to a collection member, our implementation automatically generates
an ar:comment element and populates it with the identity of the user (which
it has because the user is authenticated). Any ar:comment elements added by
the client are stripped out by the server prior to processing.

B - revision comments

The second issue we had is related to the above, but not entirely
identical. The issue is how the client provides a revision comment when making
an update. 

Because we place the ar:comment element entirely under server control,
and stripped any such elements provided by a client, we obviously had
to find another mechanism by which a client could provide a revision
comment when making an updated. Our solution was to use an HTTP header -
"X-Atom-Revision-Comment". I.e., when making a PUT request to update the
member, the client can provide a value for this header, which the server
uses to populate the ar:comment element.

However, even without issue A, there are still issues around how the client
provides a revision comment when editing the resource. E.g., if the only
means they have of supplying a revision comment is to insert an ar:comment
element into the entry they are about to update, then this raises practical
difficulties. For example, to ensure that the comment is unambiguous, the
client would have to ensure that any previous ar:comment elements were removed
from the entry, prior to making the update request. This is not difficult,
but it does add an additional chore to coding every single client, and also
means that the operation of the versioning system is not entirely transparent
to the client.

For these reasons, even without issue A, we would prefer to define an HTTP
header which may be used by a client to supply a revision comment when
making a request to create or update a resource. If the client choses not
to make use of this header, that's fine, they can update the web resource
without any knowledge of the presence or absence of an underlying versioning
system. The server implementation can use any such header present in update
requests to store an unambiguous revision comment log for the resource.

C - tombstones

Obviously, the new tombstones draft defines syntax for deleted entries, so
it makes sense to remove any overlapping syntax in the revision tracking draft.

We initially did not implement the deleted-entry features of the revision
tracking draft in our versioning plugin [3], but added these subsequently as
part of the tombstones plugin [4].

--
I think that's it. As I said, otherwise everything makes sense, and
implementation was relatively straightforward.

Cheers

Alistair

[1] http://www.imc.org/atom-syntax/mail-archive/msg21585.html
[2] http://tools.ietf.org/html/draft-snell-atompub-revision-00
[3] http://code.google.com/p/atombeat/wiki/TutorialVersioning
[4] http://code.google.com/p/atombeat/wiki/TombstonesDesign

> 
> On Tue, Nov 2, 2010 at 5:39 AM, Ed Summers <[e-mail]> wrote:
> 
> >
> > Hey Alistair,
> >
> > On Tue, Nov 2, 2010 at 7:11 AM, Alistair Miles <[e-mail]>
> > wrote:
> > > Generally speaking, we've found this to be a very useful feature in
> > several
> > > applications, and would be interested in revisiting James' original I-D
> > if
> > > anyone else was.
> > >
> > > I think the draft would need updating to deal with a couple of relatively
> > > minor issues we've worked around, and the fact that the new tombstones
> > draft
> > > [3] overlaps (see [4]). But for the most part, it works well as-is, for
> > us
> > > at least.
> >
> > I would definitely be interested in a revision to Atom Syndication
> > Format Revision Tracking [1] to work better with Atom Tombstones [2],
> > and also Link Relation Types for Simple Version Navigation between Web
> > Resources (RFC 5829) [3].
> >
> > I'd be curious to hear how you are using the extension in the work you
> > are doing, if you had a blog post in you, or if it could be posted
> > here. Being able to express version relations on the web is very
> > important for digital library applications.
> >
> > //Ed
> >
> > [1] http://tools.ietf.org/html/draft-snell-atompub-revision-00
> > [2] http://tools.ietf.org/html/draft-snell-atompub-tombstones
> > [3] http://tools.ietf.org/search/rfc5829
> >
> >

-- 
Alistair Miles
Head of Epidemiological Informatics
Centre for Genomics and Global Health <http://cggh.org>
The Wellcome Trust Centre for Human Genetics
Roosevelt Drive
Oxford
OX3 7BN
United Kingdom
Web: http://purl.org/net/aliman
Email: [e-mail]
Tel: [phone]