Re: OpenSocial Gadget Specification & Feature Versioning patch [v1.0] (issue152136)

[tmo...@atlassian.com]

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

http://codereview.appspot.com/152136

[Mark W.]

Where I'm not sure is this statement...

"but MAY share one implementation for
multiple spec versions, as long as it complies with all of those spec
versions. "

How are is a container going to know that it complies with the spec
version? Are we opening the door for subjective interpretation of
compliance and the inability to deploy apps across containers?

-Mark W.

So... Is there precedent for this in other situations? For example,
did OSGI have to deal with this in the deployment / pre-req of
bundles?

[Mark W.]

Tim,
Quick question...
http://codereview.appspot.com/152136/diff/1/2#newcode195
<<
If a Container is unable to
102 support a specification version that matches the value of a
Gadget's
103 @specificationVersion attribute, the Container MUST display
an error
104 message to Users, and SHOULD provide the specification
versions that it
105 does support to Developers.</t>
>>

How do you anticipate the container to notify the developers? For
example, if I have a gadget that is on my host, "foo.com". You come
along in iGoogle and add that to your page. Suppose iGoogle does not
support version 1.2 of feature x. It makes sense that iGoogle displays
an error message indicating that it can't deploy that gadget. But how
is iGoogle going to let me, the developer of Foo.com know that Tim
tried to deploy my gadget in iGoogle and could not because it does not
support version 1.2 of feature x?

That said, I don't think this is necessarily a bad idea. I was
actually thinking that one of the life cycle events (or life cycle
call backs) would be more appropriate. Section 4.1.7 defines the
AddApp, RemoveApp. We could introduce a "FailureAdd" call back or
something similar.

-Mark W.

On Nov 23, 4:57 pm, tmo...@atlassian.com wrote:

[Jon]

I would guess it would be the same as for Gadgets, section 3.1.3
(5) :-)
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gadgets-API-Specification.html#process

On Nov 23, 7:41 pm, "Mark W." <weitz...@us.ibm.com> wrote:
> Tim,
> Quick question...http://codereview.appspot.com/152136/diff/1/2#newcode195

[tmo...@atlassian.com]

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?

http://codereview.appspot.com/152136

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

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.

[Tim Moore]

On Nov 23, 7:33 pm, "Mark W." <weitz...@us.ibm.com> wrote:
> Where I'm not sure is this statement...
> "but MAY share one implementation for
> multiple spec versions, as long as it complies with all of those spec
> versions. "
>
> How are is a container going to know that it complies with the spec
> version? Are we opening the door for subjective interpretation of
> compliance and the inability to deploy apps across containers?

I think that if the spec is clear about what defines a compliant
implementation, this shouldn't be an issue. Obviously compliance tests
would be a good idea as well.

> So... Is there precedent for this in other situations? For example,
> did OSGI have to deal with this in the deployment / pre-req of
> bundles?

Isn't any situation where an implementation of a specification is
backwards-compatible with previous specifications a precedent?

e.g., Apache serves HTTP 1.1 and 1.0 clients. Java servlet containers
typically support several servlet spec versions, etc.

OSGi has much more flexible version matching specifications, but I
thought that might be overkill.

-- Tim

[Tim Moore]

On Nov 23, 7:41 pm, "Mark W." <weitz...@us.ibm.com> wrote:
> Tim,
> Quick question...http://codereview.appspot.com/152136/diff/1/2#newcode195

> <<
> If a Container is unable to
>   102     support a specification version that matches the value of a
> Gadget's
>   103     @specificationVersion attribute, the Container MUST display
> an error
>   104     message to Users, and SHOULD provide the specification
> versions that it
>   105     does support to Developers.</t>
>
>
>
> How do you anticipate the container to notify the developers? For
> example, if I have a gadget that is on my host, "foo.com". You come
> along in iGoogle and add that to your page. Suppose iGoogle does not
> support version 1.2 of feature x. It makes sense that iGoogle displays
> an error message indicating that it can't deploy that gadget. But how
> is iGoogle going to let me, the developer of Foo.com know that Tim
> tried to deploy my gadget in iGoogle and could not because it does not
> support version 1.2 of feature x?

I think that's going to be implementation-dependent (which is why it
is a SHOULD instead of a MUST). I was emulating language in other
existing parts of the spec.

For example, in containers like MySpace where gadget developers have
to paste the gadget XML to register it with the container (or any
implementation that requires developers to register in a directory
before the gadget is available to users) it could show a detailed
error message at registration time.

In a more free-for-all container where users can add any gadget URL,
perhaps the container would always show a detailed error message with
supported spec versions in this case. If the container developers
think that could be off-putting for non-developer users, maybe it
would show a more generic error message with a "More Details" link. Or
maybe it would only show generic error messages when adding URLs ad-
hoc but display the developer message if added to the directory. Or it
could look for the author_email attribute in the gadget spec and offer
a mailto: link with details for users that try to add the gadget.

There are really a lot of options, which would all depend on the
implementation details of each container. I didn't want to mandate
anything in particular.

> That said, I don't think this is necessarily a bad idea. I was
> actually thinking that one of the life cycle events (or life cycle
> call backs) would be more appropriate. Section 4.1.7 defines the
> AddApp, RemoveApp. We could introduce a "FailureAdd" call back or
> something similar.

This is a good idea, but I think it should definitely be optional for
both the container and the app developer. I was intentionally trying
to keep this proposal as simple as possible for implementors.

-- Tim

[Tim Moore]

On Nov 24, 11:10 am, Jon <jon.weyga...@gmail.com> wrote:
> I would guess it would be the same as for Gadgets, section 3.1.3

> (5) :-)http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/Gad...

My aim was to be consistent with the first sentence of OpenSocial-
Gadget-XML.xml section 2.2 (Parsing) where it says: "XML documents
MUST be well-formed, and Containers MUST display an error to Users if
they are asked to process a malformed document. Containers SHOULD
provide meaningful error messages to Developers when the specification
is malformed."

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

I understand the idea to be that, in cases where an implementation
differentiates the user interface between developers and other users,
there should be some guidelines for what details to provide in the
developer UI.

-- Tim

[Mark W.]

Tim,
Thanks for clarifying. I think what's not clear here is who's doing
what when. That is, we are trying to cover multiple scenarios, e.g.
gadget registration, user adding this to a page, deployment of
gadgets, et... This makes it very difficult for us to write language
that covers all of these situations. I don't think for 1.0 we want to
get into these different scenarios because we are quiet on them
throughout the spec. For example, we don't really talk all that much
about gadget registration or adding a gadget to a container.

This got me thinking along several lines, one of which is when you
have automated registration, deployment, et. For example, suppose that
I have a workflow tool that automatically provisions code, gadgets,
et. In this case, we probably don't want to require a display of an
error. This could be true when you are working behind a fire wall and
assembling an entire app. This might get packaged up in an EAR and as
part of the nightly, automated deployment process, registration
happens. Even in something like the Eclipse e4 work, simply writing an
error to the OSGi console may be enough.

Maybe we should have something like, "...the container MUST report an
error, and SHOULD display the error if possible." This requires the
container to record the fact that it can't handle the gadget
deployment, but can do so via logs, management events, et.

In 1.1, we could introduce the notion of callbacks (a.k.a. lifecycle
events) that provide the ability for a container to notify its host
that someone attempted deployment and could not. I agree with you this
would be an optional capability.

-Mark W.

[Tim Moore]

Yeah, what it means to "display an error" isn't very well defined. In
your example, I would consider writing an error to the console to
loosely qualify. Do you think it would be better to remove all
requirements regarding error display from the specification? What do
others think? I'm pretty neutral on the matter, as long as it's
consistent throughout the spec.

I like the idea of a callback, and maybe even a general automated
registration mechanism. That could make a useful extension in the
future. In our own framework we've implemented a mechanism for one
application to auto-discover a feed of gadgets that another app makes
available. Wide support for that would be great. Anything that makes
it easier to configure gadgets in a container would be really useful
for us.

Cheers,
-- Tim

[Lane]

Hi Tim,

Can you apply this patch to the Core-Gadget.xml file? The older
content in OpenSocial-Gadget-XML has already been moved there, but the
versioning stuff hasn't made it over yet.

Thanks,
Lane

[Tim Moore]

I uploaded a new patch, which was basically just re-applying the diff
using patch and manually fixing anything that patch couldn't handle
because of re-arranged sections. I didn't look over the result in
detail yet. I can do that tomorrow, but in the meantime if anyone has
any feedback or can catch any errors, please go right ahead.

http://codereview.appspot.com/152136

Cheers,
Tim

[Lane LiaBraaten]

The new patch looks good to me.  Please go ahead and submit it.

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.

[Tim Moore]

Pardon the dumb question, but what exactly do you mean by submit?
AFAIK I don't have commit access to the svn repo. I also don't believe
the proposal has gotten enough votes yet. Should I start a new thread
for voting?

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

[Lane LiaBraaten]

Sorry for the confusion...at this point we should get all the proposals committed so we can start reviewing the draft as a whole.  If your proposal hasn't gotten the votes it needs, please use the <x:draft> tag and note that the proposal still needs to be voted on.

I've added your @atlassian.com account as a committer..let me know if you'd prefer to use another account.

Thanks,

Lane

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

[Lane LiaBraaten]

Hi Folks,

Since this proposal hasn't been voted on yet, I updated Tim's patch to surround the next sections with <x:draft> and checked it in.

-Lane

[Tim Moore]

Thanks, Lane. Sorry that I couldn't get to this myself over the last
few days... too many spinning plates at the moment.

On Jan 14, 8:17 am, Lane LiaBraaten <lliab...@google.com> wrote:
> Hi Folks,
>
> Since this proposal hasn't been voted on yet, I updated Tim's patch to
> surround the next sections with <x:draft> and checked it in.
>
> -Lane
>

> >> > > 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,...
>
> read more »