svn commit: r1597827 - /felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext

[dj...@apache.org]

Author: djencks
Date: Tue May 27 17:07:23 2014
New Revision: 1597827

URL: http://svn.apache.org/r1597827
Log:
Change to Provisional API policy per vote concluded 27 May 2014

Modified:
    felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext

Modified: felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext?rev=1597827&r1=1597826&r2=1597827&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext (original)
+++ felix/site/trunk/content/documentation/development/provisional-osgi-api-policy.mdtext Tue May 27 17:07:23 2014
@@ -1,26 +1,23 @@
 Title: Provisional OSGi API Policy
 
-## Overview
+##Overview
+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.
 
-The OSGi Alliance exposes provisional API through draft specification releases. Additionally, some Felix contributors work for OSGi Alliance member companies and have access to provisional OSGi API. Often, Felix subprojects want to experiment with and/or implement provisional OSGi API. In some cases, Felix subprojects may actually be the reference implementation for the specification in question. This creates potentially confusing or questionable situations.
+## 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.
 
-For example, if a Felix subproject is released with provisional OSGi API, downstream users may not be aware that the contained API is not final OSGi API. They may mistakenly confer "official" status on it, since it is contained in an "official" Apache release. Further, the ability to implement OSGi specifications is based on creating compliant implementations. Since it is not really possible to be compliant with a provisional specification, the status of such implementations is sort of a gray area.
+1. Although it is STRONGLY NOT RECOMMENDED, modified versions of provisional api may be released with these modifications:
 
-To deal with these situations, this document describes the policy for handling provisional OSGi API in Felix subprojects.
+ 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"`.
 
-## Policy summary
+## Discussion
 
-To make the policy as simple and consistent as possible, Felix subprojects must not contain nor depend on provisional OSGi API. Provisional OSGi API refers to anything in the `org.osgi.*` package namespace that is not part of a final released specification.
+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.
 
-## Policy in practice
-
-Since subprojects will still want to implement and experiment with provisional OSGi specifications, this must still be possible. The following steps should be taken when working on or with provisional OSGi specifications:
-
-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"`.
-
-For example to provisionally export the `org.apache.felix.service.metatype` package, the
+As an example, to provisionally export the `org.apache.felix.service.metatype` package, the
 `Export-Package` statement would look something like this:
 
     :::xml
@@ -28,8 +25,4 @@ For example to provisionally export the 
       org.apache.felix.service.metatype; version="0.1"; mandatory="status"; status="provisional"
     </Export-Package>
 
-When working with new specifications, this 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.
-
-## Policy rationale
-
-The first goal of this policy is to completely avoid using provisional OSGi API given the potential confusion and questions by doing so. The second goal is to make the existence of any Felix provisional API completely obvious to downstream users and make it difficult for them to use it unknowingly. This latter goal gives us the ability to still "release early and often", but without being required to maintain backward compatibility on provisional APIs.
+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.