language: docu: documentation for the migrate command of damlc #2579

ghost · 2019-08-16T16:08:12Z

This adds a chapter on how to migrate between two different versions of
two packages.

Pull Request Checklist

Read and understand the contribution guidelines
Include appropriate tests
Set a descriptive title and thorough description
Add a reference to the issue this PR will solve, if appropriate
Add a line to the release notes, if appropriate
Normal production system change, include purpose of change in description

NOTE: CI is not automatically run on non-members pull-requests for security
reasons. The reviewer will have to comment with /AzurePipelines run to
trigger the build.

hurryabit

Looks good to me. Thanks a lot.

I'd prefer if @bame-da and/or someone from the DAML Seals has a look as well before we merge this since I'm too deep in the details already.

hurryabit · 2019-08-19T10:56:53Z

docs/source/migrate/index.rst

+
+  Available options:
+    TARGET_PATH              Path where the new project should be located
+    SOURCE                   Path to the main source file ('source' entry of the


Why can't we determine this from the manifest in the DAR?

Should be possible, I'll try to change it.

hurryabit · 2019-08-19T10:58:05Z

docs/source/migrate/index.rst

+
+.. code-block:: shell
+
+  ./build.sh


Does daml migrate generate build.sh?

no :P. I just tried it out and got the .daml files, but no build scripts.

hurryabit · 2019-08-19T10:58:35Z

docs/source/migrate/index.rst

+
+  ./build.sh
+
+respectively ``.\build.cmd`` if your on a Windows system.  Note that you can **not** use the usual


Why does daml build not work? Can you please give a short explanation? Can we maybe actually make it work?

daml build will initialize the package db from the given .dar dependencies. However, we want to generate the interface files from the .dars and put those into the package db. This is done during the migrate command. If you call daml build you will overwrite them again.

Does that mean daml build will bork the migration project? If so, we should fix that.

hurryabit · 2019-08-19T10:59:51Z

docs/source/migrate/index.rst

+
+where the ``Foo.daml`` file contains
+
+.. code-block:: daml


We should put this in a separate file and use an include directive. I'm afraid the code will stop working at some point otherwise. Same below.

hurryabit · 2019-08-19T11:04:36Z

docs/source/migrate/index.rst

+            with
+                inC : ContractId A.Foo
+                sigs : [Party]
+            controller sigs


As soon as sigs contains more than one party calling this choice needs another template to collect the signatures. We should generate that one as well. We should also base as much of this as possible on generic templates in the near future.

Agreed on the generic templates. I think we need some input anyways on how these upgrade templates should look like and what authorization they should have.

yes, we should include a workflow to collect signatures, either via generic templates, or by generating an UpgradeAgreement template, which collects signatures and has non-consuming choices for op to create and trigger Upgrade on any of the generated templates.

hurryabit · 2019-08-19T11:09:05Z

docs/source/migrate/index.rst

+  conv : (Generic a repA, Generic b repB, Conv repA repB) => a -> b
+
+From its type signature you can see that it can convert any two data types that are instances of the
+``Generic`` class and whose generic representation can be converted itself.


We need an explanation aiming at our users intuition here.

hurryabit · 2019-08-19T11:09:42Z

docs/source/migrate/index.rst

+two packages. In our example, you'll find them in the files ``FooAInstances.daml`` and
+``FooBInstances.daml``.
+
+Generic representations can be converted when they are ``isomorphic``. That means the corresponding


Is there are function called isomorphic? If not, we should change the formatting from code-like to italic.

hurryabit · 2019-08-19T11:11:22Z

docs/source/migrate/index.rst

+
+The important hint is that the compiler is not able to deduce that our data type is an instance of
+the ``DA.Upgrade.Conv`` class and hence not convertible. In this case you will have to add your own
+upgrade/rollback templates to ``daml/Foo.daml``, that describe how to convert a contract of the


daml/Foo.daml` from which package?

of the migration project you're building. I'll add it.

hurryabit · 2019-08-19T11:12:57Z

docs/source/migrate/index.rst

+You find more information on how to deploy DAML archive packages :ref:`here <deploy-ref_index>` .
+After the ``foo-upgrade-2.0.0`` package has been deployed on the ledger, there exists for every
+contract defined in ``foo-1.0.0`` a DAML workflow with a choice to upgrade it to ``foo-2.0.0`` or
+roll it back. A future iteration might add DAML triggers to carry out the upgrade process


Let's please remove the last sentence. I can be misread as a promise.

bame-da

I think these docs are good. I could follow them very easily, except that there was no mention that TARGET_PATH has to be outside your project.

I also couldn't try it out as I got no build scripts.

bame-da · 2019-08-19T12:25:26Z

docs/source/migrate/index.rst

+
+.. code-block:: shell
+
+  ./build.sh


no :P. I just tried it out and got the .daml files, but no build scripts.

bame-da · 2019-08-19T12:25:59Z

docs/source/migrate/index.rst

+
+  ./build.sh
+
+respectively ``.\build.cmd`` if your on a Windows system.  Note that you can **not** use the usual


Does that mean daml build will bork the migration project? If so, we should fix that.

bame-da · 2019-08-19T12:28:33Z

docs/source/migrate/index.rst

+            with
+                inC : ContractId A.Foo
+                sigs : [Party]
+            controller sigs


yes, we should include a workflow to collect signatures, either via generic templates, or by generating an UpgradeAgreement template, which collects signatures and has non-consuming choices for op to create and trigger Upgrade on any of the generated templates.

bame-da · 2019-08-19T12:30:43Z

docs/source/migrate/index.rst

+  data Maybe a = Just a | Nothing
+
+When the package ``foo-2.0.0`` contains an extended data type of the ``Foo`` template that is not
+isomorphic, the build will fail. For example, let's assume the ``Foo`` module in the ``foo-2.0.0``


I think it would be much nicer if it went through with as much as possible, but left stubs for Conv instances that it can't automatically derive. So the user can open Main.daml and fill in those cv definitions.

it will add the templates, but it won't compile so you really just have to change the line containing the application of the conv function.

I added a sentence to the docs.

hurryabit · 2019-08-19T13:04:48Z

@bame-da said there are plenty of "unused import" warnings. We can suppress them with

daml/compiler/damlc/daml-preprocessor/src/DA/Daml/Preprocessor/Records.hs

Line 228 in 64e8f83

importGenerated qual i = i{ideclImplicit=True, ideclQualified=qual}

hurryabit

Let's merge this and keep improving in incremental steps.

This adds a section on how to migrate between two different versions of two packages.

ghost · 2019-08-19T13:53:21Z

@bame-da ah, to follow this one of the PR's still needs to go to master

ghost requested a review from bame-da as a code owner August 16, 2019 16:08

ghost force-pushed the upgrading_docu branch from a926876 to 234c995 Compare August 16, 2019 16:45

hurryabit reviewed Aug 19, 2019

View reviewed changes

bame-da reviewed Aug 19, 2019

View reviewed changes

hurryabit approved these changes Aug 19, 2019

View reviewed changes

Robin Krom added 2 commits August 19, 2019 15:11

language: docu: documentation for the migrate command of damlc

a59218f

This adds a section on how to migrate between two different versions of two packages.

addressing martin's comments

4c23848

ghost force-pushed the upgrading_docu branch from 234c995 to 4c23848 Compare August 19, 2019 13:44

addressing bernhard's comments

54b72ad

ghost merged commit 47238a5 into master Aug 19, 2019

ghost deleted the upgrading_docu branch August 19, 2019 14:58

This pull request was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

language: docu: documentation for the migrate command of damlc #2579

language: docu: documentation for the migrate command of damlc #2579

ghost commented Aug 16, 2019

hurryabit left a comment

hurryabit Aug 19, 2019

ghost Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019

bame-da Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019 •

edited by ghost

Loading

bame-da Aug 19, 2019

hurryabit Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019

bame-da Aug 19, 2019

hurryabit Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019

hurryabit Aug 19, 2019

ghost Aug 19, 2019

bame-da left a comment

bame-da Aug 19, 2019

bame-da Aug 19, 2019

bame-da Aug 19, 2019

bame-da Aug 19, 2019

ghost Aug 19, 2019 •

edited by ghost

Loading

ghost Aug 19, 2019

hurryabit commented Aug 19, 2019

hurryabit left a comment

ghost commented Aug 19, 2019


		./build.sh

		respectively ``.\build.cmd`` if your on a Windows system. Note that you can not use the usual

language: docu: documentation for the migrate command of damlc #2579

language: docu: documentation for the migrate command of damlc #2579

Conversation

ghost commented Aug 16, 2019

Pull Request Checklist

hurryabit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost Aug 19, 2019 • edited by ghost Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bame-da left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost Aug 19, 2019 • edited by ghost Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hurryabit commented Aug 19, 2019

hurryabit left a comment

Choose a reason for hiding this comment

ghost commented Aug 19, 2019

ghost Aug 19, 2019 •

edited by ghost

Loading

ghost Aug 19, 2019 •

edited by ghost

Loading