Subject: Atom revision tracking extension

From: Alistair Miles <[email-masked]>
Date: Tue, 2 Nov 2010 11:11:07 +0000

Hi all,

This is just a short note to say that we've done an implementation of James
Snell's 2006 I-D on a revision tracking extension [1], see the documentation
at [2].

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 had a trawl through the archive to see what else had been discussed,
and could only find threads from [5] and [6]. If I've missed anything,
please let me know.

Thanks,

Alistair

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

-- 
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: [email-masked]
Tel: +44 (0)1865 287669

---

From: Ed Summers <[email-masked]>
Date: Tue, 2 Nov 2010 08:39:00 -0400

Hey Alistair,

> [3] overlaps (see [4]). But for the most part, it works well as-is, for us

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

---

From: James Snell <[email-masked]>
Date: Tue, 2 Nov 2010 11:17:53 -0700

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.

---

From: Erik Wilde <[email-masked]>
Date: Tue, 02 Nov 2010 11:18:37 -0700

hello alistair.

> [2] http://code.google.com/p/atombeat/wiki/TutorialVersioning

http://tools.ietf.org/id/draft-brown-versioning-link-relations-07.txt is 
something that is more recent and seems to cover similar use cases, even 
though it's using only link relations instead of a mix of elements and 
link relations. the latest version of that is also expired (but not 
nearly as old as draft-snell-atompub-revision), but now that RFC 5988 is 
published, maybe a new version will be published soon?

and as a shameless piece of self-advertising, on 
http://dret.typepad.com/dretblog/atom-landscape.html i try to keep track 
of all those things. i just added draft-snell-atompub-revision to it, 
and draft-brown-versioning-link-relations was on there already. any 
feedback regarding this page is highly welcome!

thanks and kind regards,

erik wilde | mailto:[email-masked]  -  tel:+1-510-6432253 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Julian Reschke <[email-masked]>
Date: Tue, 02 Nov 2010 22:24:42 +0100

> published, maybe a new version will be published soon?

It has been published as RFC; why are you expecting a new version?

---

From: James Snell <[email-masked]>
Date: Tue, 2 Nov 2010 15:47:58 -0700

Ok, I was just looking over the old revision draft. I can definitely see a
number of key changes that can be made...

1. Drop the deleted-entry element in favor of the Atom Tombstones Draft
2. Drop all of the link-relations in favor of those defined in RFC5829
3. Refine the definition of ar:revision to:

     revision = element ar:revision {
       atomCommonAttributes,
       attribute label { text },
       attribute scheme { atomIRI }?,
       (atomAuthor?,
        atomUpdated?,
        atomSummary?,
        undefinedContent)
     }

    This gives us the simplest example:

     <ar:revision label="01" scheme="http://example.org/foo" />

    If we want to indicate who made the revision, when, and provide a
revision comment, we would do:

    <ar:revision label="01" scheme="http://example.org/foo">
      <author><name>James</name></author>
      <updated>2010-12-12T12:12:12Z</updated>
      <summary>Removed some stuff</summary>
    </ar:revision>

  4. I'd like to drop the ar: namespace and define the revision, comment and
host elements within the Atom namespace.

      e.g.:
      <entry>
        ...
          <revision label="01" scheme="http://example.org/foo" />
        ...
      </entry>

Thoughts?

---

From: Alistair Miles <[email-masked]>
Date: Thu, 4 Nov 2010 13:28:47 +0000

Hi James,

Very glad to hear you're still interested. 

> with any issues you think need to be resolved and I will update the draft

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

---

From: Alistair Miles <[email-masked]>
Date: Thu, 4 Nov 2010 13:43:14 +0000

Hi James,

> 1. Drop the deleted-entry element in favor of the Atom Tombstones Draft

+1

> 2. Drop all of the link-relations in favor of those defined in RFC5829

I think this might need a bit of discussion. 

Two possible issues here...

One simple issue, the mapping from link relations defined in your revision
tracking I-D to RFC5829 is incomplete...

history -> version-history 
diff -> ???
initial-revision -> ???
current-revision -> latest-version
this-revision -> ???
prior-revision -> predecessor-version
next-revision -> successor-version

We haven't actually implemented the diff relation, but we make heavy use of
"this-revision" - it's how a client navigates from a history feed (which
might contain an incomplete representation of each revision for efficiency
reasons) to a full representation of a specific revision.

Another possible issue is that RFC5829 anticipates source-code style versioning,
defining notions of "working copy" and "checkout". We don't have any need for
these notions, and it might be easier to get consensus on a new atom revision
tracking draft if we kept it simple and limited it to consider only provision
of revision history where versioning is transparent to the client.

>       <summary>Removed some stuff</summary>

+1 to add atomAuthor here

Also I suggest making it clear that the atom:summary element within ar:revision
is *the* place to put *the* revision comment for a specific revision.

Are you proposing to drop the @number attribute? What about @initial,
@final, @significant? I could live without @significant (not sure how this
is determined anyway) but @initial and @final are useful.

>           <revision label="01" scheme="http://example.org/foo" />

Doesn't matter to me either way.

I think also the intended/expected usage of the ar:comment element needs a
bit of discussion too.

Thanks,

Alistair

---

From: James Snell <[email-masked]>
Date: Tue, 9 Nov 2010 15:14:25 -0800

Alistair, thank you very much for the detailed comments. I will spend some
time updating and revitalizing the draft today. Once I post the updated
version, we can pick up the discussion from there.

On Thu, Nov 4, 2010 at 6:43 AM, Alistair Miles <[email-masked]>wrote:

> > On Tue, Nov 2, 2010 at 2:24 PM, Julian Reschke <[email-masked]
> >wrote:
> >
> > >
> > >> http://tools.ietf.org/id/draft-brown-versioning-link-relations-07.txtis

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 18 Nov 2010 12:23:20 -0700

On 11/9/10 4:14 PM, James Snell wrote:
> Alistair, thank you very much for the detailed comments. I will spend
> some time updating and revitalizing the draft today. Once I post the
> updated version, we can pick up the discussion from there.

Hi James,

Feel free to let me know when you think this document has reached
stability, then as your sponsoring AD I will start to push this along
towards publication as an RFC. The same goes for the tombstones draft.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: James Snell <[email-masked]>
Date: Fri, 19 Nov 2010 13:27:20 -0800

Peter, thank you. I'm planning on pushing out one more draft of Atom
Tombstones, Link Extensions and a refresh of the Atom Bidirectional
Attribute spec then asking you to push those forward as RFC's. The Revisions
and the Inline drafts need to go through a few more cycles I think. Updates
for those should come very soon.

- James