From ee1bb81229c6b4ecb4635e051c0c0bab6f63fbcf Mon Sep 17 00:00:00 2001 From: carrie-laben <91496516+carrie-laben@users.noreply.github.com> Date: Wed, 17 Apr 2024 12:49:09 -0400 Subject: [PATCH 1/4] Separate Upgrade and Extend Breaking this section in two. --- docs/3.1/_toc.yml | 13 ++++--------- docs/3.1/docs/upgrade/extend.rst | 2 ++ docs/3.1/docs/upgrade/index.rst | 30 ------------------------------ docs/3.1/docs/upgrade/upgrade.rst | 2 ++ 4 files changed, 8 insertions(+), 39 deletions(-) delete mode 100644 docs/3.1/docs/upgrade/index.rst diff --git a/docs/3.1/_toc.yml b/docs/3.1/_toc.yml index ed8685774..9af05dfbb 100644 --- a/docs/3.1/_toc.yml +++ b/docs/3.1/_toc.yml @@ -234,15 +234,10 @@ subtrees: - file: daml/resource-management/contention-reducing.rst - file: daml/resource-management/contention-techniques.rst - file: daml/resource-management/active-contract-set - - file: upgrade/index - title: "Upgrading and Extending Daml Applications" - entries: - - file: upgrade/extend - title: "Extending Daml Applications" - - file: upgrade/upgrade - title: "Upgrading Daml Applications" - - file: upgrade/automation - title: "Automating the Upgrade Process" + - file: upgrade/extend + title: "Extending Daml Applications" + file: upgrade/upgrade + title: "Upgrading Daml Applications" - file: create-daml-apps/developer-tools/index title: "Developer Tools" subtrees: diff --git a/docs/3.1/docs/upgrade/extend.rst b/docs/3.1/docs/upgrade/extend.rst index 5735d4a71..5bb42cd6d 100644 --- a/docs/3.1/docs/upgrade/extend.rst +++ b/docs/3.1/docs/upgrade/extend.rst @@ -7,6 +7,8 @@ Extending Daml Applications .. .. toctree:: :hidden: +An extension adds new templates and data structures to your Daml model, while leaving all previously written definitions unchanged. + Consider the following simple Daml model for carbon certificates: .. literalinclude:: example/carbon-1.0.0/daml/CarbonV1.daml diff --git a/docs/3.1/docs/upgrade/index.rst b/docs/3.1/docs/upgrade/index.rst deleted file mode 100644 index 238942bea..000000000 --- a/docs/3.1/docs/upgrade/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. Copyright (c) 2023 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. -.. SPDX-License-Identifier: Apache-2.0 - -Upgrading and Extending Daml Applications -######################################### - -.. .. toctree:: - :hidden: - - extend - upgrade - automation - -Database schemas tend to evolve over time. A new feature in your application -might need an additional choice in one of your templates. Or a change in your -data model will make you application perform better. We distinguish two kinds of -changes to a Daml model: - - - A Daml model extension - - A Daml model upgrade - -An *extension* adds new templates and data structures to your model, while -leaving all previously written definitions unchanged. - -An *upgrade* changes previously defined data structures and templates. - -Whether extension or upgrade, your new code needs to be compatible with data -that is already live in a production system. The next two sections show how to -extend and upgrade Daml models. The last section shows how to automate the data -migration process. diff --git a/docs/3.1/docs/upgrade/upgrade.rst b/docs/3.1/docs/upgrade/upgrade.rst index 70c10138c..5b8351588 100644 --- a/docs/3.1/docs/upgrade/upgrade.rst +++ b/docs/3.1/docs/upgrade/upgrade.rst @@ -9,6 +9,8 @@ Upgrading Daml Applications .. .. toctree:: :hidden: +An upgrade changes previously defined data structures and templates in your Daml model. + In applications backed by a centralized database controlled by a single operator, it is possible to upgrade an application in a single step that migrates all existing data to a new data model. From cb8610832155a9d48ca27f047c502184e27a048c Mon Sep 17 00:00:00 2001 From: carrie-laben <91496516+carrie-laben@users.noreply.github.com> Date: Wed, 17 Apr 2024 12:56:04 -0400 Subject: [PATCH 2/4] Automations Add back Automations --- docs/3.1/_toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/3.1/_toc.yml b/docs/3.1/_toc.yml index 9af05dfbb..aa7cebc8a 100644 --- a/docs/3.1/_toc.yml +++ b/docs/3.1/_toc.yml @@ -238,6 +238,8 @@ subtrees: title: "Extending Daml Applications" file: upgrade/upgrade title: "Upgrading Daml Applications" + file: upgrade/automation + title: "Automating Daml Application Upgrades" - file: create-daml-apps/developer-tools/index title: "Developer Tools" subtrees: From 2ed2d13c07dc9a1724566062172e98be6dcc8347 Mon Sep 17 00:00:00 2001 From: carrie-laben <91496516+carrie-laben@users.noreply.github.com> Date: Wed, 17 Apr 2024 13:01:37 -0400 Subject: [PATCH 3/4] Extend is so in this toctree Also, grammar --- docs/3.1/_toc.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/3.1/_toc.yml b/docs/3.1/_toc.yml index aa7cebc8a..141e02c35 100644 --- a/docs/3.1/_toc.yml +++ b/docs/3.1/_toc.yml @@ -234,12 +234,12 @@ subtrees: - file: daml/resource-management/contention-reducing.rst - file: daml/resource-management/contention-techniques.rst - file: daml/resource-management/active-contract-set - - file: upgrade/extend - title: "Extending Daml Applications" + file: upgrade/extend + title: "Extend Daml Applications" file: upgrade/upgrade - title: "Upgrading Daml Applications" + title: "Upgrade Daml Applications" file: upgrade/automation - title: "Automating Daml Application Upgrades" + title: "Automate Daml Application Upgrades" - file: create-daml-apps/developer-tools/index title: "Developer Tools" subtrees: From b091e2e36a03277b1c10bf2dd3beee3fc9cf58de Mon Sep 17 00:00:00 2001 From: carrielaben-da <91496516+carrielaben-da@users.noreply.github.com> Date: Thu, 18 Apr 2024 12:33:27 -0400 Subject: [PATCH 4/4] Update docs/3.1/_toc.yml Co-authored-by: Gary Verhaegen --- docs/3.1/_toc.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/3.1/_toc.yml b/docs/3.1/_toc.yml index 141e02c35..6a416ae91 100644 --- a/docs/3.1/_toc.yml +++ b/docs/3.1/_toc.yml @@ -234,11 +234,11 @@ subtrees: - file: daml/resource-management/contention-reducing.rst - file: daml/resource-management/contention-techniques.rst - file: daml/resource-management/active-contract-set - file: upgrade/extend + - file: upgrade/extend title: "Extend Daml Applications" - file: upgrade/upgrade + - file: upgrade/upgrade title: "Upgrade Daml Applications" - file: upgrade/automation + - file: upgrade/automation title: "Automate Daml Application Upgrades" - file: create-daml-apps/developer-tools/index title: "Developer Tools"