[eclipse.org-architecture-council] [Bug 261874] New: provisional API con

[bugzilla-daemon@xxxxxxxxxxx]

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.