Hello David, On 19 May 2014, at 10:22 , David Bosschaert <[email protected]> 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 <[email protected]> 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 them. >> >> Greetings, Marcel >> >> On 19 May 2014, at 9:24 , Guillaume Nodet <[email protected]> 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 <[email protected]>: >>> >>>> 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" <[email protected]> >>>> 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 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 <[email protected]> >>>> 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 <[email protected]> >>>> wrote: >>>>>>>> >>>>>>>>> Hi, >>>>>>>>> >>>>>>>>> right now we have a policy for handling provisional OSGi API (API >>>> that is >>>>>>>>> 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 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 anyway. >>>>>>>>> >>>>>>>>> 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, it >>>> 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 etc. >>>>>>>>> But before doing so, I would like to get the general feeling about >>>> this. >>>>>>>>> >>>>>>>>> So, wdyt? >>>>>>>>> >>>>>>>>> Thanks >>>>>>>>> Carsten >>>>>>>>> -- >>>>>>>>> Carsten Ziegeler >>>>>>>>> [email protected] >>>>> >>>> >>>> >>
