Re: Atom revision tracking extension

[Alistair Miles <[e-mail]>]

Hi James,

On Tue, Nov 02, 2010 at 03:47:58PM -0700, James Snell wrote:
> 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

+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.

> 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>

+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.

>   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?

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

> 
> On Tue, Nov 2, 2010 at 2:24 PM, Julian Reschke <[e-mail]>wrote:
> 
> >
> > On 02.11.2010 19:18, Erik Wilde wrote:
> >
> >>
> >> hello alistair.
> >>
> >> On 2010-11-02 4:11, Alistair Miles wrote:
> >>
> >>> 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].
> >>> [1] http://tools.ietf.org/html/draft-snell-atompub-revision-00
> >>> [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?
> >>
> >
> > It has been published as RFC; why are you expecting a new version?
> >
> >

-- 
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]