Public API Change Control Process
From Symbian Developer Community
This article specifies the management processes and practices for Symbian platform public API changes. These processes are established to ensure the public API set can evolve in a controlled manner.
A public API is defined as an API that is offered for application and feature development on top of the Symbian platform. This is the API category for package external APIs, that is, those intended for developers of loosely integrated software (for example, installable applications). A public API has strong backward compatibility guarantees – especially BC but also SC.
Platform APIs are interfaces used for internal development of the platform.
All public APIs are expected to comply with the Symbian Foundation's compatibility policy. This covers:
- Source compatibility
- Binary interface compatibility (ABI)
- Functional compatibility
Any change to the public API set must be submitted in a process called a Change Request (CR), which is outlined in this document. Such changes may include adding a new public API, extending an existing one without breaking compatibility, or making a change that causes a source compatibility break, or runtime break in the documented behavior of an API. The CR will be reviewed and approved by the Architecture Council.
Contents |
API Lifecycle
The main principles for public API development are as follows:
- Public APIs must remain backwards compatible during their lifetime.
- Public APIs can be extended with non-disruptive changes.
- Public APIs must go through a deprecation period before removal.
- The Symbian Foundation publishes the API and the compatibility baseline is established (it is set when the BC test suite for the API is frozen).
- The API is extended with new functionality (compatibility remains).
- The API is modified with a non-compatible change.
- The API is deprecated.
- The API is removed.
Each of the listed state changes during an API’s lifetime requires a CR to be submitted to the API change-control process and Architecture Council approval. Step 3 should be avoided because it fragments the platform and voids any investments that software developers have made by using the API for their development projects. If a developer needs to make a non-compatible change, Symbian Foundation recommends that they create a new API instead of modifying the old one, thus keeping the old interface intact.
Definitions
The table below lists the consequences of deprecation and removal of a public API.
| Context | Deprecation | Removal |
|---|---|---|
| Symbian platform | The API should not be used for any new development. Existing clients must migrate away from the deprecated API | The API is removed from the current platform release and the related SDK but remains in previous releases and SDKs. |
| Devices | API remains binary compatible | No binary compatibility guarantee |
As a guideline, public APIs can be removed and compatibility broken only when third-party software developers have been allowed enough time (deprecation) to modify their applications to use alternative APIs, and to provide new versions to end users. This must be considered when planning removal of an API. Third parties must be informed about the plan for removal during the deprecation period. The actual time period (deprecation) may vary a lot depending on the API and its popularity among third-party software.
Although unlikely, the foundation could decide to restore an API to a platform release after removal in an ealier release. This could happen if someone in the community picks up and starts maintaining and further developing code that was earlier considered obsolete. In such cases, the foundation will not assume backwards binary compatibility, but will establish a new compatibility baseline once the API has been republished in the platform release and SDK. Any such move would require a CR.
API Change-Control Process
Package owners own the public APIs exported by their packages and therefore only the owner can formally request changes to a package’s public API set. Contributors and other members of the Symbian Foundation community will have to channel their requests via the package owner.
The formal process to modify, add or remove a public API is called an API Change Request (CR).
There is no automated process for checking that package owners honour the Architecture Council’s decision, but it is up to the community to make sure that the rules are followed. The Architecture Council (together with other councils and Symbian Foundation staff) can discuss what actions to take, if the rules are not being followed.
Roles
Package owner:
- Provides what and why description of the change
- Performs analysis of impact to affected dependent software (API clients)
- Provides porting guide for the new API version
- Updates API BC test cases accordingly
- Provides/suggests fixes for API clients in the Symbian platform code base (optional)
- Co-ordinates fixes for API clients in the Symbian platform code base
- Submits API CR to Architecture Council
- Provides change implementation for MCL submission.
Architecture Council:
- Approves or rejects CR submissions (voting)
- Provides rationale for the CR decision.
Symbian Foundation:
- Provides tools support for CR processes
- Channels communication between foundation members and software developers.
CRs
During the change process, each API change request is presented with an API CR. A CR is the main tool to track and document the change process and corresponding API modifications.
| Transition | Actor | Description |
|---|---|---|
| (1) Draft/Submitted | Package owner | CR is delivered to Architecture council (AC) for approval |
| (2) Submitted/Approved | Architecture Council | CR is approved by AC, and is therefore ready for implementation |
| (3) Approved/Done | Package owner | CR has been implemented and changes committed to MCL |
| (4) Submitted/Rejected | Architecture Council | AC has rejected the CR |
| (5) Draft (Submitted/Withdrawn) | Package owner | CR is withdrawn and corresponding API change canceled |
CRs contain the following information:
- Unique and explicit CR ID
- Status
- Unique and explicit API ID/name
- Originating package/collection/component
- Links to other software architecture tools (for example, Agile Browser)
- Thorough description of the change, and reasoning behind it
- Affected header files, methods, classes, enumerations and other source symbols
- Migration and porting guides and instructions to affected API clients
- Implementation/releasing schedule, which must be synchronized between all the API clients that need modification due this change.
It is necessary to ensure MCL release stability and integrity even when releasing disruptive changes to APIs that have clients inside the platform itself. Thus CR implementation and releasing must be planned and synchronized together with the platform clients and their corresponding MCL deliveries in such way that build breaks are avoided. The modified API’s package owner is responsible for this.
Tooling Support
The API change-control process is supported by a Web-based CR system hosted by the Symbian Foundation. The system provides visibility of API change CRs to all foundation members. Package owners can create and submit CRs that the Architecture Council will either approve or reject. The decision is based on a voting system whereby each council member may register their vote together with their reasoning for their decision.
See also
Comments
Sign in to comment…
