Difference between revisions of "PTP/policy/api"

Latest revision as of 20:37, 19 May 2010

This document provides the current API Policy for PTP (largely taken from CDT's API policy).

There are 3 types of API: Public API, Provisional API and Internal API (aka Private API, aka non API). Public API is what all clients should use, it should be documented using javadoc and should not change much from version to version. A public API breaking change requires that the major version number of the plugin be incremented. A public API extension (non-breaking changes) requires that the minor version number of the plugin be incremented. A provisional API is a candidate for a public API but does not have to follow versioning and other rules for public API, but other than that, it should be treated as public.

Examples API breaking change:

• Adding a method in interface
• Changing method signature
• Changing private visibility to any other

Examples of API extensions:

• Adding new extension point
• Changing visibility from protected to public
• Adding method in a class

Internal API

• Packages with name *.internal.*, *.examples.*
• Test projects, releng projects and feature projects
• Packages which are not exported or X-exported (i.e. not exported as public)
• Non-java code (i.e. native C code)
• Private and package private classes and members

Provisional API

Packages with names *.provisional* Classes that are marked EXPERIMENTAL as follows:

EXPERIMENTAL. This class or interface has been added as part
of a work in progress. There is no guarantee that this API will work or that
it will remain the same.

Public API

• Everything which is not internal or provisional and:
  • has public or protected java visibility
  • in public exported package
• Public API class or interface can also have some usage exceptions:
  • Classes and members marked @noreference in the javadoc comment cannot be used and not considered public API even if they have public visibility
  • Classes and interfaces that are marked as @noextend should not be extended
  • Interfaces that are marked @noimplement should not be implemented

See also Evolving Java-based APIs. .