Re: Handling of provisional OSGi API

[Richard S. Hall]

 Draft policy here:

    
https://cwiki.apache.org/confluence/display/FELIX/Proviosional+OSGi+API+Policy

-> richard

On 9/23/10 11:42, Richard S. Hall wrote:
 On 9/23/10 11:40, Richard S. Hall wrote:
 On 9/23/10 11:36, Guillaume Nodet wrote:
Yeah, once there has been a draft published.  Before that, you had to
do what i described.

IC.

Well, it is somewhat difficult to compare with were talking about 
with their policy, since they use the OSGi package namespace and we 
aren't going to use it. I think our policy is better. ;-)

Ugh. That should say:

"...it is somewhat difficult to compare what we're talking about with 
their policy..."

-> richard


-> richard

On Thu, Sep 23, 2010 at 17:34, Richard S. 
Hall<he...@ungoverned.org>  wrote:
  On 9/23/10 11:27, Guillaume Nodet wrote:
I don't want to be the devil's advocate, but i think if the spec
aren't published, we can't even make then available to the public in
any form.
I know that because the equinox guys, when working on a prototype for
rfc 138 did not even include it it the svn tree.  So you had to grab
them from the osgi repository and add them yourself to the build 
tree.
   I know that's really annoying, but maybe we could discuss that 
with
the OSGi alliance.
This is not what I understand. They've made 138 available already, 
I believe
WebSphere depends on a prior prototype of 138. What both BJ and Tom 
told me
is that they mark everything as deprecated.

The main thing I think we should avoid is including provisional 
OSGi API in
our "official" releases, because this can clearly lead to confusion 
as to
whether or not the OSGi API is also official.

However, I'm fine with Felix' view that we should always use our own
namespace until the spec is final.

->  richard

On Thu, Sep 23, 2010 at 16:13, Felix Meschberger<fmesc...@gmail.com>
  wrote:
Hi,

Am 23.09.2010 16:05, schrieb Richard S. Hall:
  On 9/23/10 2:49, Felix Meschberger wrote:
Hi,

Maybe too late, but anyways.
No, it's not too late, since we still need to define our policy 
with
respect to provisional OSGi APIs...so we need everyone's opinion 
on this
to come to consensus.

Felix, this will likely impact you in odd ways if you continue to
provide the Config Admin RI. For example, if you implement the 
future
spec changes, if you plan to release it so people can play with 
it then
you'll need to put the changed API in org.apache.felix.cm 
namespace.
Hmm, yes.

Unless OSGi decides otherwise I am fine with continuing supplying 
the RI.

If you don't plan on releasing it until the spec is final, then I
suppose org.osgi namespace is fine, but we should still probably 
mark
them the same way.
Actually we should do this regardless of whether we release or 
not, but
maybe it would be good to release.

I guess this last point is also worthwhile to discuss. I think our
policy can differentiate between what we release and what we 
experiment
with, right? The policy for releases should be "no provisional OSGi
API", while for playing around in trunk or a sandbox is different,
right? Or no?
I think whatever we have in SVN is kind of publicly available and 
thus I
think we should do experiments in our own namespace even if we don't
release.

Regards
Felix

I am probably fine with #3.

I particularly like the key argument for using mandatory 
attributes:
"clearly state that you know what you are doing".
Ok, that's two for #3. :-)

->    richard

Regards
Felix

Am 22.09.2010 21:48, schrieb Richard S. Hall:
   On 9/22/10 14:44, Richard S. Hall wrote:
   Hopefully, I can get some quick feedback on this since I 
want to do
a
release...

Guillaume and I were discussing alternatives to a mandatory
attribute.
An alternative idea was mark all provisional API as 
deprecated, so
clients get warnings. What are people's thoughts on the two
approaches?

    1. The benefit of using mandatory attributes on 
provisional API is
       that you have to explicitly "opt in" to use it so no 
one can
ever
       claim they didn't know it was provisional.
    2. The benefit of using deprecated tags is that it works 
more
       smoothly with tooling and at still does give some sort of
warning
       notice, although less direct.

Personally, i still favor using mandatory attributes, because 
I think
it better captures our use case. But, I'd like to hear what 
other
people think.
Tom Watson (of Equinox fame) pointed out that using both is 
probably
the
best option because only using mandatory attributes doesn't 
address
Require-Bundle, which could use the packages freely without 
opting in.
Otherwise, he feels the same way I do, that mandatory 
attributes are a
good idea (just like for split packages), because you really 
need to
know what you are doing to use the packages...

Given the fact that I really need to get a release of Gogo 
trunk out
the
door, I'm just going to push forward for now with what we have in
trunk,
which is using mandatory attributes. We can continue to refine 
our
policy and when we are done, we can do another release to 
reflect it
even if it means doing another one next week.

So, to summarize, we now have three options:

    1. Just mandatory attributes.
    2. Just deprecated tags.
    3. Both.

After Tom's arguments, I'm probably now leaning toward #3.

->      richard

Quickly. :-)

->      richard


On 9/22/10 9:19, Richard S. Hall wrote:
   On 9/22/10 6:16, Guillaume Nodet wrote:
I'm also not convinced by the mandatory attribute.  I do 
understand
the value, but it may cause a lot of burden on our users 
for not
much.
If you have another recommendation for making it 100% clear 
to our
users that these packages will not be supported in the 
future, then
speak up. It's not that I want to use mandatory attributes, 
it's
that
I don't want to be taken to task in the future for throwing 
away the
API. In that regard, I think there is benefit to using it since
people have to go out of their way to use it.

Regarding the version number, I was using 0.6.1 because it 
is only a
maintenance release as compared to 0.6.0. The completely
incompatible
change was from 0.4.0 to 0.6.0, no? Or are you specifically
referring
to the mandatory attribute? If so, I don't have an issue 
with it
being 0.8.0 if you think the mandatory attribute warrants 
it, but I
don't really think that constitutes a breaking code
change...certainly a breaking metadata change.

->      richard

    Mandatory attributes are not very common and the 
tooling might
not be
prepared to handle those gracefully.  For example, I've 
just hit a
big
problem with karaf integration tests that use pax-exam, 
because the
mandatory attribute it not automatically added, so all test 
bundles
were failing during resolution ...
I've fixed that, but an average user will be in a real 
trouble if
hitting this.

On Wed, Sep 22, 2010 at 08:29, Guillaume 
Nodet<gno...@gmail.com>
wrote:
Do you plan to release gogo as 0.6.1 as indicated in JIRA ?
Given the change is fully incompatible, I'd at least bump the
minor
version ...

On Mon, Sep 20, 2010 at 17:50, Richard S.
Hall<he...@ungoverned.org>       wrote:
    On 9/20/10 11:21, Derek Baum wrote:
I also favor #1.

When we apply this to gogo, it will mean removing the draft
RFC-147 API
from
the org.osgi.service.command namespace and moving it to 
a felix
namespace.

We actually already did this for the gogo-0.6 release, 
but then
reverted
the
change in the trunk, as it broke many command providers who
imported
org.osgi.service.command. Back then we didn't have a 
policy for
supporting
draft OSGi APIs, but now it seems like we've agreed on 
#1. Do we
need a
vote?
It sounds like we have consensus, so we can probably just 
move
forward.

->       richard

Derek



On 19 September 2010 17:27, Richard S.
Hall<he...@ungoverned.org>         wrote:

    On 9/18/10 10:34, Felix Meschberger wrote:

Hi,

While I understand (and certainly don't underestimate the
consequences
of) the drawbacks of option (1) I still think it is 
the better
option.

At the time the OSGi releases the official API, we can 
still
keep our
internal API for certain period of time thus 
supporting both
API, if we
so wish.

     From my point of view we should just export the 
packages
with
mandatory
attributes and make it clear they will change when the 
API goes
final.
For
framework, I wouldn't plan to provide any ongoing 
support for
provisional
API. However, I don't think we need to mandate a global 
Felix
policy for
this and subprojects can choose to support two APIs if 
they
want.

->         richard



    Regards
Felix

Am 17.09.2010 18:35, schrieb Richard S. Hall:

    For a long time, we've played a little fast and 
loose
with our
handling
of provisional OSGi API. Starting with the OBR 1.6.0 
and Gogo
0.6.0
releases, we've started to evolve a policy on how to 
handle
this, but
nothing has been decided concretely. This is problematic
since
it leads
different people to different decisions. Thus, its about
time we
defined
our policy on this.

So, what's the issue?

Provisional OSGi API is not official. Further, 
provisional
package
content is evolving and these changes are not always 
made
readily
available by the OSGi Alliance. Even though some of 
us are
members of
the OSGi Alliance, we are not necessarily at liberty to
disclose
changes
to internal RFCs.

So, what can we do about it?

I see two potential [reasonable] policies from which 
we could
choose:

     1. Always use the org.apache.felix package 
namespace for
provisional
        OSGi API until the spec goes final.
     2. Use the org.osgi package namespace while the
provisional
API is in
        development, but only expose what has been 
publicly
made
available
        by the OSGi Alliance.

Both approaches have their drawbacks.

The benefit of (1) is that the legal/IP/etiquette issues
and/or
concerns
are reduced to those associated with normal open source
development.
For
completely new development, like Gogo, this would all 
happen
in
non-OSGi
packages, while changes to existing packages would 
need to be
done in
subclasses in non-OSGi packages. One downside of (1) 
is that
it will
always result in a package name change at the end 
that will
break
existing clients. For this reason, such experimental 
packages
should be
exported with mandatory attributes to warn potential 
clients.

The benefit of (2) is that the package namespace is more
consistent.
The
downside of (2) is that it is a IP/legal/etiquette 
gray area
as to
whether or not we can do official releases of 
subprojects
containing
provisional OSGi API. Even if we do not modify the 
API, it
still is
potentially confusing to our users who are getting an
"official"
release
from us of a subproject containing these "unofficial" 
bytes.
At a
minimum we would also need to use deprecated tags and/or
mandatory
attributes to warn people. Even then, it still raises 
issues
since we
aren't at liberty to evolve the packages freely to 
include
OSGi
internal, non-public RFC updates, nor extensions for
potential
feedback
into the RFC. In those cases, we would still need to 
resort
to
putting
stuff in org.apache.felix packages and renaming later 
once
the
changes
become public, which would also be problematic for 
clients.
Also, you
have to consider the case where the RFC is abandoned, in
which
case if
we still find it useful, we'll be forced to change our
package
names.

    From my point of view, approach (1) might not be 
awesome,
but it
results
in a simpler process than (2). So, I'd recommend (1). 
If the
majority
prefers (2), then we can do that (although I think 
we'll have
to run
the
decision by the board first).

Thoughts?

->          richard


--
Cheers,
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com