felix-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david_jen...@yahoo.com>
Subject Re: Handling of provisional OSGi API?
Date Sat, 17 May 2014 07:37:00 GMT
I propose we change the provisional api policy page http://felix.apache.org/documentation/development/provisional-osgi-api-policy.html
to this (markdown source):

The OSGi Alliance exposes provisional API that may or may not become part of future OSGI specifications.
 This policy explains how and when Felix subprojects may relate to such API. Provisional OSGi
API refers to anything in the `org.osgi.*` package namespace that is not part of a final released

## Policy
1. No Felix release may contain or refer to provisional OSGI API.
1. Provisional API may be included and used in unreleased source code, however the API must
be part of a final released OSGI specification before this felix source may be released.

1. Although it is STRONGLY NOT RECOMMENDED, modified versions of provisional api may be released
with these modifications:

 1. Any provisional OSGi API must be recreated in the `org.apache.felix.*` package name space;
this effectively makes it provisional Felix API.
 1. All Felix provisional API must be marked as deprecated.
 1. All Felix provisional API exported from bundles should be exported with a mandatory attribute
of `status="provisional"`.

## Discussion

The first goal of this policy is to completely avoid using provisional OSGi API in released
Felix projects given the potential confusion and questions by doing so. The second goal is
to make the existence of any released Felix provisional API completely obvious to downstream
users and make it difficult for them to use it unknowingly. However, any such release is likely
to involve numerous problems such as incorrect semantic versioning or version mismatch between
the provisional and eventual osgi release and bundle version inflation if the felix provisional
api is removed after the OSGI API is released.

As an example, to provisionally export the `org.apache.felix.service.metatype` package, the
`Export-Package` statement would look something like this:

      org.apache.felix.service.metatype; version="0.1"; mandatory="status"; status="provisional"

When working with new OSGI specifications, constructing a Felix provisional API will likely
result in parallel package structures between the provisional OSGi and Felix APIs. When working
with existing specifications, it may be necessary to create extensions to existing OSGi interfaces
in the Felix package namespace.



david jencks

ps.  JB, Guillaume, what exactly are you +1ing?  That we keep talking? That the policy stay
the same? Change?

On May 16, 2014, at 7:56 PM, "Richard S. Hall" <heavy@ungoverned.org> wrote:

> On 5/16/14, 20:43 , David Jencks wrote:
>> You have a point about specs that don't get released.  And in such a circumstance
having something released with org.osgi packages marked provisional would be sort of a disaster.
>> But if a felix subproject is going to be an osgi ri, it really needs to be developed
with the right package names.  Otherwise, for instance, debugging the conformance test suite
will be more or less impossible, as well as making running the ri against the ct implausible.
> I believe we did have this issue with the Config Admin RI and somehow we managed.
>> So I think I'd like the policy to say (sub) projects are strongly discouraged from
releasing anything with a non released osgi spec api no matter what package it's moved to
and how provisional it's marked, but it's ok to have unreleased org.osgi packages in source
as long as either the spec gets released before any felix release is made or they are removed
before any felix release is made.
> I don't think we can leave policy as a recommendation, because then it still leaves it
up to whomever to decide.
> Again, I don't have an issue with saying it is okay in source form, but not in a released
>> My next DS commits add the DTO stuff, so unless the policy is changed they will have
to wait on github for a while.
> So, make a modified policy proposal and put it up for comments and ultimately a vote.
> -> richard
>> thanks
>> david jencks
>> On May 16, 2014, at 2:24 PM, Richard S. Hall <heavy@ungoverned.org> wrote:
>>> There was thought that went into that policy, it wasn't just pulled out of the
air...further, from experience of working on that specs that didn't make the cut (original
OBR and Gogo), I can say the policy does a good job of avoiding the confusion/complication
created in those cases.
>>> So, working around the policy based on personal whim, doesn't seem like a good
idea...that sort of makes it not a policy.
>>> However, all policies can be improved. You could argue that the policy should
simply be modified, as David suggests, to say only "released" subprojects must not contain
provisional API.
>>> I'd personally be fine with that, but such a subproject would still have to be
fine with not having an official release until the specs are final.
>>> -> richard
>>> On 5/16/14, 13:59 , David Jencks wrote:
>>>> Well, I pretty much disagree with the existing policy being good or nice,
but I think I agree with your proposal.
>>>> I think that there should be very different policy for the svn tree and for
releases.  I don't think it's a very good idea to have a release with a provisional osgi api,
whether or not it's had its packages shaded.  However if we decide we need to do this I think
_either_ renaming the packages _or_ marking the packages provisional should be sufficient,
not both.
>>>> For the svn tree, I think it's fine to just copy the osgi draft source into
some appropriate location and build it as part of the project.  The svn tree is not for general
consumption, if you use it you are supposed to know what you are doing and you certainly aren't
supposed to rely on it for production without doing your own deternimation that it is entirely
suitable, since it comes with no assurances of anything from apache.  We just shouldn't release
anything in this state: either the spec gets released first, or we mark the spec packages
provisional or rename them.
>>>> I have the same problem with  the felix ds/rfc 190 work, with the new runtime
and dto packages, and realistically for me the options are either changing the policy, or
keeping my work visible on github until the spec is released.
>>>> I don't have time or interest to investigate, but it might be possible to
use the maven shade plugin to rename the packages in byte code.  I imagine we'd have to run
bnd after this step.  I don't know if the shading can be done to integration tests as well
so the instructions to bnd don't have to be duplicated with and without the mangled package
names so we can create an unshaded bundle for unshaded integration tests.
>>>> thanks for reminding me to think about this before I committed :-)
>>>> david jencks
>>>> On May 15, 2014, at 11:14 PM, Carsten Ziegeler <cziegeler@apache.org>
>>>>> Hi,
>>>>> right now we have a policy for handling provisional OSGi API (API that
>>>>> currently drafted in the OSGi expert groups but not final or officially
>>>>> released yet):
>>>>> http://felix.apache.org/documentation/development/provisional-osgi-api-policy.html
>>>>> While the policy is good and nice, it requires to rename the packages
>>>>> an OSGi namespace to an Apache one for the reasons stated in the policy.
>>>>> However, this creates a burden for people using this stuff, e.g. when
>>>>> writing tests as these need to be refactored later on anyway.
>>>>> The reference implementation of the new Http Service (RFC 189) will be
>>>>> as part of Apache Felix and we would like to start working on this in
>>>>> open. Therefore we need to commit the current version of the API draft
>>>>> somewhere. I think if we do this in the whiteboard section, it should
>>>>> clear enough that the API is provisional and we don't need to rename
>>>>> packages. We can also add all kinds of disclaimers/readmes etc.
>>>>> But before doing so, I would like to get the general feeling about this.
>>>>> So, wdyt?
>>>>> Thanks
>>>>> Carsten
>>>>> -- 
>>>>> Carsten Ziegeler
>>>>> cziegeler@apache.org

View raw message