Add a first version of new upgrade docs (digital-asset#4750)

This PR adds a first version of update documentation and removes the existing docs which were talking about `damlc migrate`. So far the docs focus on the high-level approach to upgrades taken in DAML and give an example of how to structure upgrade contracts. What is not covered so far (and I’d like to leave that for a separate PR) is: 1. Technical details: How are things split up into packages, which restrictions apply to data-dependencies, … 2. Deployment and Running the upgrade via triggers/daml script/… 3. Common patterns for handling this in UIs (e.g. “locking” old contracts) changelog_begin changelog_end
axman6 · Mar 2, 2020 · 1b5140e · 1b5140e
1 parent 7a9b9a3
commit 1b5140e
Show file tree

Hide file tree

Showing 21 changed files with 161 additions and 420 deletions.
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -567,6 +567,11 @@ daml_test(
     srcs = glob(["source/daml/intro/daml/**/*.daml"]),
 )
 
+daml_test(
+    name = "daml-upgrade-daml-test",
+    srcs = glob(["source/upgrade/**/*.daml"]),
+)
+
 filegroup(
     name = "daml-intro-1",
     srcs = glob(

diff --git a/docs/configs/pdf/index.rst b/docs/configs/pdf/index.rst
@@ -92,6 +92,7 @@ Experimental features
 
    experimental/warning
    daml-integration-kit/index
+   upgrade/index
    json-api/index
    triggers/index
    daml-script/index

diff --git a/docs/source/daml/intro/6_Parties.rst b/docs/source/daml/intro/6_Parties.rst
@@ -45,6 +45,9 @@ This may seem awkward, but notice that the ``ensure`` clause is gone from the ``
 
 You'll now learn a couple of common ways of building issuance and transfer workflows for the above ``Iou``, before diving into the authorization model in full.
 
+
+.. _intro propose accept:
+
 Use propose-accept workflows for one-off authorization
 ------------------------------------------------------
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -96,7 +96,7 @@ DAML SDK documentation
    experimental/warning
    daml-integration-kit/index
    tools/ledger-api-test-tool/index
-   migrate/index
+   upgrade/index
    json-api/index
    DAML Triggers <triggers/index>
    DAML Script <daml-script/index>

diff --git a/docs/source/migrate/foo-1.0.0/daml.yaml b/docs/source/migrate/foo-1.0.0/daml.yaml
diff --git a/docs/source/migrate/foo-1.0.0/daml/Foo.daml b/docs/source/migrate/foo-1.0.0/daml/Foo.daml
diff --git a/docs/source/migrate/foo-1.0.0/ui-backend.conf b/docs/source/migrate/foo-1.0.0/ui-backend.conf
diff --git a/docs/source/migrate/foo-2.0.0/daml.yaml b/docs/source/migrate/foo-2.0.0/daml.yaml
diff --git a/docs/source/migrate/foo-2.0.0/daml/Foo.daml b/docs/source/migrate/foo-2.0.0/daml/Foo.daml
diff --git a/docs/source/migrate/foo-2.0.0/ui-backend.conf b/docs/source/migrate/foo-2.0.0/ui-backend.conf
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/.gitignore b/docs/source/migrate/foo-upgrade-2.0.0/.gitignore
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml.yaml b/docs/source/migrate/foo-upgrade-2.0.0/daml.yaml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/Foo.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/Foo.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooAGenInstances.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooAGenInstances.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooBGenInstances.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooBGenInstances.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooManual.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooManual.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooWithGenerics.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooWithGenerics.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/ui-backend.conf b/docs/source/migrate/foo-upgrade-2.0.0/ui-backend.conf
-Original file line number
+Diff line change
@@ Expand Up @@
     You'll now learn a couple of common ways of building issuance and transfer workflows for the above ``Iou``, before diving into the authorization model in full.
+    .. _intro propose accept:
     Use propose-accept workflows for one-off authorization
     ------------------------------------------------------
@@ Expand Down @@