From 4adc0380a2f98d249dbec0cc1c41c4e1bbc099af Mon Sep 17 00:00:00 2001 From: Anthony Keenan Date: Thu, 24 May 2018 14:43:58 +0100 Subject: [PATCH] CORDA-1496 Add api-scanner documentation (#3184) Add api-scanner documentation --- docs/source/api-scanner.rst | 58 +++++++++++++++++++++++++++ docs/source/contributing.rst | 6 +++ docs/source/corda-api.rst | 2 + docs/source/release-process-index.rst | 3 +- 4 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/source/api-scanner.rst diff --git a/docs/source/api-scanner.rst b/docs/source/api-scanner.rst new file mode 100644 index 0000000000..45e0d096c1 --- /dev/null +++ b/docs/source/api-scanner.rst @@ -0,0 +1,58 @@ +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 `. 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 `. + +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-.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 `_. + + +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 `_, `Rick Parker `_ or `Matthew Nesbit `_. + +.. 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. \ No newline at end of file diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 3bfff458e4..0baf3c6efc 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -102,6 +102,12 @@ Building against the master branch You can test your changes against CorDapps defined in other repos by following the instructions :doc:`here `. +Running the API scanner +^^^^^^^^^^^^^^^^^^^^^^^ +Your changes must also not break compatibility with existing public API. We have an API scanning tool which runs as part of the build +process which can be used to flag up any accidental changes, which is detailed :doc:`here `. + + Updating the docs ----------------- diff --git a/docs/source/corda-api.rst b/docs/source/corda-api.rst index f0f803a227..bcb150c3c4 100644 --- a/docs/source/corda-api.rst +++ b/docs/source/corda-api.rst @@ -21,6 +21,8 @@ The following are the core APIs that are used in the development of CorDapps: Before reading this page, you should be familiar with the :doc:`key concepts of Corda `. +.. _internal-apis-and-stability-guarantees: + Internal APIs and stability guarantees -------------------------------------- diff --git a/docs/source/release-process-index.rst b/docs/source/release-process-index.rst index b269691a86..9ef0c82347 100644 --- a/docs/source/release-process-index.rst +++ b/docs/source/release-process-index.rst @@ -8,4 +8,5 @@ Release process changelog contributing codestyle - testing \ No newline at end of file + testing + api-scanner \ No newline at end of file