language: docu: documentation for the migrate command of damlc (digit…

…al-asset#2579) * language: docu: documentation for the migrate command of damlc This adds a section on how to migrate between two different versions of two packages. * addressing martin's comments * addressing bernhard's comments
axman6 · Aug 19, 2019 · 47238a5 · 47238a5
1 parent daf10bf
commit 47238a5
Show file tree

Hide file tree

Showing 18 changed files with 406 additions and 0 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -93,6 +93,7 @@ DAML SDK documentation
 
    experimental/warning
    daml-integration-kit/index
+   migrate/index
 
 .. toctree::
    :titlesonly:

diff --git a/docs/source/migrate/foo-1.0.0/daml.yaml b/docs/source/migrate/foo-1.0.0/daml.yaml
@@ -0,0 +1,12 @@
+sdk-version: 0.0.0
+name: foo
+source: daml/Foo.daml
+parties:
+  - Alice
+  - Bob
+version: 1.0.0
+exposed-modules:
+  - Foo
+dependencies:
+  - daml-prim
+  - daml-stdlib
diff --git a/docs/source/migrate/foo-1.0.0/daml/Foo.daml b/docs/source/migrate/foo-1.0.0/daml/Foo.daml
@@ -0,0 +1,14 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+--------------------------------------------------------------------------------
+
+daml 1.2
+module Foo where
+
+template Foo
+  with
+    a : Int
+    p : Party
+  where
+    signatory p
diff --git a/docs/source/migrate/foo-1.0.0/ui-backend.conf b/docs/source/migrate/foo-1.0.0/ui-backend.conf
@@ -0,0 +1,5 @@
+users
+  {
+    Alice { party = "Alice" },
+    Bob { party = "Bob" }
+  }
diff --git a/docs/source/migrate/foo-2.0.0/daml.yaml b/docs/source/migrate/foo-2.0.0/daml.yaml
@@ -0,0 +1,12 @@
+sdk-version: 0.0.0
+name: foo
+source: daml/Foo.daml
+parties:
+  - Alice
+  - Bob
+version: 2.0.0
+exposed-modules:
+  - Foo
+dependencies:
+  - daml-prim
+  - daml-stdlib
diff --git a/docs/source/migrate/foo-2.0.0/daml/Foo.daml b/docs/source/migrate/foo-2.0.0/daml/Foo.daml
@@ -0,0 +1,21 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+--------------------------------------------------------------------------------
+
+daml 1.2
+module Foo where
+
+template Foo
+  with
+    a : Int
+    p : Party
+  where
+    signatory p
+
+template Bar
+  with
+    t : Text
+    p : Party
+  where
+    signatory p
diff --git a/docs/source/migrate/foo-2.0.0/daml/FooEmbedding.daml b/docs/source/migrate/foo-2.0.0/daml/FooEmbedding.daml
@@ -0,0 +1,16 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+--------------------------------------------------------------------------------
+
+daml 1.2
+module Foo where
+
+template Foo
+  with
+    a : Int
+    b : Text
+    p : Party
+  where
+    signatory p
+
diff --git a/docs/source/migrate/foo-2.0.0/ui-backend.conf b/docs/source/migrate/foo-2.0.0/ui-backend.conf
@@ -0,0 +1,5 @@
+users
+  {
+    Alice { party = "Alice" },
+    Bob { party = "Bob" }
+  }
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/.gitignore b/docs/source/migrate/foo-upgrade-2.0.0/.gitignore
@@ -0,0 +1 @@
+/.daml
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/build.cmd b/docs/source/migrate/foo-upgrade-2.0.0/build.cmd
@@ -0,0 +1,4 @@
+:: Copyright (c) 2019 The DAML Authors. All rights reserved.
+:: SPDX-License-Identifier: Apache-2.0
+
+daml build --init-package-db=no --package @("foo-1.0.0",[("Foo","FooA")])@ --package @("foo-2.0.0",[("Foo","FooB")])@
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/build.sh b/docs/source/migrate/foo-upgrade-2.0.0/build.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Copyright (c) 2019 The DAML Authors. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+daml build --init-package-db=no --package '("foo-1.0.0",[("Foo","FooA")])' --package '("foo-2.0.0",[("Foo","FooB")])'
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml.yaml b/docs/source/migrate/foo-upgrade-2.0.0/daml.yaml
@@ -0,0 +1,13 @@
+sdk-version: 0.0.0
+name: foo-upgrade-2.0.0
+source: daml/Foo.daml
+parties:
+  - Alice
+  - Bob
+version: 0.0.1
+dependencies:
+  - daml-prim
+  - daml-stdlib
+  - /home/drsk/daml/docs/source/migrate/foo-1.0.0/.daml/dist/foo-1.0.0.dar
+  - /home/drsk/daml/docs/source/migrate/foo-2.0.0/.daml/dist/foo-2.0.0.dar
+
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
@@ -0,0 +1,40 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+daml 1.2
+module Foo where
+import FooA qualified as A
+import FooB qualified as B
+import FooAInstances()
+import FooBInstances()
+import DA.Next.Set
+import DA.Upgrade
+template FooUpgrade
+    with
+        op : Party
+    where
+        signatory op
+        nonconsuming choice Upgrade: ContractId B.Foo
+            with
+                inC : ContractId A.Foo
+                sigs : [Party]
+            controller sigs
+                do
+                    d <- fetch inC
+                    assert $ fromList sigs == fromList (signatory d)
+                    create $ conv d
+template FooRollback
+    with
+        op : Party
+    where
+        signatory op
+        nonconsuming choice Rollback: ContractId A.Foo
+            with
+                inC : ContractId B.Foo
+                sigs : [Party]
+            controller sigs
+                do
+                    d <- fetch inC
+                    assert $ fromList sigs == fromList (signatory d)
+                    create $ conv d
+
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooAInstances.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooAInstances.daml
@@ -0,0 +1,14 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+{-# LANGUAGE EmptyCase #-}
+{-# LANGUAGE NoDamlSyntax #-}
+module FooAInstances where
+import FooA
+import DA.Generics
+instance {-# NO_OVERLAP #-} Generic Foo (DA.Generics.D1 ('DA.Generics.MetaData ('DA.Generics.MetaData0 "Foo" "Foo" "foo-1.0.0" 'Prelude.False)) (DA.Generics.C1 ('DA.Generics.MetaCons ('DA.Generics.MetaCons0 "Foo" 'DA.Generics.PrefixI 'Prelude.True)) ((DA.Generics.:*:) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "a") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Int)) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "p") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Party))))) where
+  from x
+    = M1 (case x of { Foo g1 g2 -> M1 (P1 (M1 (K1 g1)) (M1 (K1 g2))) })
+  to (M1 x)
+    = case x of { (M1 (P1 (M1 (K1 g1)) (M1 (K1 g2)))) -> Foo g1 g2 }
+
diff --git a/docs/source/migrate/foo-upgrade-2.0.0/daml/FooBInstances.daml b/docs/source/migrate/foo-upgrade-2.0.0/daml/FooBInstances.daml
@@ -0,0 +1,19 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+{-# LANGUAGE EmptyCase #-}
+{-# LANGUAGE NoDamlSyntax #-}
+module FooBInstances where
+import FooB
+import DA.Generics
+instance {-# NO_OVERLAP #-} Generic Bar (DA.Generics.D1 ('DA.Generics.MetaData ('DA.Generics.MetaData0 "Bar" "Foo" "foo-2.0.0" 'Prelude.False)) (DA.Generics.C1 ('DA.Generics.MetaCons ('DA.Generics.MetaCons0 "Bar" 'DA.Generics.PrefixI 'Prelude.True)) ((DA.Generics.:*:) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "t") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Text)) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "p") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Party))))) where
+  from x
+    = M1 (case x of { Bar g1 g2 -> M1 (P1 (M1 (K1 g1)) (M1 (K1 g2))) })
+  to (M1 x)
+    = case x of { (M1 (P1 (M1 (K1 g1)) (M1 (K1 g2)))) -> Bar g1 g2 }
+instance {-# NO_OVERLAP #-} Generic Foo (DA.Generics.D1 ('DA.Generics.MetaData ('DA.Generics.MetaData0 "Foo" "Foo" "foo-2.0.0" 'Prelude.False)) (DA.Generics.C1 ('DA.Generics.MetaCons ('DA.Generics.MetaCons0 "Foo" 'DA.Generics.PrefixI 'Prelude.True)) ((DA.Generics.:*:) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "a") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Int)) (DA.Generics.S1 ('DA.Generics.MetaSel ('DA.Generics.MetaSel0 ('Prelude.Some "p") 'DA.Generics.NoSourceUnpackedness 'DA.Generics.NoSourceStrictness)) (DA.Generics.Rec0 Party))))) where
+  from x
+    = M1 (case x of { Foo g1 g2 -> M1 (P1 (M1 (K1 g1)) (M1 (K1 g2))) })
+  to (M1 x)
+    = case x of { (M1 (P1 (M1 (K1 g1)) (M1 (K1 g2)))) -> Foo g1 g2 }
+
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
@@ -0,0 +1,40 @@
+-- Copyright (c) 2019 The DAML Authors. All rights reserved.
+-- SPDX-License-Identifier: Apache-2.0
+
+daml 1.2
+module Foo where
+import FooA qualified as A
+import FooB qualified as B
+import FooAInstances()
+import FooBInstances()
+import DA.Next.Set
+import DA.Upgrade
+template FooUpgrade
+    with
+        op : Party
+    where
+        signatory op
+        nonconsuming choice Upgrade: ContractId B.Foo
+            with
+                inC : ContractId A.Foo
+                sigs : [Party]
+            controller sigs
+                do
+                    d <- fetch inC
+                    assert $ fromList sigs == fromList (signatory d)
+                    create $ Foo with a = d.a; b = "updated"; p = d.p
+template FooRollback
+    with
+        op : Party
+    where
+        signatory op
+        nonconsuming choice Rollback: ContractId A.Foo
+            with
+                inC : ContractId B.Foo
+                sigs : [Party]
+            controller sigs
+                do
+                    d <- fetch inC
+                    assert $ fromList sigs == fromList (signatory d)
+                    create $ Foo with a = d.a; p = d.p
+
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
@@ -0,0 +1,5 @@
+users
+  {
+    Alice { party = "Alice" },
+    Bob { party = "Bob" }
+  }