|[eclipse.org-architecture-council] [Bug 261874] New: provisional API conventions|
https://bugs.eclipse.org/bugs/show_bug.cgi?id=261874 Product/Component: Community / Architecture Council Summary: provisional API conventions Product: Community Version: unspecified Platform: PC OS/Version: Windows Vista Status: NEW Severity: normal Priority: P3 Component: Architecture Council AssignedTo: eclipse.org-architecture-council@xxxxxxxxxxx ReportedBy: jeff@xxxxxxxxxxxxxxxxx CC: tjwatson@xxxxxxxxxx Throughout Eclipse there have been a number of cases of new function being put in place but no API being declared. This is quite understandable from a team perspective -- not enough experience has been had with the new function to commit long term to the shape of the current intended "API". This leads the what we have traditionally called "provisional API". Marking something as provisional API is useful in that it indicates to consumers that a) the standard binary compatibility API contract is not in force but b) if they are going to use this function, here is where the producers expect you to look. This is vital for gaining adoption of the new function and thus experience with the provisional API. To date the provisional API guidelines http://wiki.eclipse.org/Provisional_API_Guidelines have indicated that producers use "internal" and perhaps "internal.provisional" in the names of packages containing such API. Further, the guidelines state that the manifest "x-internal:=true" should be used. The PDE team has put in place a sophisticated set of API tooling http://wiki.eclipse.org/PDE/API_Tools to tell users when they are violating the API expectations of code they are consuming. This tooling is driven primarily by the manifest markup and by JavaDoc tags embedded in the code to refine the standard Java visibility declarations. Some observations: 1) It turns out that for historical and other reasons the provisional package naming conventions are applied inconsistently throughout the Eclipse projects. 2) The API tooling (and many producing teams) treat the x-internal flag as the ultimate definition of API. The historical naming convention of including "internal" in package names to indicate non-API is just that. A historical convention. The Eclipse in particular has long since dropped the idea that "internal" was the name 3) There have traditionally been two arguments for and against the provisional package naming conventions (respectively). a) There are no guarantees so forcing a name when the API "graduates" forces consumers to revisit their use of the function b) Optimistically using the expected name brings clarity to the provisional function's expected API both for the producer and early adopters. Proposal. We should accept that things have been inconsistent and provide flexible guidance going forward. Teams should be be free to make their package names as "unattractive" as they like. By the same token, with x-internal being the final arbiter of macro level API and the inclusion of API tooling, we should allow for provisional API to *not* have "internal" or "provisional" in their package names. By using version numbering correctly (e.g, moving from 1.0 to 2.0 when breaking compatibility) even when provisional API is concerned, consumers get the hard development and run time errors/warnings that they need to know that things have changed (i.e., case 3a). This also addresses viewpoint 3b) by using "the good name" communicate with consumers and clarify design. Martin O capture this quite well in bug 253777 comment 134. Concretely, the provisional API guidelines should be update to read as follows in the "After the API freeze" section: ====== Package naming Provisional API code may be in a package whose name contains the segment "internal" or "internal.provisional". Neither is required. Bundle manifest All provisional API packages must exported using the x-internal=true manifest markup. Package versions Provisional API packages must be exported with version and use the same package versioning rules as API packages. The package version must evolve independently from the Bundle-Version of the exporter. For example, the first release a provisional API some.cool.stuff might appear as follows: Bundle-Version: 3.0.0 Export-Package: some.cool.stuff; version=1.0; x-internal:=true Increasing the provisional package version should result in at least the service segment of the exporting bundle's version being incremented. Early Adopter Consumption Early adopters should use Import-Package to declare a dependency on provisional API. Proper version ranges should be used to ensure a compatible version of the provisional API is used. Import-Package: some.cool.stuff; version="[1.0, 2.0)" Graduating provisional API When a provisional API graduates, the x-internal flag is removed and the version number evolves as per the API package guidelines. Javadoc <copy down the section from the "Before the API freeze" section. The idea here is that people reviewing Javadoc etc should be aware that the code here is provisional.> ====== The updates to this guideline should be put in place by M6 (API freeze) to allow for teams to adapt. -- Configure bugmail: https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug.
Back to the top