Return-Path: X-Original-To: apmail-felix-dev-archive@www.apache.org Delivered-To: apmail-felix-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D116E11342 for ; Mon, 19 May 2014 08:55:26 +0000 (UTC) Received: (qmail 83875 invoked by uid 500); 19 May 2014 08:55:26 -0000 Delivered-To: apmail-felix-dev-archive@felix.apache.org Received: (qmail 83799 invoked by uid 500); 19 May 2014 08:55:26 -0000 Mailing-List: contact dev-help@felix.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@felix.apache.org Delivered-To: mailing list dev@felix.apache.org Received: (qmail 83790 invoked by uid 99); 19 May 2014 08:55:26 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 May 2014 08:55:26 +0000 X-ASF-Spam-Status: No, hits=-0.0 required=5.0 tests=RCVD_IN_DNSWL_NONE,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (nike.apache.org: local policy includes SPF record at spf.trusted-forwarder.org) Received: from [194.109.24.30] (HELO smtp-vbr10.xs4all.nl) (194.109.24.30) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 19 May 2014 08:55:22 +0000 Received: from [10.0.0.33] (planetmarrs.xs4all.nl [82.95.193.148]) (authenticated bits=0) by smtp-vbr10.xs4all.nl (8.13.8/8.13.8) with ESMTP id s4J8svdt008239 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO) for ; Mon, 19 May 2014 10:54:59 +0200 (CEST) (envelope-from marcel.offermans@luminis.nl) Content-Type: text/plain; charset=windows-1252 Mime-Version: 1.0 (Mac OS X Mail 7.2 \(1874\)) Subject: Re: Handling of provisional OSGi API? From: Marcel Offermans In-Reply-To: Date: Mon, 19 May 2014 10:54:57 +0200 Content-Transfer-Encoding: quoted-printable Message-Id: References: <21176F9C-9657-4B1C-B17D-997A951E59FE@yahoo.com> <537681F8.3040504@ungoverned.org> <5376CFF6.8050805@ungoverned.org> <6DA9E6D0-7D80-4349-B3DC-3315F9592859@yahoo.com> <771A70F7-507F-4375-AD0B-F8D557E6DB99@luminis.nl> To: dev@felix.apache.org X-Mailer: Apple Mail (2.1874) X-Virus-Scanned: by XS4ALL Virus Scanner X-Virus-Checked: Checked by ClamAV on apache.org Hello David, On 19 May 2014, at 10:22 , David Bosschaert = wrote: > On 5/16/14, 20:43 , David Jencks wrote: >> for instance, debugging the conformance test suite will be more or = less impossible, >=20 > 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=92s = 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 >=20 > Cheers, >=20 > David >=20 > On 19 May 2014 10:05, Marcel Offermans = wrote: >> I did not read David=92s proposal that way. I think he is saying: >>=20 >> 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). >>=20 >> 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). >>=20 >> The only downside I see is that, from the OSGi Alliance point of = view, they are getting less =93real world=94 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=92s not too hard for someone to write = a small component that publishes such an API itself and =93bridges=94 to = the artifact that our project released. I think that=92s actually a = reasonable compromise. >>=20 >> 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=92s out there anyway. = On the other hand, those extras are not in anybody=92s way and they do = serve as a warning, so I=92m not going to make an argument that we must = remove them. >>=20 >> Greetings, Marcel >>=20 >> On 19 May 2014, at 9:24 , Guillaume Nodet wrote: >>=20 >>> 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. >>>=20 >>>=20 >>> 2014-05-17 9:37 GMT+02:00 David Jencks : >>>=20 >>>> I propose we change the provisional api policy page >>>> = http://felix.apache.org/documentation/development/provisional-osgi-api-pol= icy.htmlto this (markdown source): >>>>=20 >>>> 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. >>>>=20 >>>> ## 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. >>>>=20 >>>> 1. Although it is STRONGLY NOT RECOMMENDED, modified versions of >>>> provisional api may be released with these modifications: >>>>=20 >>>> 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=3D"provisional"`. >>>>=20 >>>> ## Discussion >>>>=20 >>>> 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. >>>>=20 >>>> As an example, to provisionally export the >>>> `org.apache.felix.service.metatype` package, the >>>> `Export-Package` statement would look something like this: >>>>=20 >>>> :::xml >>>> >>>> org.apache.felix.service.metatype; version=3D"0.1"; >>>> mandatory=3D"status"; status=3D"provisional" >>>> >>>>=20 >>>> 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. >>>>=20 >>>> Comments? >>>>=20 >>>> thanks >>>>=20 >>>> david jencks >>>>=20 >>>> ps. JB, Guillaume, what exactly are you +1ing? That we keep = talking? >>>> That the policy stay the same? Change? >>>>=20 >>>> On May 16, 2014, at 7:56 PM, "Richard S. Hall" = >>>> wrote: >>>>=20 >>>>> 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. >>>>>>=20 >>>>>> 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. >>>>>=20 >>>>> I believe we did have this issue with the Config Admin RI and = somehow we >>>> managed. >>>>>=20 >>>>>>=20 >>>>>> 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. >>>>>=20 >>>>> I don't think we can leave policy as a recommendation, because = then it >>>> still leaves it up to whomever to decide. >>>>>=20 >>>>> Again, I don't have an issue with saying it is okay in source = form, but >>>> not in a released artifact. >>>>>=20 >>>>>=20 >>>>>>=20 >>>>>> My next DS commits add the DTO stuff, so unless the policy is = changed >>>> they will have to wait on github for a while. >>>>>=20 >>>>> So, make a modified policy proposal and put it up for comments and >>>> ultimately a vote. >>>>>=20 >>>>> -> richard >>>>>=20 >>>>>>=20 >>>>>> thanks >>>>>> david jencks >>>>>>=20 >>>>>>=20 >>>>>>=20 >>>>>> On May 16, 2014, at 2:24 PM, Richard S. Hall = >>>> wrote: >>>>>>=20 >>>>>>> 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. >>>>>>>=20 >>>>>>> So, working around the policy based on personal whim, doesn't = seem >>>> like a good idea...that sort of makes it not a policy. >>>>>>>=20 >>>>>>> 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. >>>>>>>=20 >>>>>>> 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. >>>>>>>=20 >>>>>>> -> richard >>>>>>>=20 >>>>>>> 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. >>>>>>>>=20 >>>>>>>> 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. >>>>>>>>=20 >>>>>>>> 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. >>>>>>>>=20 >>>>>>>> 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. >>>>>>>>=20 >>>>>>>> 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. >>>>>>>>=20 >>>>>>>> thanks for reminding me to think about this before I committed = :-) >>>>>>>>=20 >>>>>>>> david jencks >>>>>>>>=20 >>>>>>>> On May 15, 2014, at 11:14 PM, Carsten Ziegeler = >>>> wrote: >>>>>>>>=20 >>>>>>>>> Hi, >>>>>>>>>=20 >>>>>>>>> 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): >>>>>>>>>=20 >>>> = http://felix.apache.org/documentation/development/provisional-osgi-api-pol= icy.html >>>>>>>>>=20 >>>>>>>>> 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. >>>>>>>>>=20 >>>>>>>>> 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. >>>>>>>>>=20 >>>>>>>>> So, wdyt? >>>>>>>>>=20 >>>>>>>>> Thanks >>>>>>>>> Carsten >>>>>>>>> -- >>>>>>>>> Carsten Ziegeler >>>>>>>>> cziegeler@apache.org >>>>>=20 >>>>=20 >>>>=20 >>=20