Tidying up migration guide

digital-asset · May 6, 2019 · dbea50f · dbea50f
1 parent ee623a8
commit dbea50f
Showing 1 changed file with 68 additions and 64 deletions.
diff --git a/docs/source/support/new-assistant.rst b/docs/source/support/new-assistant.rst
@@ -4,87 +4,91 @@
 Moving to the new DAML assistant
 ################################
 
-New command-line tool for working with the DAML SDK: DAML Assistant, or ``daml``. Many commands are similar to using the old SDK Assistant (``da``), but with some changes:
+We've released a new command-line tool for working with the DAML SDK: DAML Assistant, or ``daml``. Many of its commands are similar to the old SDK Assistant (``da``), but there are some changes:
 
-- Simplified installation process: ``curl -sSL https://get.daml.com/ | sh`` for Linux and Mac.
+- Simplified installation process: ``curl -sSL https://get.daml.com/ | sh`` for Linux and Mac
 - Overhaul and simplification of templates:
 
   - ``daml new`` takes arguments in a consistent order:
 
-    - ``daml new proj`` creates a new project named ``proj`` with a skeleton template.
-    - ``daml new proj quickstart-java`` creates a new project with the quickstart-java template.
+    - ``daml new proj`` creates a new project named ``proj`` with a skeleton template
+    - ``daml new proj quickstart-java`` creates a new project with the quickstart-java template
 
-  - ``daml new`` templates are built-in to the SDK.
+  - ``daml new`` templates are built-in to the SDK
   - Mix-in template mechanism is gone (``da add``)
-  - No more publishing or subscribing of templates on Bintray, use Github and ``git clone`` to distribute templates outside of the SDK.
+  - No more publishing or subscribing of templates on Bintray: use Github and ``git clone`` to distribute templates outside of the SDK
 
-- Use ``daml build`` to compile your project into a DAR.
-- ``daml start`` components don't run in the background, you stop them with ``ctrl+c``
+- Use ``daml build`` to compile your project into a DAR
+- ``daml start`` components don't run in the background, and you stop them with ``ctrl+c``
 
-  - There is no ``da stop`` and ``da restart`` command.
+  As a result, there are no equivalents to ``da stop`` and ``da restart``
 
 - No ``da run`` equivalent, but:
 
   - ``daml sandbox`` is the same as ``da run sandbox --``
   - ``daml navigator`` is the same as ``da run navigator --``
   - ``daml damlc`` is the same as ``da run damlc --``
-
-
-Migrating a da project to daml
-==============================
-
-Before you begin migrating an existing project to ``daml``, make sure you upgrade your project to SDK version 0.12.15 or later.
-
-The biggest difference between a ``da`` project and a ``daml`` project is that the latter requires a ``daml.yaml`` file instead of a ``da.yaml`` file.
-
-.. The ``da migrate`` command, from the old assistant, will create a ``daml.yaml`` file based on the existing ``da.yaml``. This command is not complete at this time.
-
-So to migrate an existing project, you will need to create a ``daml.yaml`` file. The two files are very similar, with ``daml.yaml`` being the ``project`` section of ``da.yaml``, with some additional packaging information. Here is an example of a ``daml.yaml`` file, from the quickstart-java template:
-
-.. code-block:: yaml
-
-   sdk-version: 0.12.14
-   name: my_project
-   source: daml/Main.daml
-   scenario: Main:setup
-   parties:
-   - Alice
-   - Bob
-   - USD_Bank
-   - EUR_Bank
-   version: 1.0.0
-   exposed-modules:
-   - Main
-   dependencies:
-   - daml-prim
-   - daml-stdlib
-
-Here is the corresponding ``da.yaml`` file for comparison:
-
-.. code-block:: yaml
-
-   project:
-     sdk-version: 0.12.12
-     scenario: Main:setup
-     name: foobar
-     source: daml/Main.daml
-     parties:
-     - Alice
-     - Bob
-     - USD_Bank
-     - EUR_Bank
-   version: 2
+- ``daml.yaml`` configuration file replaces ``da.yaml`` - read more about this in the next section
+
+Migrating a ``da`` project to ``daml``
+======================================
+
+To migrate an existing project to use ``daml``:
+
+1. Upgrade your project to SDK version 0.12.15 or later.
+2. Convert your project's ``da.yaml`` file into a ``daml.yaml`` file. 
+
+   .. To do this, run ``da migrate`` on your existing ``da.yaml``. This command isn't done yet so commenting this out.
+
+   The two files are very similar: ``daml.yaml`` is the ``project`` section of ``da.yaml``, plus some additional packaging information. Here is an example of a ``daml.yaml`` file, from the quickstart-java template:
+
+   .. code-block:: yaml
+
+      sdk-version: 0.12.14
+      name: my_project
+      source: daml/Main.daml
+      scenario: Main:setup
+      parties:
+      - Alice
+      - Bob
+      - USD_Bank
+      - EUR_Bank
+      version: 1.0.0
+      exposed-modules:
+      - Main
+      dependencies:
+      - daml-prim
+      - daml-stdlib
+
+   Here is the corresponding ``da.yaml`` file:
+
+   .. code-block:: yaml
+
+      project:
+        sdk-version: 0.12.12
+        scenario: Main:setup
+        name: foobar
+      source: daml/Main.daml
+        parties:
+        - Alice
+        - Bob
+        - USD_Bank
+        - EUR_Bank
+      version: 2
 
 The extra fields in ``daml.yaml`` are related to the new packaging functionality in ``damlc``. When you build a DAML project with ``daml build`` (or ``daml start``) it creates a ``.dar`` package from your project inside the ``dist/`` folder. (You can supply a different target location by passing the ``-o`` option.) To create the package properly, the new config file ``daml.yaml`` needs the following additional fields that were not present in ``da.yaml``:
 
-- ``version``: This is the version number for the DAML project, which becomes the version number for the compiled package.
-- ``exposed-modules``: This is used when building the ``.dar`` file for the project. It determines what modules are exposed for users of the package.
-- ``dependencies``: These are the DAML packages that this project depends on. The two packages ``daml-prim`` and ``daml-stdlib`` give access to the basic definitions of DAML, and you should add them both as dependencies. At this time, additional dependencies can only be added by giving the path to the ``.dar`` file of the other package.
+- ``version``: The version number for the DAML project, which becomes the version number for the compiled package.
+- ``exposed-modules``: When the ``.dar`` file is built, this determines what modules are exposed for users of the package.
+- ``dependencies``: The DAML packages that this project depends on. ``daml-prim`` and ``daml-stdlib`` together give access to the basic definitions of DAML - **you should add them both as dependencies**. Additional dependencies can only be added by giving the path to the ``.dar`` file of the other package.
 
+You can now use ``daml`` commands with your project.
 
 Switching from old commands to new ones
 =======================================
 
+This section goes through the ``da`` commands, and gives the ``daml`` equivalent where there is one.
+
 Managing versions and config
 ****************************
 
@@ -139,16 +143,16 @@ Running components
      - ``daml studio``
    * - ``da navigator``
      - Launch Navigator
-     - ``daml navigator``
+     - No direct equivalent; ``daml navigator`` is equivalent to ``da run navigator``
    * - ``da sandbox``
      - Launch Sandbox
-     - ``daml sandbox``
+     - No direct equivalent; ``daml sandbox`` is equivalent to ``da run sandbox``
    * - ``da compile``
      - Compile a DAML project into a .dar file
      - ``daml build``
-   * - ``da run``
+   * - ``da run <component>``
      - Run an SDK component
-     - ``daml studio``, ``daml navigator``, etc as above
+     - ``daml navigator``, ``daml sandbox``, etc as above
    * - ``da path <component>``
      - Show the path to an SDK component
      - No equivalent
@@ -176,7 +180,7 @@ Managing templates and projects
      - No longer needed: use ``git clone`` instead
    * - ``da new``
      - Create a new project from template
-     - ``daml new  <path to create project in> <name of template>``
+     - ``daml new <target path> <name of template>``
    * - ``da subscribe``
      - Subscribe to a template namespace
      - No longer needed: use ``git clone`` instead
@@ -195,7 +199,7 @@ Docs and feedback
      - New equivalent
    * - ``da docs``
      - Display the documentation
-     - No longer needed: you can access the docs at docs.daml.com, which includes a PDF download for offline use
+     - No longer needed: you can access the docs at `docs.daml.com <https://docs.daml.com/>`__, which includes a PDF download for offline use
    * - ``da feedback``
      - Send us feedback
      - No longer needed: see :doc:`/support/support` for how to give feedback.