Re: Usage Scenarios for Versioning and Extensibility

[Joe Gregorio <joe.gregorio@xxxxxxxxx>]

On Mon, 12 Jul 2004 17:14:54 -0700, Mark Nottingham <mnot@xxxxxxxx> wrote:
> 
> On Jul 12, 2004, at 2:47 PM, Dare Obasanjo wrote:
> 
> > My primary use case for versioning is simple. How can
> > an aggregator which encounters a different version of
> > Atom from one its seen before know whether it is
> > backwards compatible or not? With RSS, the assumption
> > I use in RSS Bandit is that all feeds are RSS 2.0 and
> > the version attribute is ignored.
> 
> I'd like to make this a bit more concrete.

Thanks for setting this conversation on solid ground.
I've tried to fill out the examples using Tim's model.

>
> 0) Let's imagine that Atom 1.0 has been released and finalised in all
> of its glory.

<feed version="1.0" xmlns="atom" ...
   <title>My Stuff</title>

> 
> 1) And it was good... except for that nasty atom:title element; after
> wide deployment experience, it's agreed we need a new version of it.
> So, a new version of Atom is introduced. The new one isn't
> backwards-compatible with the old one.

I would argue against making  a non-backward compatible
change to an element. How about 
introducing a new 'super-title' element in a 2.0 release:

<feed version="2.0" xmlns="atom" ...
   <title>My Stuff</title>
   <super-title>My Extended Stuff</super-title>


> 2) Then, we decide we want to add a new metadata element, let's call it
> "fog." So, a new version of Atom is introduced.

<feed version="3.0" xmlns="atom" ...
   <title>My Stuff</title>
   <super-title>My Extended Stuff</super-title>
   <fog/>


> 3) After a while, someone comes up with a souped-up version of
> atom:title that is backwards-compatible, just *better*. It gets really
> popular, and yet another version of Atom is born.

Note that title and super-title are both
legal but 'super-title' is depracated.

<feed version="4.0" xmlns="atom" ...
   <title>My Stuff</title>
   <super-title>My Extended Stuff</super-title>
   <fog/>


> 4) At the same time, a group of rogue Open Source Software programmers
> descends upon this idyllic scene and introduces its own extensions. Up
> until now, all of our extensions have been approved and incorporated by
> the WG, but these are destined to remain separate.

All of these go in their own namespaces. It is up to 
the authors of those extensions to flag which 
versions of Atom that they interoperate with.

<feed version="4.0" xmlns="atom" ...
   <title>My Stuff</title>
   <super-title>My Extended Stuff</super-title>
   <fog/>
   <foo:bar/>

> 5) Finally, in 2010, we realise that the Atom feed and entry containers
> aren't really doing the job, and we need to change their model. Yet
> Another Version of Atom (YAVA) comes into being.

That is a rather fundamental change for which I would hope
you would select another namespace and mime-type:

<notfeed version="1.0" xmlns="something-besides-atom" ...
   <title>My Stuff</title>
   <super-title>My Extended Stuff</super-title>
   <fog/>
   <foo:bar/>

> Any proposal for versioning should address at least these situations,
> show how the various extensions and changes are identified and
> disambiguated, and should explain how software is to handle them. They
> should also consider how combinations of these scenarios are handled.

Tim's policy seems to work, but with the following caveat/addition:

1. Newer versions of the format are kept backward 
compatible with older versions. Note that in these examples that 
was done by not changing an element in a non-backward compatible 
way but by introducing a new element. Note that in step 1.0 the
'super-title' could have also been introduced as 'title' but in
a different namespace. If you must break 
backward compatibility do it in a new format/namespace/mime-type.

I will also note that the use of mustUnderstand is not 
of use in any of the above scenarios. Are there other 
formats where 'mustUnderstand' semantics have been
successfully deployed? I don't think SOAP's history 
with mustUnderstand is one to point to as representing
'success'. [1]


[1] http://www.pocketsoap.com/weblog/soapInterop/base.html

    Thanks,
    -joe