RELEASE - merge v3.1 release notes / upgrade notes / changelog to mas…

…ter (corda#2937)

* RELEASE - 3.1 upgrade and release notes

* Update docs for change to vno

* address vno change in release notes

* Update release-notes.rst

* make corda links

* Review comments

* Review comments

* review comments

* remove ref to reverted bugfix

* Review comments

docs/source/changelog.rst

@@ -5,7 +5,16 @@ Here's a summary of what's changed in each Corda release. For guidance on how to
 release, see :doc:`upgrade-notes`.
 
 Unreleased
-----------
+==========
+
+* java.security.cert.CRLReason added to the default Whitelist.
+
+* java.security.cert.X509CRL serialization support added.
+
+* Upgraded H2 to v1.4.197.
+
+* Shell (embedded available only in dev mode or via SSH) connects to the node via RPC instead of using the ``CordaRPCOps`` object directly.
+  To enable RPC connectivity ensure node’s ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
 
 * Errors thrown by a Corda node will now reported to a calling RPC client with attention to serialization and obfuscation of internal data.
 
@@ -19,16 +28,12 @@ Unreleased
   only once when it was created. Whilst registering serializers that already exist is essentially a no-op, it's a performance overhead for
   a very frequent operation that hits a synchronisation point (and is thus flagged as contended by our perfomance suite)
 
-* Update the fast-classpath-scanner dependent library version from 2.0.21 to 2.12.3
-
-  .. note:: Whilst this is not the latest version of this library, that being 2.18.1 at time of writing, versions later
-  than 2.12.3 (including 2.12.4) exhibit a different issue.
-
 * Node can be shut down abruptly by ``shutdown`` function in `CordaRPCOps` or gracefully (draining flows first) through ``gracefulShutdown`` command from shell.
 
 * Carpenter Exceptions will be caught internally by the Serializer and rethrown as a ``NotSerializableException``
 
-  * Specific details of the error encountered are logged to the node's log file. More information can be enabled by setting the debug level to ``trace`` ; this will cause the full stack trace of the error to be dumped into the log.
+  * Specific details of the error encountered are logged to the node's log file. More information can be enabled by setting the debug level to
+    ``trace`` ; this will cause the full stack trace of the error to be dumped into the log.
 
 * Parsing of ``NodeConfiguration`` will now fail if unknown configuration keys are found.
 
@@ -40,14 +45,27 @@ Unreleased
 
 * java.math.BigInteger serialization support added.
 
-* java.security.cert.CRLReason added to the default Whitelist.
+.. _changelog_v3.1:
 
-* java.security.cert.X509CRL serialization support added.
+Version 3.1
+-----------
 
-* Upgraded H2 to v1.4.197.
+* Update the fast-classpath-scanner dependent library version from 2.0.21 to 2.12.3
 
-* Shell (embedded available only in dev mode or via SSH) connects to the node via RPC instead of using the ``CordaRPCOps`` object directly.
-  To enable RPC connectivity ensure node’s ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
+  .. note:: Whilst this is not the latest version of this library, that being 2.18.1 at time of writing, versions later
+  than 2.12.3 (including 2.12.4) exhibit a different issue.
+
+* Updated the api scanner gradle plugin to work the same way as the version in master. These changes make the api scanner more
+  accurate and fix a couple of bugs, and change the format of the api-current.txt file slightly. Backporting these changes
+  to the v3 branch will make it easier for us to ensure that apis are stable for future versions. These changes are
+  released in gradle plugins version 3.0.10. For more information on the api scanner see
+  the `documentation <https://github.com/corda/corda-gradle-plugins/tree/master/api-scanner>`_.
+
+* Fixed security vulnerability when using the ``HashAttachmentConstraint``. Added strict check that the contract JARs
+  referenced in a transaction were deployed on the node.
+
+* Fixed node's behaviour on startup when there is no connectivity to network map. Node continues to work normally if it has
+  all the needed network data, waiting in the background for network map to become available.
 
 .. _changelog_v3:
 

docs/source/release-notes.rst

@@ -1,6 +1,61 @@
 Release notes
 =============
 
+.. _release_notes_v3_1:
+
+Release 3.1
+-----------
+
+This rapid follow-up to Corda 3.0 corrects an issue discovered by some users of Spring Boot and a number of other
+smaller issues discovered post release. All users are recommended to upgrade.
+
+Special Thanks
+~~~~~~~~~~~~~~
+
+Without passionate and engaged users Corda would be all the poorer. As such, we are extremely grateful to
+`Bret Lichtenwald <https://github.com/bret540>`_ for helping nail down a reproducible test case for the
+Spring Boot issue.
+
+Major Bug Fixes
+~~~~~~~~~~~~~~~
+
+* **Corda Serialization fails with "Unknown constant pool tag"**
+
+  This issue is most often seen when running a CorDapp with a Rest API using / provided by ``Spring Boot``.
+
+  The fundamental cause was ``Corda 3.0`` shipping with an out of date dependency for the
+  `fast-classpath-scanner <https://github.com/lukehutch/fast-classpath-scanner>`_ library, where the manifesting
+  bug was already fixed in a released version newer than our dependant one. In response, we've updated our dependent
+  version to one including that bug fix.
+
+* **Corda Versioning**
+
+  Those eagle eyed amongst you will have noticed for the 3.0 release we altered the versioning scheme from that used by previous Corda
+  releases (1.0.0, 2.0.0, etc) with the addition of an prepended product name, resulting in ``corda-3.0``. The reason for this was so
+  that developers could clearly distinguish between the base open source platform and any distributions based on on Corda that may
+  be shipped in the future (including from R3), However, we have heard the complaints and feel the pain that's caused by various
+  tools not coping well with this change. As such, from now on the versioning scheme will be inverted, with this release being ``3.1-corda``.
+
+  As to those curious as to why we dropped the patch number from the version string, the reason is very simple: there won't
+  be any patches applied to a release of Corda. Either a release will be a collection of bug fixes and non API breaking
+  changes, thus eliciting a minor version bump as with this release, or major functional changes or API additions and warrant
+  a major version bump. Thus, rather than leave a dangling ``.0`` patch version on every release we've just dropped it. In the
+  case where a major security flaw needed addressing, for example, then that would generate a release of a new minor version.
+
+Issues Fixed
+~~~~~~~~~~~~
+
+* RPC server leaks if a single client submits a lot of requests over time [`CORDA-1295 <https://r3-cev.atlassian.net/browse/CORDA-1295>`_]
+* Flaky startup, no db transaction in context, when using postgresql [`CORDA-1276 <https://r3-cev.atlassian.net/browse/CORDA-1276>`_]
+* Corda's JPA classes should not be final or have final methods [`CORDA-1267 <https://r3-cev.atlassian.net/browse/CORDA-1267>`_]
+* Backport api-scanner changes [`CORDA-1178 <https://r3-cev.atlassian.net/browse/CORDA-1178>`_]
+* Misleading error message shown when node is restarted after the flag day
+* Hash constraints not working from Corda 3.0 onwards
+* Serialisation Error between Corda 3 RC01 and Corda 3
+* Nodes don't start when network-map/doorman is down
+
+.. _release_notes_v3_0:
+
 Release 3.0
 -----------
 
@@ -294,6 +349,8 @@ Minor Changes
   * Numerous bug fixes and documentation tweaks.
   * Removed dependency on Jolokia WAR file.
 
+.. _release_notes_v2_0:
+
 Release 2.0
 -----------
 Following quickly on the heels of the release of Corda 1.0, Corda version 2.0 consolidates
@@ -313,6 +370,8 @@ Adds the facility for transparent forwarding of transactions to some third party
 that entity simply run an Observer node they can simply recieve a stream of digitally signed, de-duplicated reports that
 can be used for reporting.
 
+.. _release_notes_v1_0:
+
 Release 1.0
 -----------
 Corda 1.0 is finally here!

docs/source/upgrade-notes.rst

@@ -31,6 +31,85 @@ We also strongly recommend cross referencing with the :doc:`changelog` to confir
 UNRELEASED
 ----------
 
+<<< Fill this in >>>
+
+v3.0 to v3.1
+------------
+
+Gradle Plugin Version
+^^^^^^^^^^^^^^^^^^^^^
+
+Corda 3.1 uses version 3.1.0 of the gradle plugins and your ``build.gradle`` file should be updated to reflect this.
+
+.. sourcecode:: shell
+
+    ext.corda_gradle_plugins_version = '3.1.0'
+
+You will also need to update the ``corda_release_version`` identifier in your project gradle file.
+
+.. sourcecode:: shell
+
+  ext.corda_release_version = '3.1-corda'
+
+V2.0 to V3.0
+------------
+
+Gradle Plugin Version
+^^^^^^^^^^^^^^^^^^^^^
+
+Corda 3.0 uses version 3.0.9 of the gradle plugins and your ``build.gradle`` file should be updated to reflect this.
+
+.. sourcecode:: shell
+
+    ext.corda_gradle_plugins_version = '3.0.9'
+
+You will also need to update the ``corda_release_version`` identifier in your project gradle file.
+
+.. sourcecode:: shell
+
+  ext.corda_release_version = 'corda-3.0'
+
+Network Map Service
+^^^^^^^^^^^^^^^^^^^
+
+With the re-designed network map service the following changes need to be made:
+
+* The network map is no longer provided by a node and thus the ``networkMapService`` config is ignored. Instead the
+  network map is either provided by the compatibility zone (CZ) operator (who operates the doorman) and available
+  using the ``compatibilityZoneURL`` config, or is provided using signed node info files which are copied locally.
+  See :doc:`network-map` for more details, and :doc:`setting-up-a-corda-network.rst` on how to use the network
+  bootstrapper for deploying a local network.
+
+* Configuration for a notary has been simplified. ``extraAdvertisedServiceIds``, ``notaryNodeAddress``, ``notaryClusterAddresses``
+  and ``bftSMaRt`` configs have been replaced by a single ``notary`` config object. See :doc:`corda-configuration-file`
+  for more details.
+
+* The advertisement of the notary to the rest of the network, and its validation type, is no longer determined by the
+  ``extraAdvertisedServiceIds`` config. Instead it has been moved to the control of the network operator via
+  the introduction of network parameters. The network bootstrapper automatically includes the configured notaries
+  when generating the network parameters file for a local deployment.
+
+* Any nodes defined in a ``deployNodes`` gradle task performing the function of the network map can be removed, or the
+  ``NetworkMap`` parameter can be removed for any "controller" node which is both the network map and a notary.
+
+* For registering a node with the doorman the ``certificateSigningService`` config has been replaced by ``compatibilityZoneURL``.
+
+Corda Plugins
+^^^^^^^^^^^^^
+
+* Corda plugins have been modularised further so the following additional gradle entries are necessary:
+  For example:
+
+    .. sourcecode:: groovy
+        dependencies {
+            classpath "net.corda.plugins:cordapp:$corda_gradle_plugins_version"
+        }
+
+        apply plugin: 'net.corda.plugins.cordapp'
+
+The plugin needs to be applied in all gradle build files where there is a dependency on Corda using any of:
+cordaCompile, cordaRuntime, cordapp
+
 * For existing contract ORM schemas that extend from ``CommonSchemaV1.LinearState`` or ``CommonSchemaV1.FungibleState``,
   you will need to explicitly map the ``participants`` collection to a database table. Previously this mapping was done
   in the superclass, but that makes it impossible to properly configure the table name. The required changes are to:
@@ -405,4 +484,4 @@ Finance
 
   * Adjust imports of Cash flow references
   * Adjust the ``StartFlow`` permission in ``gradle.build`` files
-  * Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``)
+  * Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``)