mirror of
https://github.com/corda/corda.git
synced 2024-12-20 05:28:21 +00:00
58 lines
3.3 KiB
ReStructuredText
58 lines
3.3 KiB
ReStructuredText
|
API stability check
|
||
|
|
===================
|
||
|
|
|
||
|
|
We have committed not to alter Corda's API so that developers will not have to keep rewriting their CorDapps with each
|
||
|
|
new Corda release. The stable Corda modules are listed :ref:`here <internal-apis-and-stability-guarantees>`. Our CI process runs an "API Stability"
|
||
|
|
check for each GitHub pull request in order to check that we don't accidentally introduce an API-breaking change.
|
||
|
|
|
||
|
|
Build Process
|
||
|
|
-------------
|
||
|
|
|
||
|
|
As part of the build process the following commands are run for each PR:
|
||
|
|
|
||
|
|
.. code-block:: shell
|
||
|
|
|
||
|
|
$ gradlew generateApi
|
||
|
|
$ .ci/check-api-changes.sh
|
||
|
|
|
||
|
|
This ``bash`` script has been tested on both MacOS and various Linux distributions, it can also be run on Windows with the
|
||
|
|
use of a suitable bash emulator such as git bash. The script's return value is the number of API-breaking changes that it
|
||
|
|
has detected, and this should be zero for the check to pass. The maximum return value is 255, although the script will still
|
||
|
|
correctly report higher numbers of breaking changes.
|
||
|
|
|
||
|
|
There are three kinds of breaking change:
|
||
|
|
|
||
|
|
* Removal or modification of existing API, i.e. an existing class, method or field has been either deleted or renamed, or
|
||
|
|
its signature somehow altered.
|
||
|
|
* Addition of a new method to an interface or abstract class. Types that have been annotated as ``@DoNotImplement`` are
|
||
|
|
excluded from this check. (This annotation is also inherited across subclasses and subinterfaces.)
|
||
|
|
* Exposure of an internal type via a public API. Internal types are considered to be anything in a ``*.internal.`` package
|
||
|
|
or anything in a module that isn't in the stable modules list :ref:`here <internal-apis-and-stability-guarantees>`.
|
||
|
|
|
||
|
|
Developers can execute these commands themselves before submitting their PR, to ensure that they haven't inadvertently
|
||
|
|
broken Corda's API.
|
||
|
|
|
||
|
|
|
||
|
|
How it works
|
||
|
|
------------
|
||
|
|
|
||
|
|
The ``generateApi`` Gradle task writes a summary of Corda's public API into the file ``build/api/api-corda-<version>.txt``.
|
||
|
|
The ``.ci/check-api-changes.sh`` script then compares this file with the contents of ``.ci/api-current.txt``, which is a
|
||
|
|
managed file within the Corda repository.
|
||
|
|
|
||
|
|
The Gradle task itself is implemented by the API Scanner plugin. More information on the API Scanner plugin is available `here <https://github.com/corda/corda-gradle-plugins/tree/master/api-scanner>`_.
|
||
|
|
|
||
|
|
|
||
|
|
Updating the API
|
||
|
|
----------------
|
||
|
|
|
||
|
|
As a rule, ``api-current.txt`` should only be updated by the release manager for each Corda release.
|
||
|
|
|
||
|
|
We do not expect modifications to ``api-current.txt`` as part of normal development. However, we may sometimes need to adjust
|
||
|
|
the public API in ways that would not break developers' CorDapps but which would be blocked by the API Stabilty check.
|
||
|
|
For example, migrating a method from an interface into a superinterface. Any changes to the API summary file should be
|
||
|
|
included in the PR, which would then need explicit approval from either `Mike Hearn <https://github.com/mikehearn>`_, `Rick Parker <https://github.com/rick-r3>`_ or `Matthew Nesbit <https://github.com/mnesbit>`_.
|
||
|
|
|
||
|
|
.. note:: If you need to modify ``api-current.txt``, do not re-generate the file on the master branch. This will include new API that
|
||
|
|
hasn't been released or committed to, and may be subject to change. Manually change the specific line or lines of the
|
||
|
|
existing committed API that has changed.
|