OpenSocial Gadget Specification & Feature Versioning patch [v1.0]

First cut of versioning proposal for standard gadget features and the gadget XML/processing specification.

[Lane, 2009-11-17 18:16:29]

+1 - Great job, Tim!

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode500
draft/OpenSocial-Gadget-XML.xml:500: they provide.</t>
This last sentence may be more appropriate for the "Extensions" section of the
main spec file.  I guess it can't hurt to reiterate here.

http://codereview.appspot.com/152136/diff/1/2#newcode842
draft/OpenSocial-Gadget-XML.xml:842: <c>views</c>
views is part of core as of 0.9.  I know you didn't introduce this issue, but
can you fix it please.

[Jon Weygandt, 2009-11-18 01:04:32]

Overall, on the default versions: if they always default to 1.0, then the
developer when changing from specification 1.0 to 2.0 MUST set all the versions
of the features to use the latest. I see this as a headache.

Proposal: 

Each version of the OpenSocial specification shall state what the default
version is of their core features. 

Extensions shall state what the default version is for each existing OpenSocial
specification. Lacking specific default declaration... (the words get ugly, but
since versions can be compared numerically we can work something out if this
path is acceptable).

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode195
draft/OpenSocial-Gadget-XML.xml:195: MUST return true; otherwise it MUST return
false. Developers SHOULD use
Is this small addition in conflict, or redundant with text around line 790?

http://codereview.appspot.com/152136/diff/1/2#newcode541
draft/OpenSocial-Gadget-XML.xml:541: containers MUST conform to the exact
version of the specification or
For both minor and patch versions, should it be relaxed to state: "When all
three (or two) version components are specified containers MUST deliver a
version backward compatible with the specified version.". For instance if 1.1.3
is requested, then 1.1.3, 1.1.4, 1.5.3 are valid, but 2.0.0 or 1.1.2 is not.

http://codereview.appspot.com/152136/diff/1/2#newcode784
draft/OpenSocial-Gadget-XML.xml:784: to Developers when a conflict is
detected.</t>
If I "Require opensocial version 2.0" and "Optional opensocial-data version 1.0"
will the gadget deploy and render, with hasFeature returning false for
opensocial-data?
That's how I would read this, but it is not totally clear.

[Tim Moore, 2009-11-23 21:57:22]

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode195
draft/OpenSocial-Gadget-XML.xml:195: MUST return true; otherwise it MUST return
false. Developers SHOULD use
On 2009/11/18 01:04:32, Jon Weygandt wrote:
> Is this small addition in conflict, or redundant with text around line 790?

It wasn't added, just moved it out of the description for the @feature attribute
to the description for the element as a whole. I moved it because I didn't want
to imply that support is based on the name of the feature alone.

I read it to be redundant with the text around 790 (i.e., not conflicting) but I
think it makes sense to restate it here for clarity. What makes you think there
is a conflict? I'm open to suggestions for clarifying it.

http://codereview.appspot.com/152136/diff/1/2#newcode500
draft/OpenSocial-Gadget-XML.xml:500: they provide.</t>
On 2009/11/17 18:16:29, Lane wrote:
> This last sentence may be more appropriate for the "Extensions" section of the
> main spec file.  I guess it can't hurt to reiterate here.

It probably makes sense to include it in both places, but I'm afraid that I'm
not sure which section of which file you're referring to. Is that section
something that hasn't been committed yet?

http://codereview.appspot.com/152136/diff/1/2#newcode541
draft/OpenSocial-Gadget-XML.xml:541: containers MUST conform to the exact
version of the specification or
On 2009/11/18 01:04:32, Jon Weygandt wrote:
> For both minor and patch versions, should it be relaxed to state: "When all
> three (or two) version components are specified containers MUST deliver a
> version backward compatible with the specified version.". For instance if
1.1.3
> is requested, then 1.1.3, 1.1.4, 1.5.3 are valid, but 2.0.0 or 1.1.2 is not.

I'm not sure. I'd like to see some discussion of this.

My thought is that, since we're talking about a specification version and not an
implementation version, it's best to be precise. Ideally, 1.1.3, 1.1.3, and
1.5.3 would all be backwards-compatible with 1.1.3, assuming that the versioning
guidelines are followed closely, but in practice, sometimes mistakes do happen
and non-backwards-compatible changes slip into a minor release. I want to assume
that if a gadget author asks for a very specific spec version, it's probably for
a good reason, and containers shouldn't second-guess it.

On the other hand, it may even be the case that a 1.1.3 implementation does
satisfy the 1.2 spec, or that a 1.1.2 implementation satisfies a 1.1.3 spec,
depending on the exact nature of the changes from one spec version to another,
and whether additions are mandatory or optional.

Note that, in cases where the same implementation *does* satisfy multiple spec
versions, containers are free to provide the same implementation for all of
those spec versions. In the Features section, it says, "Containers MAY use the
same implementation to satisfy several different versions of a Feature, if by
doing so they fully comply with the Feature's specification." Maybe it would be
good to generalize that and move it into this section?

All in all, I was aiming to provide the maximum flexibility for container
implementations, while ensuring predictability for gadget developers. IMO the
best way to do that is by being clear that containers MUST provide
implementations that fully satisfy the spec version requested by each gadget,
but MAY share one implementation for multiple spec versions, as long as it
complies with all of those spec versions.

http://codereview.appspot.com/152136/diff/1/2#newcode784
draft/OpenSocial-Gadget-XML.xml:784: to Developers when a conflict is
detected.</t>
On 2009/11/18 01:04:32, Jon Weygandt wrote:
> If I "Require opensocial version 2.0" and "Optional opensocial-data version
1.0"
> will the gadget deploy and render, with hasFeature returning false for
> opensocial-data?
> That's how I would read this, but it is not totally clear.

That was the intent, yes. I'll try to clarify this.

http://codereview.appspot.com/152136/diff/1/2#newcode842
draft/OpenSocial-Gadget-XML.xml:842: <c>views</c>
On 2009/11/17 18:16:29, Lane wrote:
> views is part of core as of 0.9.  I know you didn't introduce this issue, but
> can you fix it please.

Sure. I've also fixed up all of the xrefs to JS APIs in the Features section to
be erefs to the Core-Gadget.xml or Social-Gadget.xml documents (except
gadgets.pubsub, which isn't in any of the spec documents, so I removed the
link).

Someone will need to fix up the rest of the file at some point (I can do this in
a different patch).

[Tim Moore, 2009-11-23 22:00:22]

Changes from the first round of comments

[Jon Weygandt, 2009-11-24 19:03:09]

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode195
draft/OpenSocial-Gadget-XML.xml:195: MUST return true; otherwise it MUST return
false. Developers SHOULD use
On 2009/11/18 01:04:32, Jon Weygandt wrote:
> Is this small addition in conflict, or redundant with text around line 790?

Around 790 it states that it can only return true if the option was requested
AND the container supports the feature (which I think makes sense). 

This states that if the container supports the feature it can return true (does
not state the option needs to be requested)

http://codereview.appspot.com/152136/diff/1/2#newcode541
draft/OpenSocial-Gadget-XML.xml:541: containers MUST conform to the exact
version of the specification or
"specification version" vs "implementation version" - should be obvious once
pointed out, but is a very different concept. I would think that specifications
will hopefully undergo few changes, compared to an implementation, so exact
match should not be too difficult for the user. Objection withdrawn.

[Tim Moore, 2009-11-24 19:11:26]

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode195
draft/OpenSocial-Gadget-XML.xml:195: MUST return true; otherwise it MUST return
false. Developers SHOULD use
On 2009/11/24 19:03:09, Jon Weygandt wrote:
> On 2009/11/18 01:04:32, Jon Weygandt wrote:
> > Is this small addition in conflict, or redundant with text around line 790?
> 
> Around 790 it states that it can only return true if the option was requested
> AND the container supports the feature (which I think makes sense). 
> 
> This states that if the container supports the feature it can return true
(does
> not state the option needs to be requested)

But it's in the context of describing the behavior of the /ModulePrefs/Optional
element (i.e., the way the feature is requested).

I can add a sentence to try to be more explicit about what happens when there is
no /ModulePrefs/Optional element for a feature.

http://codereview.appspot.com/152136/diff/1/2#newcode541
draft/OpenSocial-Gadget-XML.xml:541: containers MUST conform to the exact
version of the specification or
On 2009/11/24 19:03:09, Jon Weygandt wrote:
> "specification version" vs "implementation version" - should be obvious once
> pointed out, but is a very different concept. I would think that
specifications
> will hopefully undergo few changes, compared to an implementation, so exact
> match should not be too difficult for the user. Objection withdrawn.

OK cool. Do you think I should add something to clarify this?

[Jon Weygandt, 2009-11-24 19:21:25]

http://codereview.appspot.com/152136/diff/1/2
File draft/OpenSocial-Gadget-XML.xml (right):

http://codereview.appspot.com/152136/diff/1/2#newcode541
draft/OpenSocial-Gadget-XML.xml:541: containers MUST conform to the exact
version of the specification or
Actually you state "specification" above pretty clearly. Although my mind was on
what happens in practice with implementation versions, often going through many
different release to fix bugs and such. 

I would expect specification versions to change more slowly, plus as you said,
if spec-1.5 is defined as backward compatible with spec-1.0, the implementation
delivering spec-1.5 can also deliver spec-1.0. 

On 2009/11/24 19:11:26, Tim Moore wrote:
> On 2009/11/24 19:03:09, Jon Weygandt wrote:
> > "specification version" vs "implementation version" - should be obvious once
> > pointed out, but is a very different concept. I would think that
> specifications
> > will hopefully undergo few changes, compared to an implementation, so exact
> > match should not be too difficult for the user. Objection withdrawn.
> 
> OK cool. Do you think I should add something to clarify this?

[Tim Moore, 2010-01-07 03:17:58]

Re-applied to Core-Gadget.xml

[goosemanjack, 2010-02-02 18:21:57]

On 2010/01/07 03:17:58, Tim Moore wrote:
> Re-applied to Core-Gadget.xml

+1