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

[tmo...@atlassian.com]

Reviewers: lliabraa,

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

Please review this at http://codereview.appspot.com/152136

Affected files:
draft/OpenSocial-Gadget-XML.xml

[Tim Moore]

Sorry that I just got this in at the last minute. I only added Lane as
a reviewer. I'm not sure if this tool lets other people sign
themselves up, but let me know if you'd like me to add you.

This is what I had been calling "Versioned Core Gadget Features", but
after the discussion on the list, it expanded in scope somewhat.
Hopefully not too much.

In addition to this, which is the main change, I'll need to go through
the other documents and tidy them up to be sure that all of the other
features (opensocial, opensocial-templates, etc.) specify versions
where necessary. I wanted to get this out first, though, to be sure
that everyone is happy with the overall direction.

Thanks,
Tim

[Lane LiaBraaten]

I've added this to the preview.  Affected sections are:

http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Gadget-XML.xml#Module

http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Gadget-XML.xml#Parsing

http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Gadget-XML.xml#RequireAndOptional

http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Gadget-XML.xml#Versioning

http://www.opensocial.org/Technical-Resources/draft/OpenSocial-Gadget-XML.xml#Features

This content will ultimately end up in Core-Gadget.xml, but I think it's okay to finalize the content in the OpenSocial-Gadget-XML.xml file and move it over later.

My comments coming soon...

-Lane

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=.

[api.ll...@gmail.com]

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

http://codereview.appspot.com/152136

[jon.we...@gmail.com]

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.

http://codereview.appspot.com/152136

[Mark W.]

Lane,

Would it be possible to add an example in the spec? Maybe we could
have one canonical example at the end that we could reference along
the way. It might sound trivial, but even in this section it would
help.

[Lane LiaBraaten]

An example of what?  Can you give me an example :P

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Jon]

Mark,

You responded to my review, not Lane's.

Is the agreement with the proposal and a desire for more information?

[Mark W.]

Lane,
It would be good to have an example of a gadget in this spec that we
could use as illustration. Here's a snip of what I put in the
extensions section to talk about how a gadget would need to put in to
consume an incubating feature. We could have one example at the end of
the doc, maybe in an appendix, that is a complete, well formed, gadget
definition, with all the new version tags et...

<Module>
<ModulePrefs title="Extensions Prototype">
<Require feature="opensocial-0.9"/>
<Require feature="opensocial-data" />
<Require feature="opensocial-templates"/>
<Require feature="osapi"/>
<Require feature="extensions-devworldprototype.incubating"/>
<Require feature="extensions-acmeprototype.incubating"/>

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>
> > .

[Lane LiaBraaten]

I would rather not have an example gadget as part of the spec...it's just one more thing to keep up to date.  I'd prefer small examples inline, close to where the behavior is defined.  Two reasons... First, it easier for the reader to see the example if it's right in front of them, rather than having to flip/browse to the appendix and back.  Second, if we change the behavior, the example is right there and harder to overlook.

-Lane

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=.

[Tim Moore]

On Nov 17, 5:04 pm, jon.weyga...@gmail.com wrote:
> 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).

I'd like to hear from others, but here's my reasoning for making the
default always be 1.0:

My intent was to gently push people towards specifying a version for
all of the features, while remaining backwards compatible with
existing gadgets. By requiring gadget authors to specify a version to
get any additions to features, it encourages explicit versioning.
While this adds a little verbosity to the spec files, I think it's
pretty minimal. I don't imagine that people will be changing their
gadgets to use new OpenSocial specs very often, so I don't think it
will be too onerous a task to update versions.

I also think that making the feature versions dependent on the spec
version complicates things quite a bit, both for the gadget developers
and container implementors. If the rules are too complex to remember
(i.e., they need to be looked up in each spec version) then I think
there is a far greater chance that bugs will slip in.

It gets even more complicated when considering extensions. Let's say I
write an extension called ExtOS that targets OpenSocial 1.0, and say
that the default version for OpenSocial 1.0 is ExtOS 1.0. Later, I
release ExtOS 1.1 and 1.2, but I can't retroactively change the
default version of my for OpenSocial 1.0, so it remains at ExtOS 1.0.
Then OpenSocial 1.1 comes along, and I'm too busy to update my feature
extension for it. In that case, the version of ExtOS that containers
should default to for OpenSocial 1.1 gadgets is unspecified. So what
should containers do? Refuse to render the gadget? Then OpenSocial 1.1
wouldn't be backwards compatible with existing gadgets that specify
specificationVersion="1" and require ExtOS but don't specify the
version. Should they assume that it remains at ExtOS 1.0? What if I
then come along and release an ExtOS 1.2.1 spec that clarifies that
OpenSocial 1.1 gadgets should default to ExtOS 1.2.1? Any existing
OpenSocial 1.1 containers that were defaulting to ExtOS 1.0 would
suddenly become non-compliant. It seems like having extension specs
document which version to serve with each OpenSocial spec version
would require extension authors to specify behavior for future,
unwritten OpenSocial spec versions.

So my preference is to keep this as simple as possible for container
implementors, at the expense of requiring a small amount of additional
effort on the part of gadget developers to specify the exact version
that they want, with the benefit that it's easier for everyone to
understand what will happen at render time.


What could make sense is to define umbrella features that incorporate
all of a set of finer-grained features. In that case, I could create a
gadget with <Require feature="opensocial-all" version="1.0"/> and get
all of the features defined by the OpenSocial specification. Then
that's just one thing to update when I want to go to version 1.1 or
2.0. I think that most implementations probably have some internal
mechanism to handle feature dependencies already, so this would
probably be a pretty easy thing to implement.

-- Tim

[Tim Moore]

Other follow-up comments to Lane & Jon ended up creating a new thread:

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/630a066eee2eb3d6

I also uploaded a new patch with changes based on their feedback:

http://codereview.appspot.com/152136

Thanks,
-- Tim

[goosemanjack]

+1 overall, and +1 at making the default be 1.0. Most, if not all of
the delta between 0.9 and 1.0 is clarification or additive in nature.
--
clc

[Lane LiaBraaten]

So far we have 3 +1's (Tim, Chris, Lane).  Please vote on this proposal so we can address any remaining concerns or yank out the <x:draft> tags.

Thanks,

Lane

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Lane LiaBraaten]

Ping!

[Tim Moore]

Sorry that I've been out of touch for a while. I've relocated to
Australia, and now I'm reachable again.

I just wanted to bump this thread. The proposal is short a few votes,
but I believe all of the feedback has been addressed. If there are
still any concerns, please let me know. If the whole proposal seems
undesirable, I'd like to hear your thoughts.

In particular: Jon, Mark, you've given good feedback in the past. Are
you happy with where this is now?

Thanks,
Tim

On Feb 2, 2:42 am, Lane LiaBraaten <lliab...@google.com> wrote:
> Ping!
>

> >> opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>

[Evan Gilbert]

+1

[Arne Roomann-Kurrik]

+1 - note that I've adjusted the mime type of these files so that
they're viewable directly from SVN:
http://opensocial-resources.googlecode.com/svn/spec/draft/Core-Gadget.xml

~Arne

On Feb 9, 12:08 am, Evan Gilbert <uid...@google.com> wrote:
> +1
>

> >> opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>

> >> .
> >> For more options, visit this group at
> >>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> >  --
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To post to this group, send email to
> > opensocial-an...@googlegroups.com.
> > To unsubscribe from this group, send email to

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>

[Lane LiaBraaten]

On Tue, Feb 9, 2010 at 12:13 PM, Arne Roomann-Kurrik <kur...@google.com> wrote:

+1 - note that I've adjusted the mime type of these files so that
they're viewable directly from SVN:
http://opensocial-resources.googlecode.com/svn/spec/draft/Core-Gadget.xml

That's great...no more uploading to opensocial.org.  I'll just update the link to point straight to svn.

-Lane

 

To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Tim Moore]

Looks like the vote passed. Would you like me to remove the <x:draft>
tags?

On Feb 10, 7:52 am, Lane LiaBraaten <lliab...@google.com> wrote:
> On Tue, Feb 9, 2010 at 12:13 PM, Arne Roomann-Kurrik <kur...@google.com>wrote:
>
> > +1 - note that I've adjusted the mime type of these files so that
> > they're viewable directly from SVN:

> >http://opensocial-resources.googlecode.com/svn/spec/draft/Core-Gadget...

> > > >> opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com><opensocial-and-gad
> > gets-spec%2Bunsu...@googlegroups.com<gets-spec%252Bunsubscribe@googlegr oups.com>

>
> > > >> .
> > > >> For more options, visit this group at
> > > >>http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
> > > >  --
> > > > You received this message because you are subscribed to the Google
> > Groups
> > > > "OpenSocial and Gadgets Specification Discussion" group.
> > > > To post to this group, send email to
> > > > opensocial-an...@googlegroups.com.
> > > > To unsubscribe from this group, send email to

> > > > opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com><opensocial-and-gad
> > gets-spec%2Bunsu...@googlegroups.com<gets-spec%252Bunsubscribe@googlegr oups.com>