From 3a89bc774e6df574558de4cd6b80c920d961b07d Mon Sep 17 00:00:00 2001
From: josecoll <jose.coll@r3cev.com>
Date: Fri, 22 Feb 2019 10:14:59 +0000
Subject: [PATCH] CORDA-2656 Docs: building a CorDapp for both OS and
 Enterprise (#4797)

* CORDA-2656 Explanation and steps for building a CorDapp for both OS and Enterprise.

* Added details and links to Jar Signing and CorDapp dependencies management.
---
 docs/source/cordapp-build-systems.rst |  2 ++
 docs/source/cordapp-overview.rst      | 33 ++++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/source/cordapp-build-systems.rst b/docs/source/cordapp-build-systems.rst
index 5ddfe945d2..07da3debc7 100644
--- a/docs/source/cordapp-build-systems.rst
+++ b/docs/source/cordapp-build-systems.rst
@@ -38,6 +38,8 @@ the following folder and files from the `Kotlin CorDapp Template <https://github
 * ``gradlew``
 * ``gradlew.bat``
 
+.. _cordapp_dependencies_ref:
+
 Setting your dependencies
 -------------------------
 
diff --git a/docs/source/cordapp-overview.rst b/docs/source/cordapp-overview.rst
index 7c59ed6701..4829eebd57 100644
--- a/docs/source/cordapp-overview.rst
+++ b/docs/source/cordapp-overview.rst
@@ -45,4 +45,35 @@ the following components:
     * An ``ExitBondFlow``, allowing existing ``BondState`` states to be exited from the ledger
 
 After installing this CorDapp, the node owner will be able to use the flows defined by the CorDapp to agree ledger
-updates related to issuance, sale, purchase and exit of bonds.
\ No newline at end of file
+updates related to issuance, sale, purchase and exit of bonds.
+
+Writing and building apps that run on both Corda (open source) and Corda Enterprise
+-----------------------------------------------------------------------------------
+Corda and Corda Enterprise are compatible and interoperable, which means you can write a CorDapp that can run on both.
+To make this work in practice you should follow these steps:
+
+1. Ensure your CorDapp is designed per :doc:`Structuring a CorDapp <writing-a-cordapp>` and annotated according to :ref:`CorDapp separation <cordapp_separation_ref>`.
+   In particular, it is critical to separate the consensus-critical parts of your application (contracts, states and their dependencies) from
+   the rest of the business logic (flows, APIs, etc).
+   The former - the **CorDapp kernel** - is the Jar that will be attached to transactions creating/consuming your states and is the Jar
+   that any node on the network verifying the transaction must execute.
+
+.. note:: It is also important to understand how to manage any dependencies a CorDapp may have on 3rd party libraries and other CorDapps.
+   Please read :ref:`Setting your dependencies <cordapp_dependencies_ref>` to understand the options and recommendations with regards to correctly Jar'ing CorDapp dependencies.
+
+2. Compile this **CorDapp kernel** Jar once, and then depend on it from your workflows Jar (or Jars - see below). Importantly, if
+   you want your app to work on both Corda and Corda Enterprise, you must compile this Jar against Corda, not Corda Enterprise.
+   This is because, in future, we may add additional functionality to Corda Enterprise that is not in Corda and you may inadvertently create a
+   CorDapp kernel that does not work on Corda open source. Compiling against Corda open source as a matter of course prevents this risk, as well
+   as preventing the risk that you inadvertently create two different versions of the Jar, which will have different hashes and hence break compatibility
+   and interoperability.
+
+.. note:: As of Corda 4 it is recommended to use :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>` to leverage the new signature constraints functionality.
+
+3. Your workflow Jar(s) should depend on the **CorDapp kernel** (contract, states and dependencies). Importantly, you can create different workflow
+   Jars for Corda and Corda Enterprise, because the workflows Jar is not consensus critical. For example, you may wish to add additional features
+   to your CorDapp for when it is run on Corda Enterprise (perhaps it uses advanced features of one of the supported enterprise databases or includes
+   advanced database migration scripts, or some other Enterprise-only feature).
+
+In summary, structure your app as kernel (contracts, states, dependencies) and workflow (the rest) and be sure to compile the kernel
+against Corda open source. You can compile your workflow (Jars) against the distribution of Corda that they target.