felix-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marcel Offermans <marcel.offerm...@luminis.nl>
Subject Re: Handling of provisional OSGi API?
Date Mon, 19 May 2014 08:54:57 GMT
Hello David,

On 19 May 2014, at 10:22 , David Bosschaert <david.bosschaert@gmail.com> wrote:

> On 5/16/14, 20:43 , David Jencks wrote:
>> for instance, debugging the conformance test suite will be more or less impossible,
> Yep, if you're writing an RI in Felix and this RI needs to run as part
> of the OSGi CT, it will only work if it uses the official OSGi API.
> As an example take an OSGi CT that looks for a whiteboard service that
> implements the org.osgi.service.http.runtime.HttpServiceRuntime
> interface.
> The CT will not find the implementation if it's renamed to
> org.apache.felix...something. So at least to test the RI as part of
> the CT you need the real API.

You do, but as far as I know you do not need a release (in the Apache sense of the word, meaning
source code) for that as the OSGi CT only requires you to submit a binary artifact. And that
can easily be produced without doing any kind of release (and should, because it’s not for
public consumption usually).

> BTW I think it would be good if this policy could also apply to new
> versions of an existing API. E.g. it should also be usable when we
> move the Core API from 1.7 to 1.8 for Core R6. Thought anyone?

This policy already applies to new versions of an existing API, right?

Greetings, Marcel

> Cheers,
> David
> On 19 May 2014 10:05, Marcel Offermans <marcel.offermans@luminis.nl> wrote:
>> I did not read David’s proposal that way. I think he is saying:
>> YES, you can code against an API that is under development, as long as you do not
do any releases (before the API is finalized).
>> So only if you want to do a release before the API is finalized do you need to package
it under the Felix namespace and deprecate it (with a provisional status).
>> The only downside I see is that, from the OSGi Alliance point of view, they are getting
less “real world” use of their reference implementations while they are being developed,
because this policy makes it impractical to use (in production) any API that is still under
development. On the other hand, it’s not too hard for someone to write a small component
that publishes such an API itself and “bridges” to the artifact that our project released.
I think that’s actually a reasonable compromise.
>> Personally, I could also live with a policy that only requires us to put the API
in the Felix namespace (and not mark it deprecated or anything). Once an artifact has been
released, it’s out there anyway. On the other hand, those extras are not in anybody’s
way and they do serve as a warning, so I’m not going to make an argument that we must remove
>> Greetings, Marcel
>> On 19 May 2014, at 9:24 , Guillaume Nodet <gnodet@apache.org> wrote:
>>> The change and your proposal.  It seems to restrictive to not allow coding
>>> against API that are being developped when not planning to release the
>>> project before the API is.
>>> 2014-05-17 9:37 GMT+02:00 David Jencks <david_jencks@yahoo.com>:
>>>> I propose we change the provisional api policy page
>>>> http://felix.apache.org/documentation/development/provisional-osgi-api-policy.htmlto
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
>>>> specification.
>>>> ## 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:
>>>>   :::xml
>>>>   <Export-Package>
>>>>     org.apache.felix.service.metatype; version="0.1";
>>>> mandatory="status"; status="provisional"
>>>>   </Export-Package>
>>>> 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.
>>>> Comments?
>>>> thanks
>>>> 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
>>>> 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
>>>> 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
>>>> 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 artifact.
>>>>>> 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
>>>> 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
>>>> like a good idea...that sort of makes it not a policy.
>>>>>>> However, all policies can be improved. You could argue that the
>>>> 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
>>>> 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
>>>> 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
>>>> released.
>>>>>>>> I don't have time or interest to investigate, but it might
>>>> 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>
>>>> wrote:
>>>>>>>>> Hi,
>>>>>>>>> right now we have a policy for handling provisional OSGi
>>>> that is
>>>>>>>>> currently drafted in the OSGi expert groups but not final
>>>> 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
>>>> packages from
>>>>>>>>> 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
>>>>>>>>> The reference implementation of the new Http Service
(RFC 189) will
>>>> be done
>>>>>>>>> as part of Apache Felix and we would like to start working
on this
>>>> in the
>>>>>>>>> open. Therefore we need to commit the current version
of the API
>>>> draft
>>>>>>>>> somewhere. I think if we do this in the whiteboard section,
>>>> should be
>>>>>>>>> clear enough that the API is provisional and we don't
need to rename
>>>> the
>>>>>>>>> packages. We can also add all kinds of disclaimers/readmes
>>>>>>>>> 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