Commit d4d9ea14 authored by Martyn Welch's avatar Martyn Welch

Move API review process from the Contribution Process

The contribution process on designs.apertis.org currently has a section on
API review. This process doesn't fit with the focus of that document
(namely upstream contributions), so move it to the API documentation.
Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>
parent 385eedc3
Pipeline #123554 passed with stage
in 32 seconds
......@@ -286,4 +286,56 @@ be different to solve one of our requirements (in which case we keep
it); or perhaps the difference doesn't really matter either way; or
perhaps the difference points to a design issue in our API, which would
mean we can improve it by correcting that design issue, and get a better
outcome.
\ No newline at end of file
outcome.
## API review process
Before a public API may be marked as stable and suitable for use by third-party
apps, it must be reviewed. The process for this is:
* Some or all of the APIs of a component are selected for review. For example,
it might be decided to review the C APIs for a component, but not the D-Bus
APIs which it uses internally to communicate with a background service.
* The component authors produce:
* A description of the goals of the component and the APIs under review.
These should be high-level descriptions, covering the use cases for that
component and its APIs, goals of the implementation, and specific
non-goals. Where possible, this should refer back to a design document.
These descriptions should *not* be simply a copy of the API documentation
describing *how* the goals are implemented.
* A list of required features and APIs which must pass review before the API
may be marked as stable.
* A list of other components which depend on the APIs under review, and a
description of how those other components should interact with the APIs
under review. This ensures the final APIs are still usable as intended from
other components, and is another way of describing the use cases of the
API.
* An explicit description of where privilege boundaries are required in the
system, and whether any of the APIs cross those boundaries (for example, if
they implement functionality which should not be callable without elevated
privileges).
* A description of how the API may need to be extended. For example, should
it be extensible by the component maintainers, by third-party apps, or not
at all?
* The reviewers examine the APIs and provided documentation, and make
recommendations for the component as a whole, its interactions with other
components, and specific recommendations for each API under review (for
example, ‘keep this API unchanged’, ‘remove this API’, ‘keep it with the
following changes’, etc.).
* The feedback is discussed, potentially iterated, and changes are made to the
public API accordingly.
* The changes are re-reviewed, and the process iterates until the reviewers are
happy.
* The APIs are marked as public and stable, and their API documentation is
updated.
The main goal of the review process is to ensure that the stable APIs, which
have to be supported for a long time in the future, are a good match for all
current and anticipated use cases, and follow good system architecture
practices. A large part of this effort is in ensuring that all use cases for
the APIs are known and documented. A *non-goal* of the review process is to
look at each API individually and mechanically run through some ‘API review
checklist’ — this can easily miss mismatches between the API and the
component’s use cases; architectural issues which are important to catch.
Components’ APIs should not be marked as stable until they have been reviewed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment