ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-02 19:26:47 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Docs: more work on the upgrade/release notes:

Browse Source 
* Address Shams' review comments
* Add some more discussion of app splitting, note the finance jar changes.
This commit is contained in:
Mike Hearn 2018-12-20 19:15:15 +01:00
parent 08564808c0
commit 8d15b8aea7
2 changed files with 28 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/source/app-upgrade-notes.rst
View File

@ -43,10 +43,14 @@ You should also ensure you're using Gradle 4.10 (but not 5). If you use the Grad
Otherwise just upgrade your installed copy in the usual manner for your operating system. Otherwise just upgrade your installed copy in the usual manner for your operating system.
Step 2. Add a "cordapp" section to your Gradle build file Step 2. Update your Gradle build file
--------------------------------------------------------- -------------------------------------
This is used by the Corda Gradle build plugin to populate your app JAR with useful information. It should look like this:: There are several adjustments that are beneficial to make to your Gradle build file, beyond simply incrementing the versions
as described in step 1.
**Provide app metadata.** This is used by the Corda Gradle build plugin to populate your app JAR with useful information.
It should look like this::
cordapp { cordapp {
targetPlatformVersion 4 targetPlatformVersion 4
@ -75,29 +79,39 @@ API semantics changes or disabling workarounds for bugs that may be in your apps
are promising that you have thoroughly tested your app on the new version. Using a high target version is are promising that you have thoroughly tested your app on the new version. Using a high target version is
a good idea because some features and improvements are only available to apps that opt in. a good idea because some features and improvements are only available to apps that opt in.
The minimum platform version is just the (major) version number of the node that you require, so if you The minimum platform version is the platform version of the node that you require, so if you
start using new APIs and features in Corda 4, you should set this to 4. Unfortunately Corda 3 and below start using new APIs and features in Corda 4, you should set this to 4. Unfortunately Corda 3 and below
do not know about this metadata and don't check it, so your app will still be loaded in such nodes and do not know about this metadata and don't check it, so your app will still be loaded in such nodes and
may exhibit undefined behaviour at runtime. However it's good to get in the habit of setting this may exhibit undefined behaviour at runtime. However it's good to get in the habit of setting this
properly for future releases. properly for future releases.
.. note:: Whilst it's currently a convention that Corda releases have the platform version number as their
major version i.e. Corda 3.3 implements platform version 3, this is not actually required and may in
future not hold true. You should know the platform version of the node releases you wan to target.
The new ``versionId`` number is a version code for **your** app, and is unrelated to Corda's own versions. The new ``versionId`` number is a version code for **your** app, and is unrelated to Corda's own versions.
It is used to block state downgrades: when a state constraint can be satisfied It is used to block state downgrades: when a state constraint can be satisfied
by multiple attachments, the version is tracked in the ledger and cannot decrement. This ensures security by multiple attachments, the version is tracked in the ledger and cannot decrement. This ensures security
fixes in CorDapps stick and can't be reversed by downgrading states to an earlier version. See fixes in CorDapps stick and can't be reversed by downgrading states to an earlier version. See
":ref:`contract_non-downgrade_rule_ref`" for more information. In future, the version attached to the ":ref:`contract_non-downgrade_rule_ref`" for more information.
workflow JAR will also be used to help implement smoother upgrade and migration features. You may directly
reference the gradle version number of your app when setting the cordapp specific versionId identifiers
if this follows the convention of always being a whole number starting from 1, you can just refer to that
variable directly to set the version id.
The duplication between ``contract`` and ``workflow`` blocks exists because you should split your app into **Split your app into contract and workflow JARs.** The duplication between ``contract`` and ``workflow`` blocks exists because you should split your app into
two separate JARs/modules, one that contains on-ledger validation code like states and contracts, and one two separate JARs/modules, one that contains on-ledger validation code like states and contracts, and one
for the rest (called by convention the "workflows" module although it can contain a lot more than just flows: for the rest (called by convention the "workflows" module although it can contain a lot more than just flows:
services would also go here, for instance). For simplicity, here we use one JAR for both, but this is in services would also go here, for instance). For simplicity, here we use one JAR for both, but this is in
general an anti-pattern and can result in your flow logic code being sent over the network to arbitrary general an anti-pattern and can result in your flow logic code being sent over the network to arbitrary
third party peers, even though they don't need it. third party peers, even though they don't need it.
In future, the version ID attached to the workflow JAR will also be used to help implement smoother upgrade
and migration features. You may directly reference the gradle version number of your app when setting the
cordapp specific versionId identifiers if this follows the convention of always being a whole number
starting from 1.
If you use the finance demo app, you should adjust your dependencies so you depend on the finance-contracts
and finance-workflows artifacts from your own contract and workflow JAR respectively. Although a single
finance jar still exists in Corda 4 for backwards compatibility, it should not be installed or used for
updated apps. This way, only the code that needs to be on the ledger actually will be.
Step 3. Security: Upgrade your use of FinalityFlow Step 3. Security: Upgrade your use of FinalityFlow
-------------------------------------------------- --------------------------------------------------
@ -269,7 +283,7 @@ automatically use them if your application JAR is signed. **We recommend all JAR
with developer certificates is deployed to a production node, the node will refuse to start. Therefore to deploy apps built for COrda 4 with developer certificates is deployed to a production node, the node will refuse to start. Therefore to deploy apps built for COrda 4
to production you will need to generate signing keys and integrate them with the build process. to production you will need to generate signing keys and integrate them with the build process.
Step 8. Security: package namespace handling Step 8. Security: Package namespace handling
-------------------------------------------- --------------------------------------------
Almost no apps will be affected by these changes, but they're important to know about. Almost no apps will be affected by these changes, but they're important to know about.
@ -279,8 +293,8 @@ There are two improvements to how Java package protection is handled in Corda 4:
1. Package sealing 1. Package sealing
2. Package namespace ownership 2. Package namespace ownership
**Sealing.** App isolation has been improved. Version 4 of the finance CorDapp (*corda-finance.jar*) is now built as a sealed and signed JAR file. **Sealing.** App isolation has been improved. Version 4 of the finance CorDapp (*corda-finance.jar*) is now built as a set of sealed and
This means classes in your own CorDapps cannot be placed under the following package namespace: ``net.corda.finance`` signed JAR files. This means classes in your own CorDapps cannot be placed under the following package namespace: ``net.corda.finance``
In the unlikely event that you were injecting code into ``net.corda.finance.*`` package namespaces from your own apps, you will need to move them In the unlikely event that you were injecting code into ``net.corda.finance.*`` package namespaces from your own apps, you will need to move them
into a new package, e.g. ``net/corda/finance/flows/MyClass.java`` can be moved to ``com/company/corda/finance/flows/MyClass.java``. into a new package, e.g. ``net/corda/finance/flows/MyClass.java`` can be moved to ``com/company/corda/finance/flows/MyClass.java``.

2
docs/source/release-notes.rst
View File

@ -37,7 +37,7 @@ A reference input state is a ``ContractState`` which can be referred to in a tra
of input and output states but, significantly, whose contract is not executed as part of the transaction of input and output states but, significantly, whose contract is not executed as part of the transaction
verification process and is not consumed when the transaction is committed to the ledger. Rather, it is checked verification process and is not consumed when the transaction is committed to the ledger. Rather, it is checked
for "current-ness". In other words, the contract logic isn't run for the referencing transaction only. for "current-ness". In other words, the contract logic isn't run for the referencing transaction only.
Since they're normal states, if they occur in the input or output positions, they can evolve on the ledger, Since they're normal states, if they do occur in the input or output positions, they can evolve on the ledger,
modeling reference data in the real world. modeling reference data in the real world.
Signature constraints Signature constraints