digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-11-08 21:34:22 +03:00
Code Issues Projects Releases Wiki Activity

Documentation of our support and compatibility framework (#7458)

Browse Source 
* Documentation of our support and compatibility framework

CHANGELOG_BEGIN
CHANGELOG_END

* Update docs/source/daml-integration-kit/index.rst

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

* Update docs/source/support/component-statuses.rst

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>

* Address feedback

* Update docs/source/support/compatibility.rst

Co-authored-by: Gerolf Seitz <gerolf.seitz@daml.com>

* Add Deprecations and address feedback

* Fix short title underline

* Apply suggestions from code review

Co-authored-by: Gerolf Seitz <gerolf.seitz@daml.com>

* Improve sentence on Integration Kit

* Imprive SemVer TLDR

* Uncapitalize release candidate

* Fix release timeline image

* Make the DAML Language Server CLI a Labs feature

Co-authored-by: Moritz Kiefer <moritz.kiefer@purelyfunctional.org>
Co-authored-by: Gerolf Seitz <gerolf.seitz@daml.com>
This commit is contained in:
Bernhard Elsner 2020-09-24 16:40:57 +02:00 committed by GitHub
parent 86bdf7b6ec
commit 331ee44978
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 804 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
compiler/damlc/lib/DA/Cli/Damlc.hs
View File

@ -224,14 +224,14 @@ cmdInspect =
cmdVisual :: Mod CommandFields Command
cmdVisual =
command "visual" $ info (helper <*> cmd) $ progDesc "Generate visual from dar (early access)" <> fullDesc
command "visual" $ info (helper <*> cmd) $ progDesc "Early Access (Labs). Generate visual from dar" <> fullDesc
where
cmd = vis <$> inputDarOpt <*> dotFileOpt
vis a b = Command Visual Nothing $ execVisual a b
cmdVisualWeb :: Mod CommandFields Command
cmdVisualWeb =
command "visual-web" $ info (helper <*> cmd) $ progDesc "Generate D3-Web Visual from dar (early access)" <> fullDesc
command "visual-web" $ info (helper <*> cmd) $ progDesc "Early Access (Labs). Generate D3-Web Visual from dar" <> fullDesc
where
cmd = vis <$> inputDarOpt <*> htmlOutFile <*> openBrowser
vis a b browser = Command Visual Nothing $ execVisualHtml a b browser
@ -408,7 +408,7 @@ cmdDocTest :: Int -> Mod CommandFields Command
cmdDocTest numProcessors =
command "doctest" $
info (helper <*> cmd) $
progDesc "doc tests" <> fullDesc
progDesc "Early Access (Labs). doc tests" <> fullDesc
where
cmd = execDocTest
<$> optionsParser numProcessors (EnableScenarioService True) optPackageName

2
compiler/damlc/lib/DA/Cli/Damlc/Command/Damldoc.hs
View File

@ -22,7 +22,7 @@ import qualified Data.Set as Set
cmd :: Int -> (CmdArgs -> a) -> Mod CommandFields a
cmd numProcessors f = command "docs" $
info (helper <*> (f <$> documentation numProcessors)) $
progDesc "Generate documentation for the given DAML program."
progDesc "Early Access (Labs). Generate documentation for the given DAML program."
<> fullDesc
documentation :: Int -> Parser CmdArgs

2
daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs
View File

@ -165,7 +165,7 @@ commandParser = subparser $ fold
<*> (JsonApiOptions <$> many (strOption (long "json-api-option" <> metavar "JSON_API_OPTION" <> help "Pass option to HTTP JSON API")))
<*> (ScriptOptions <$> many (strOption (long "script-option" <> metavar "SCRIPT_OPTION" <> help "Pass option to DAML script interpreter")))
<*> stdinCloseOpt
<*> (SandboxClassic <$> switch (long "sandbox-classic" <> help "Run with Sandbox Classic."))
<*> (SandboxClassic <$> switch (long "sandbox-classic" <> help "Deprecated. Run with Sandbox Classic."))
navigatorFlag =
-- We do not use flagYesNoAuto here since that doesn’t allow us to differentiate

2
daml-script/runner/src/main/scala/com/digitalasset/daml/lf/engine/script/RunnerConfig.scala
View File

@ -108,7 +108,7 @@ object RunnerConfig {
.action { (_, c) =>
c.copy(jsonApi = true)
}
.text("Run DAML Script via the HTTP JSON API instead of via gRPC (experimental).")
.text("Run DAML Script via the HTTP JSON API instead of via gRPC.")
opt[Int]("max-inbound-message-size")
.action((x, c) => c.copy(maxInboundMessageSize = x))

11
docs/configs/pdf/index.rst
View File

@ -100,13 +100,14 @@ Early Access Features
triggers/index
tools/visual
Support and updates
-------------------
DAML Ecosystem
--------------
.. toctree::
:titlesonly:
:maxdepth: 2
support/support
support/release-notes
Roadmap <support/roadmap>
support/overview
support/releases
support/compatibility
support/support

6
docs/redirects.map
View File

@ -1,9 +1,7 @@
app-arch/index.html -> /app-dev/app-arch.html
release-notes.html -> /support/release-notes.html
tools/extractor.html
integration.html -> /app-dev/app-arch.html
index.html
support.html -> /support/support.html
daml.html -> /daml/reference/index.html
daml/reference/template-reference.html -> /daml/reference/index.html
daml/anti-patterns.html
@ -815,3 +813,7 @@ app-dev/authentication.html -> /app-dev/authorization.html
daml/intro/2_Scenario.html -> /daml/intro/2_DamlScript.html
daml-script/daml-script-docs.html -> /daml-script/api/index.html
triggers/trigger-docs.html -> /triggers/api/index.html
support.html -> /support/support.html
release-notes.html -> support/releases.html#release-notes
support/release-notes.html -> support/releases.html#release-notes
support/roadmap.html -> support/releases.html#roadmap

142
docs/source/app-dev/bindings-java/index.rst
View File

@ -42,7 +42,7 @@ The Java bindings library is composed of:
Can be found in the java package ``com.daml.ledger.rxjava``.
- The Reactive Components
A set of optional components you can use to assemble DAML Ledger applications.
A set of optional components you can use to assemble DAML Ledger applications. These components are deprecated as of 2020-10-14.
The most important components are:
@ -67,73 +67,6 @@ Connections to the ledger are made by creating instance of classes that implemen
This class provides access to the ledgerId, and all clients that give access to the various ledger services, such as the active contract set, the transaction service, the time service, etc. This is described :ref:`below <ledger-api-java-binding-connecting>`. Consult the `JavaDoc for DamlLedgerClient <javadocs/com/daml/ledger/rxjava/DamlLedgerClient.html>`_ for full details.
Accessing data on the ledger: LedgerView
========================================
The ``LedgerView`` of an application is the "copy" of the ledger that the application has locally. You can query it to obtain the contracts that are active on the Ledger and not pending.
.. note::
- A contract is *active* if it exists in the Ledger and has not yet been archived.
- A contract is *pending* if the application has sent a consuming command to the Ledger and has yet
to receive an completion for the command (that is, if the command has succeeded or not).
The ``LedgerView`` is updated every time:
- a new event is received from the Ledger
- new commands are sent to the Ledger
- a command has failed to be processed
For instance, if an incoming transaction is received with a create event for a contract that is relevant
for the application, the application ``LedgerView`` is updated to contain that contract too.
Writing automations: Bot
========================
The ``Bot`` is an abstraction used to write automation for a DAML Ledger. It is conceptually
defined by two aspects:
- the ``LedgerView``
- the logic that produces commands, given a ``LedgerView``
When the ``LedgerView`` is updated, to see if the bot has new commands to submit based on the
updated view, the logic of the bot is run.
The logic of the bot is a Java function from the bot's ``LedgerView`` to a ``Flowable<CommandsAndPendingSet>``.
Each ``CommandsAndPendingSet`` contains:
- the commands to send to the Ledger
- the set of contractIds that should be considered pending while the command is in-flight
(that is, sent by the client but not yet processed by the Ledger)
You can wire a ``Bot`` to a ``LedgerClient`` implementation using ``Bot.wire``:
.. code-block:: java
Bot.wire(String applicationId,
LedgerClient ledgerClient,
TransactionFilter transactionFilter,
Function<LedgerViewFlowable.LedgerView<R>, Flowable<CommandsAndPendingSet>> bot,
Function<CreatedContract, R> transform)
In the above:
- ``applicationId``
The id used by the Ledger to identify all the queries from the same application.
- ``ledgerClient``
The connection to the Ledger.
- ``transactionFilter``
The server-side filter to the incoming transactions. Used to reduce the traffic between
Ledger and application and make an application more efficient.
- ``bot``
The logic of the application,
- ``transform``
The function that, given a new contract, returns which information for
that contracts are useful for the application. Can be used to reduce space used
by discarding all the info not required by the application. The input to the function
contains the ``templateId``, the arguments of the contract created and the context of
the created contract. The context contains the ``workflowId``.
Reference documentation
***********************
@ -212,7 +145,80 @@ Advanced connection settings
Sometimes the default settings for gRPC connections/channels are not suitable for a given situation. These use cases are supported by creating a a custom `NettyChannelBuilder <https://grpc.github.io/grpc-java/javadoc/io/grpc/netty/NettyChannelBuilder.html>`_ object and passing the it to the ``newBuilder`` static method defined over `DamlLedgerClient <javadocs/com/daml/ledger/rxjava/DamlLedgerClient.html>`_.
Reactive Components
===================
The Reactive Components are deprecated as of 2020-10-14.
Accessing data on the ledger: LedgerView
----------------------------------------
The ``LedgerView`` of an application is the "copy" of the ledger that the application has locally. You can query it to obtain the contracts that are active on the Ledger and not pending.
.. note::
- A contract is *active* if it exists in the Ledger and has not yet been archived.
- A contract is *pending* if the application has sent a consuming command to the Ledger and has yet
to receive an completion for the command (that is, if the command has succeeded or not).
The ``LedgerView`` is updated every time:
- a new event is received from the Ledger
- new commands are sent to the Ledger
- a command has failed to be processed
For instance, if an incoming transaction is received with a create event for a contract that is relevant
for the application, the application ``LedgerView`` is updated to contain that contract too.
Writing automations: Bot
------------------------
The ``Bot`` is an abstraction used to write automation for a DAML Ledger. It is conceptually
defined by two aspects:
- the ``LedgerView``
- the logic that produces commands, given a ``LedgerView``
When the ``LedgerView`` is updated, to see if the bot has new commands to submit based on the
updated view, the logic of the bot is run.
The logic of the bot is a Java function from the bot's ``LedgerView`` to a ``Flowable<CommandsAndPendingSet>``.
Each ``CommandsAndPendingSet`` contains:
- the commands to send to the Ledger
- the set of contractIds that should be considered pending while the command is in-flight
(that is, sent by the client but not yet processed by the Ledger)
You can wire a ``Bot`` to a ``LedgerClient`` implementation using ``Bot.wire``:
.. code-block:: java
Bot.wire(String applicationId,
LedgerClient ledgerClient,
TransactionFilter transactionFilter,
Function<LedgerViewFlowable.LedgerView<R>, Flowable<CommandsAndPendingSet>> bot,
Function<CreatedContract, R> transform)
In the above:
- ``applicationId``
The id used by the Ledger to identify all the queries from the same application.
- ``ledgerClient``
The connection to the Ledger.
- ``transactionFilter``
The server-side filter to the incoming transactions. Used to reduce the traffic between
Ledger and application and make an application more efficient.
- ``bot``
The logic of the application,
- ``transform``
The function that, given a new contract, returns which information for
that contracts are useful for the application. Can be used to reduce space used
by discarding all the info not required by the application. The input to the function
contains the ``templateId``, the arguments of the contract created and the context of
the created contract. The context contains the ``workflowId``.
Example project
***************
Example projects using the Java bindings are available on `GitHub <https://github.com/digital-asset/ex-java-bindings>`__. :doc:`Read more about them here </app-dev/bindings-java/example>`.

2
docs/source/app-dev/bindings-js.rst
View File

@ -4,6 +4,8 @@
Node.js bindings
################
The Node.js bindings are deprecated as of 2020-10-14.
The documentation for the Node.js bindings has been moved to `digital-asset.github.io/daml-js <http://digital-asset.github.io/daml-js/>`__.
You can also try the Node.js bindings tutorial, which is at `github.com/digital-asset/ex-tutorial-nodejs <https://github.com/digital-asset/ex-tutorial-nodejs>`__.

2
docs/source/app-dev/bindings-scala/index.rst
View File

@ -6,6 +6,8 @@
Scala bindings
##############
The Scala bindings are deprecated as of 2020-10-14.
This page provides a basic Scala programmer's introduction to working with DAML Ledgers,
using the Scala programming language and the **Ledger API**.

8
docs/source/daml-integration-kit/index.rst
View File

@ -1,8 +1,10 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
DAML Integration Kit - ALPHA
############################
DAML Integration Kit
####################
The DAML Integration Kit is currently an :doc:`Early Access Feature in Labs status </support/status-definitions>`. It comprises the components needed to build your own :ref:`DAML Drivers <ecosystem-architecture>`.
.. toctree::
:hidden:
@ -228,7 +230,7 @@ Library infrastructure overview
To help you implement your server and validator, we provide the following
four Scala libraries as part of the DAML SDK. Changes
to them are explained as part of the :doc:`/support/release-notes`.
to them are explained as part of the :ref:`release-notes`.
As explained in :ref:`integration-kit_writing_code`,
this section is best read jointly with the code in

2
docs/source/getting-started/installation.rst
View File

@ -24,6 +24,8 @@ Windows 10
Download and run the installer_, which will install DAML and set up your PATH.
.. _mac-linux-sdk:
Mac and Linux
=============

9
docs/source/index.rst
View File

@ -112,8 +112,9 @@ DAML SDK documentation
:titlesonly:
:maxdepth: 2
:hidden:
:caption: Support and updates
:caption: DAML Ecosystem
support/support
support/release-notes
Roadmap <support/roadmap>
support/overview
support/releases
support/compatibility
support/support

BIN
docs/source/support/architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

57
docs/source/support/compatibility.rst Normal file
View File

@ -0,0 +1,57 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Portability, Compatibility, and Support Durations
=================================================
The DAML Ecosystem offers a number of forward and backward compatibility guarantees aiming to give the Ecosystem as a whole the following properties. See :ref:`ecosystem-architecture` for the terms used here and how they fit together.
Application Portability
A DAML application should not depend on the underlying Database or DLT used by a DAML Network.
Network Upgradeability
Ledger Operators should be able to upgrade DAML Network or Participant Nodes seamlessly to stay up to date with the latest features and fixes. A DAML application should be able to operate without significant change across such Network Upgrades.
SDK Upgradeability
Application Developers should be able to update their developer tools seamlessly to stay up to date with the latest features and fixes, and stay able to maintain and develop their existing applications.
Ledger API Compatibility: Application Portability
-------------------------------------------------
Application Portability and to some extent Network Upgradeability are achieved by intermediating through the Ledger API. As per :ref:`versioning`, and :ref:`ecosystem-architecture`, the Ledger API is independently semantically versioned, and the compatibility guarantees derived from that semantic versioning extend to the entire semantics of the API, including the behavior of DAML Packages on the Ledger. Since all interaction with a DAML Ledger happens through the DAML Ledger API, a DAML Application is guaranteed to work as long as the Participant Node exposes a compatible Ledger API version.
Specifically, if a DAML Application is built against Ledger API version X.Y.Z and a Participant Node exposes Ledger API version X.Y2.Z2, the application is guaranteed to work as long as Y2.Z2 >= Y.Z.
Currently, the Ledger API version is the same as the version of the Integration Components used in the Participant Node. This is mostly the case because there has been no need for the versions to diverge yet. This will likely change at the latest when one part of the ecosystem moves to version 2.X. Integration Components, DAML Drivers, and Participant Nodes advertise the Ledger API version they expose.
As a concrete example, DAML for Postgres 1.4.0 has the Participant Node integrated, and exposes Ledger API version 1.4.0 and the DAML for VMware Blockchain 1.0 Participant Nodes expose Ledger API version 1.6.0. So any application that runs on DAML for Postgres 1.4.0 will also run on DAML for VMware Blockchain 1.0.
Driver and Participant Compatibility: Network Upgradeability
------------------------------------------------------------
Given the Ledger API Compatibility above, network upgrades are seamless if they preserve data, and Participant Nodes keep exposing the same or a newer minor version of the same major Ledger API Version. The semantic versioning of DAML Drivers and Participant Nodes gives this guarantee. Upgrades from one minor version to another are data preserving, and major Ledger API versions may only be removed with a new major version of Integration Components, DAML Drivers and Participant Nodes.
As an example, from an application standpoint, the only effect of upgrading DAML for Postgres 1.4.0 to DAML for Postgres 1.6.0 is an uptick in the Ledger API version. There may be significant changes to components or database schemas, but these are not public APIs.
SDK, Runtime Component, and Library Compatibility: SDK Upgradeability
---------------------------------------------------------------------
As long as a major Ledger API version is supported (see :ref:`ledger-api-support`), there will be supported versions of SDK, Runtime Components, and Libraries able to target all minor versions of that major version. This has the obvious caveat that new features may not be available with old Ledger API versions.
For example, an application built and compiled with SDK, Libraries and Runtime Components 1.4.0 against Ledger API 1.4.0, it can still be compiled using SDK 1.6.0 and can be run against Ledger API 1.4.0 using 1.6.0 libraries and runtime components.
.. _ledger-api-support:
Ledger API Support Duration
---------------------------
Major Ledger API versions behave like stable features in :doc:`status-definitions`. They are supported from the time they are first released as "stable" to the point where they are removed from Integration Components and SDK following a 12 month deprecation cycle. The earliest point a major Ledger API version can be deprecated is with the release of the next major version. The earliest it can be removed is 12 months later with a major version release of the Integration Components.
Other than for hotfix releases, new releases of the Integration Components will only support the latest minor/patch version of each major Ledger API version.
As a result we can make this overall statement:
**An application built using SDK, Libraries and Runtime Components U.V.W against Ledger API X.Y.Z can be maintained using any SDK, Library amd Runtime Components version U2.V2.W2 >= U.V.W as long as Ledger API major version X is still supported at the time of release of U2.V2.W2, and run against any DAML Network with Participant Nodes exposing Ledger API X.Y2.Z2 >= X.Y.Z.**

349
docs/source/support/component-statuses.rst Normal file
View File

@ -0,0 +1,349 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Feature and Component Statuses
==============================
This page gives an overview of the statuses of released components and features according to :doc:`status-definitions`. Anything not listed here implicitly has status "Labs", but it's possible that something accidentally slipped the list so if in doubt, please :doc:`contact us <support>`.
Ledger API
----------
.. list-table::
:widths: 80 10 10
:header-rows: 1
* - Component/Feature
- Status
- Deprecated on
* - :doc:`Ledger API specification </app-dev/grpc/proto-docs>` including all semantics of >= DAML-LF 1.6
- Stable
-
* - `Numbered (ie non-dev) Versions of Proto definitions distributed via GitHub Releases <protobufs_>`_
- Stable
-
* - `Dev Versions of Proto definitions distributed via GitHub Releases <protobufs_>`_
- Alpha
-
Integration Components
----------------------
.. list-table::
:widths: 80 10 10
:header-rows: 1
* - Component/Feature
- Status
- Deprecated on
* - :doc:`Integration Kit Components </daml-integration-kit/index>`
- Labs
-
* - CLI and test names of :doc:`/tools/ledger-api-test-tool/index`
- Beta
-
.. _runtime-components:
Runtime components
------------------
.. list-table::
:widths: 80 10 10
:header-rows: 1
* - Component / Feature
- Status
- Deprecated on
* - **JSON API**
-
-
* - HTTP endpoints under ``/v1/`` including status codes, authentication, query language and encoding.
- Stable
-
* - ``daml json-api`` CLI :ref:`for development <dev-tools>`. (as specified using ``daml json-api --help``)
- Stable
-
* - Stand-alone distribution for production use, including CLI specified in ``--help``.
- Stable
-
* - **Triggers**
-
-
* - :doc:`DAML API of individual Triggers </triggers/index>`
- Beta
-
* - :doc:`Development CLI to start individual triggers in dev environment </triggers/index>` (``daml trigger``)
- Beta
-
* - :doc:`/tools/trigger-service` (``daml trigger-service``)
- Alpha
-
* - **Extractor**
-
-
* - :doc:`/tools/extractor` (``daml extractor``)
- Labs
-
.. _libraries:
Libraries
---------
.. list-table::
:widths: 80 10 10
:header-rows: 1
* - Component / Feature
- Status
- Deprecated on
* - **Scala Ledger API Bindings**
-
-
* - ``daml codegen scala`` :doc:`CLI and generated code </app-dev/bindings-scala/index>`
- Stable, Deprecated
- 2020-10-14
* - ``bindings-scala_2.12`` :doc:`library and its public API </app-dev/bindings-scala/index>`
- Stable, Deprecated
- 2020-10-14
* - **Java Ledger API Bindings**
-
-
* - ``daml codegen java`` :doc:`CLI and generated code </app-dev/bindings-java/codegen>`
- Stable
-
* - ``bindings-java`` :doc:`library and its public API </app-dev/bindings-java/index>`.
- Stable
-
* - ``bindings-rxjava`` :doc:`library and its public API </app-dev/bindings-java/index>` *excluding* the reactive components in package ``com.daml.ledger.rxjava.components``.
- Stable
-
* - Java Reactive Components in the ``com.daml.ledger.rxjava.components`` package of ``bindings-rxjava``.
- Stable, Deprecated
- 2020-10-14
* - Maven artifact ``daml-lf-1.6-archive-java-proto``
- Stable
-
* - Maven artifact ``daml-lf-1.7-archive-java-proto``
- Stable
-
* - Maven artifact ``daml-lf-1.8-archive-java-proto``
- Stable
-
* - Maven artifact ``daml-lf-dev-archive-java-proto``
- Alpha
-
* - **Node.js Ledger API Bindings**
-
-
* - ``@digital-asset/bindings-js`` :doc:`Node.js library </app-dev/bindings-js>`
- Stable, Deprecated
- 2020-10-14
* - **JavaScript Client Libraries**
-
-
* - ``daml codegen js`` :doc:`CLI and generated code </app-dev/bindings-ts/daml2js>`
- Stable
-
* - ``@daml/types`` :doc:`library and its public API </app-dev/bindings-ts/daml-types>`
- Stable
-
* - ``@daml/ledger`` :doc:`library and its public API </app-dev/bindings-ts/daml-ledger>`
- Stable
-
* - ``@daml/react`` :doc:`library and its public API </app-dev/bindings-ts/daml-react>`
- Stable
-
* - **DAML Libraries**
-
-
* - :doc:`The DAML Standard Library </daml/stdlib/index>`
- Stable
-
* - :doc:`The DAML Script Library </daml-script/api/index>`
- Stable
-
* - :doc:`The DAML Trigger Library </triggers/api/index>`
- Stable
-
.. _dev-tools:
Developer Tools
---------------
.. list-table::
:widths: 80 10 10
:header-rows: 1
* - Component / Feature
- Status
- Deprecated on
* - **SDK**
-
-
* - Windows SDK (installer_)
- Stable
-
* - :ref:`Mac SDK <mac-linux-sdk>`
- Stable
-
* - :ref:`Linux SDK <mac-linux-sdk>`
- Stable
-
* - :doc:`/tools/assistant` with top level commands
- ``--help``
- ``version``
- ``install``
- ``uninstall``
- Stable
-
* - ``daml start`` helper command and associated CLI (``daml start --help``)
- Stable
-
* - ``daml deploy`` :doc:`helper command and associated CLI </deploy/generic_ledger>` (``daml deploy --help``)
- Stable
-
* - Assistant commands to start Runtime Components: ``daml json-api`, ``daml trigger``, ``daml trigger-service``, and ``daml extractor``.
- See :ref:`runtime-components`.
-
* - **DAML Projects**
-
-
* - ``daml.yaml`` project specification
- Stable
-
* - Assistant commands ``new``, ``create-daml-app``, and ``init``. Note that the templates created by ``daml new`` and ``create-daml-app`` are considered example code, and are not covered by :ref:`semantic versioning <versioning>`.
- Stable
-
* - **DAML Studio**
-
-
* - VSCode Extension
- Stable
-
* - ``daml studio`` assistant command
- Stable
-
* - **Code Generation**
-
-
* - ``daml codegen`` assistant commands
- See :ref:`libraries`.
-
* - **Sandbox Development Ledger**
-
-
* - ``daml sandbox`` assistant command and documented CLI under ``daml sandbox --help``.
- Stable
-
* - DAML Sandbox in Memory (ie without the ``--sql-backend-jdbcurl`` flag)
- Stable
-
* - DAML Sandbox on Postgres (iw with the ``--sql-backend-jdbcurl`` flag)
- Stable
-
* - DAML Sandbox Classic and associated CLIs ``daml sandbox-classic``, ``daml start --sandbox-classic``
- Stable, Deprecated
- 2020-04-09
* - **DAML Compiler**
-
-
* - ``daml build`` CLI
- Stable
-
* - ``daml damlc`` CLI
- Stable
-
* - Compilation and packaging (``daml damlc build``)
- Stable
-
* - Legacy packaging command (``daml damlc package``)
- Stable, Deprecated
- 2020-10-14
* - In-memory Scenario/Script testing (``daml damlc test``)
- Stable
-
* - DAR File inspection (``daml damlc inspect-dar``). The exact output is only covered by :ref:`semantic versioning <versioning>` when used with the ``--json`` flag.
- Stable
-
* - DAR File validation (``daml damlc validate-dar``)
- Stable
-
* - DAML Linter (``daml damlc lint``)
- Stable
-
* - DAML REPL (``daml damlc repl``)
- See DAML REPL heading below
-
* - DAML Language Server CLI (``daml damlc ide``)
- Labs
-
* - DAML Documentation Generation (``daml damlc docs``)
- Labs
-
* - :doc:`DAML Model Visualization </tools/visual>` (``daml damlc visual`` and ``daml damlc visual-web``)
- Labs
-
* - ``daml doctest``
- Labs
-
* - **Scenarios and Script**
-
-
* - Scenario DAML API
- Stable
-
* - :doc:`Script DAML API </daml-script/index>`
- Stable
-
* - DAML Scenario IDE integration
- Stable
-
* - DAML Script IDE integration
- Stable
-
* - :doc:`DAML Script Library </daml-script/api/index>`
- See :ref:`libraries`
-
* - ``daml test`` in-memory Script and Scenario test CLI
- Stable
-
* - ``daml test-script`` Sandbox-based Script Testing
- Stable
-
* - ``daml script`` :doc:`CLI to run Scripts against live ledgers. </daml-script/index>`
- Stable
-
* - **Navigator**
-
-
* - :doc:`DAML Navigator Development UI </tools/navigator/index>` (``daml navigator server``)
- Stable
-
* - Navigator Config File Creation (``daml navigator create-config``)
- Stable
-
* - :doc:`DAML Navigator Console </tools/navigator/console>` (``daml navigator console``)
- Labs
-
* - Navigator graphQL Schema (``daml navigator dump-graphql-schema``)
- Labs
-
* - **DAML REPL Interactive Shell**
-
-
* - ``daml repl`` :doc:`CLI </daml-repl/index>`
- Stable
-
* - :doc:`DAML and meta-APIs of the REPL </daml-repl/index>`
- Stable
-
* - **Ledger Administration CLI**
-
-
* - ``daml ledger`` :doc:`CLI and all subcommands </deploy/generic_ledger>`.
- Stable
-

65
docs/source/support/overview.rst Normal file
View File

@ -0,0 +1,65 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
DAML Ecosystem Overview
=======================
.. toctree::
:hidden:
status-definitions
component-statuses
This page is intended to give you an overview of the components that constitute the DAML Ecosystem, what status they are in, and how they fit together. It lays out DAML's "public API" in the sense of :ref:`Semantic Versioning <versioning>`, and is a prerequisite to understanding DAML's :doc:`compatibility`.
The pages :doc:`status-definitions` and :doc:`component-statuses` give a fine-grained view of what labels like "Alpha" and "Beta" mean, which components expose public APIs and what status they are in.
.. _ecosystem-architecture:
Architecture
------------
A high level view of the architecture of a DAML application or solution is helpful to make sense of how individual components, APIs and features fit into the DAML Stack.
.. figure:: architecture.png
DAML Networks
.............
At the bottom of every DAML Application is a DAML Network, a distributed, or possibly centralized persistence infrastructure together with DAML Drivers. DAML Drivers enable the persistence infrastructure to act as a consensus, messaging, and in some cases persistence layer for DAML Applications. Most DAML Drivers will have a public API, but there are no _uniform_ public APIs on DAML Drivers. This does not harm application portability since applications only interact with DAML Networks through the Participant Node. A good example of a public API of a DAML Driver is the command line interface of `DAML for Postgres <https://github.com/digital-asset/daml/blob/master/ledger/daml-on-sql/README.rst>`_. It's a public interface, but specific to the Postgres driver.
Participant Nodes
.................
On top of, or integrated into the DAML Drivers sits a Participant Node, that has the primary purpose of exposing the DAML Ledger API. In the case of _integrated_ DAML Drivers, the Participant Node usually interacts with the DAML Drivers through solution-specific APIs. In this case, Participant Nodes can only communicate with DAML Drivers of one DAML Network. In the case of _interoperable_ DAML Drivers, the Participant Node communicates with the DAML Drivers through the uniform `Canton Protocol <https://www.canton.io/docs/stable/user-manual/index.html>`_. The Canton Protocol is versioned and has some cross-version compatibility guarantees, but is not a public API. So Participant nodes may have public APIs like monitoring and logging, command line interfaces or similar, but the only _uniform_ public API exposed by all Participant Nodes is the Ledger API.
Integration Components
......................
DAML Drivers and Participant Nodes share a lot of components between underlying DLTs or Databases. These shared components are called the Integration Components, or sometimes the :doc:`/daml-integration-kit/index`.
Ledger API
..........
The Ledger API is the primary interface that offers forward and backward compatibility between DAML Networks and Applications. As you can see in the diagram above, all interaction between components above the Participant Node and the Participant Node or DAML Network happen through the Ledger API. The Ledger API is a public API and offers the lowest level of access to DAML Ledgers supported for application use.
Runtime Components
..................
Runtime components are standalone components that run alongside Participant Nodes or Applications and expose additional services like query endpoints, automations, or integrations. Each Runtime Component has public APIs, which are covered in :doc:`component-statuses`. Typically there is a command line interface, and one or more "Runtime APIs" as indicated in the above diagram.
Libraries
.........
Libraries naturally provide public APIs in their target language, be it DAML, or secondary languages like JavaScript or Java. For details on available libraries and their interfaces, see :doc:`component-statuses`.
Generated Code
..............
The developer tools in the SDK allow the generation of code for some languages from a DAML Model. This generated code has public APIs, but is not independently versioned, but depends on the SDK version and source of the generated code, like a DAML package. In this case, the version of the SDK used covers changes to the public API of the generated code.
SDK
...
The SDK consists of the developer tools used to develop user code, both DAML and in secondary languages, to generate code, and to interact with running applications via Runtime, and Ledger API. The SDK has a broad public API covering the DAML Language, CLIs, IDE, and Developer tools, but few of those APIs are intended for runtime use in a production environment. Exceptions to that are called out on :doc:`component-statuses`.

7
docs/source/support/release-notes.rst
View File

@ -1,7 +0,0 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Release notes
#############
Release notes are now hosted on `the DAML blog <https://daml.com/release-notes/>`_.

BIN
docs/source/support/release-timeline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

86
docs/source/support/releases.rst Normal file
View File

@ -0,0 +1,86 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Releases and Versioning
=======================
.. _versioning:
Versioning
----------
All DAML components follow `Semantic Versioning <https://semver.org/>`_. In short, this means that there is a well defined "public API", changes or breakages to which are indicated by the version number.
Stable releases have versions MAJOR.MINOR.PATCH. Segments of the version are incremented according to the following rules:
#. MAJOR version when there are incompatible API changes,
#. MINOR version when functionality is added in a backwards compatible manner, and
#. PATCH version when there are only backwards compatible bug fixes.
DAML's "public API" is laid out in the :doc:`overview`.
Cadence
-------
Regular snapshot releases are made every Wednesday, with additional snapshots released as needed. These releases contain SDK, Libraries, Runtime Components, and Integration Components, both from the `daml repository <https://github.com/digital-asset/daml>`_ as well as some others.
Stable versions are released once a month. See :ref:`release_process` below for the usual schedule. This schedule is a guide, not a guarantee, and additional releases may be made, or releases may be delayed for skipped entirely.
No more than one major version is released every six months, barring exceptional circumstances.
Individual DAML Drivers follow their own release cadence, using already released Integration Components as a dependency.
.. _release-notes:
Release Notes
-------------
Release notes for each release are published on the `Release Notes section of the DAML Driven blog <https://daml.com/release-notes/>`_.
.. _roadmap:
Roadmap
-------
Once a month Digital Asset publishes a community update to accompany the announcement of the release candidate for the next release. The community update contains a section outlining the next priorities for development. You can find community updates on the `DAML Driven Blog <https://daml.com/daml-driven>`_, or subscribe to the mailing list or social media profiles on `https://daml.com/ <https://daml.com/>`_ to stay up to date.
.. _release_process:
Process
-------
Weekly snapshot and monthly stable releases follow a regular process and schedule. The process is documented `in the DAML repository <https://github.com/digital-asset/daml/blob/master/release/RELEASE.md>`_ so only the schedule for monthly releases is covered here.
Selecting a Release Candidate
This is done by the DAML core engineering teams on the **first Monday of every month**.
The monthly releases are time-based, not scope-based. Furthermore, DAML development is fully HEAD-based so both the repository and every snapshot are intended to be in a fully releasable state at every point. The release process therefore starts with "selecting a release candidate". Typically the Snapshot from the preceding Wednesday is selected as the release candidate.
Release Notes and Candidate Review
After selecting the release candidate, Release Notes are written and reviewed with a particular view towards unintended changes and violations of :ref:`Semantic Versioning <versioning>`.
Release Candidate Refinement
If issues surface in the initial review, the issues are resolved and different Snapshot is selected as the release candidate.
Release Candidate Announcement
Barring delays due to issues during initial review, the release candidate is announced publicly with accompanying Release Notes on **the Thursday following the first Monday of every Month**.
Communications, Testing and Feedback
In the days following the announcement, the release is presented and discussed with both commercial and community users. It is also put through its paces by integrating it in `project:DABL <https://projectdabl.com>`_ and several ledger integrations.
Release Candidate Refinement II
Depending on feedback and test results, new release candidates may be issued iteratively. Depending on the severity of changes from release candidate to release candidate, the testing period is extended more or less.
Release
Assuming the release is not postponed due to extended test periods or newly discovered issues in the release candidate, the release is declared stable and given a regular version number on **the second Wednesday after the first Monday of the Month**.
.. figure:: release-timeline.png
The release process timeline illustrated by example of September 2020.

8
docs/source/support/roadmap.rst
View File

@ -1,8 +0,0 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
DAML roadmap (as of July 2020)
===================================
A new roadmap is currently being worked on and will be published soon.
If you have requests for features, see the :doc:`/support/support` page for how to get in touch.

127
docs/source/support/status-definitions.rst Normal file
View File

@ -0,0 +1,127 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Status Definitions
==================
Throughout the documentation, we use labels to mark features of APIs not yet deemed stable. This page gives meaning to those labels.
Early Access Features
---------------------
Features or components covered by these docs are :ref:`Stable <status_definitions>` by default. :ref:`Stable <status_definitions>` features and components constitute DAML's "public API" in the sense of :ref:`Semantic Versioning <versioning>`. Feature and components that are not :ref:`Stable <status_definitions>` are called "Early Access" and called out explicitly.
Early Access features are opt-in whenever possible, needing to be activated with special commands or flags needing to be started up separately, or requiring the use of additional endpoints, for example.
Within the Early Access category, we distinguish three labels:
Labs
Labs components and features are experiments, introduced for evaluation, testing, or project-internal use. There is no intent to develop them into a stable feature other than to see whether they add value and find uptake. They can be changed or discontinued without advance notice. They may be poorly documented and it is not recommended to start relying on them.
Alpha
Alpha components and features are early preview versions of features being actively developed to become a stable part of the ecosystem. At the Alpha stage, they are not yet feature complete, may have poor runtime characteristics, are still subject to frequent change, and may not be fully documented. Alpha features can be evaluated, and used in PoCs, but should not yet be relied upon for large projects or production use where breakages or changes to APIs would be costly.
Beta
Beta components and features are preview versions of features that are close to maturity. They are characterized by being considered feature complete, and the APIs close to the final public APIs. It is relatively safe to build on Beta features as long as the documented caveats to runtime characteristics are understood and bugs and minor API adjustments are not too costly.
Deprecation
-----------
In addition to being labelled Early Access, features and components can also be labelled "Deprecated". Deprecation follows a deprecation cycle laid out in the table below. The date of deprecation is documented in :doc:`overview`.
Deprecated features can be relied upon during the deprecation cycle to the same degree as their non-deprecated counterparts, but building on deprecated features may hinder an upgrade to new DAML versions following the deprecation cycle.
.. _status_definitions:
Comparison of Statuses
----------------------
The table below gives a concise overview of the labels used for DAML features and components.
.. list-table:: Feature Maturities
:widths: 10 20 20 20 20
:header-rows: 1
* -
- Stable
- Beta
- Alpha
- Labs
* - **Functionality**
-
-
-
-
* - Functional Completeness
- Functionally complete
- Considered functionally complete, but subject to change according to usability testing
- MVP-level functionality covering at least a few core use-cases
- Functionality covering one specific use-case it was made for
* - **Non-functional Requirements**
-
-
-
-
* - Performance
- Unless stated otherwise, the feature can be used without concern about system performance.
- Current performance impacts and expected performance for the stable release are documented.
- Using the feature may have significant undocumented impact on overall system performance.
- Using the feature may have significant undocumented impact on overall system performance.
* - Compatibility
- Compatibility is covered by :doc:`compatibility`.
- Compatibility is covered by :doc:`compatibility`.
- The feature may only work against specific DAML integrations, or specific API versions, including Early Access ones.
- The feature may only work against specific DAML integrations, or specific API versions, including Early Access ones.
* - Stability & Error Recovery
- The feature is long-term stable and supports recovery fit for a production system.
- No known reproducible crashes which can't be recovered from. There is still an expectation that new issues may be discovered.
- The feature may not be stable and lack error recovery.
- The feature may not be stable and lack error recovery.
* - **Releases and Support**
-
-
-
-
* - Distribution and Releases
- Distributed as part of regular :doc:`releases <releases>`.
- Distributed as part of regular :doc:`releases <releases>`.
- Distributed as part of regular :doc:`releases <releases>`.
- Releases and distribution may be separate.
* - Support
- Covered by standard commercial support terms. Hotfixes for critical bugs and security issues are available.
- Not covered by standard commercial support terms. Receives bug- and security fixes with regular releases.
- Not covered by standard commercial support terms. Receives bug- and security fixes with regular releases.
- Not covered by standard commercial support terms. Only receives fixes with low priority.
* - Deprecation
- May be removed with any new major version 12 months after the date of deprecation.
- May be removed with any new minor version 1 month after the date of deprecation.
- May be removed without warning.
- May be removed without warning.
* - Covered by :ref:`Semantic Versioning <versioning>`
- Yes, part of the "public API".
- No, but breaking changes will be documented.
- No, and changes may be poorly documented.
- No, and changes may be poorly documented.
* - **Documentation**
-
-
-
-
* - Basic Use
- Fully documented as part of main docs.
- Fully documented as part of main docs.
- Basic documentation as part of main docs.
- Documentation may be sparse and separate from the main docs.
* - API, Functionality, and Gaps
- Fully documented as part of main docs.
- Fully documented as part of main docs.
- Rough indication of targeted functionality and current limitations.
- May be undocumented.
* - Compatibility
- Covered by :doc:`compatibility`.
- Covered by :doc:`compatibility`.
- Current compatibility documented as part of main docs.
- May be undocumented.

4
docs/source/support/support.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Support
=======
Getting Help
============
Have questions or feedback? You're in the right place.

2
docs/source/tools/extractor.rst
View File

@ -4,6 +4,8 @@
Extractor
#########
The Extractor is currently an :doc:`Early Access Feature in Labs status </support/status-definitions>`.
Introduction
************

2
docs/source/tools/navigator/console.rst
View File

@ -4,6 +4,8 @@
Navigator Console
#################
The Navigator Console is currently an :doc:`Early Access Feature in Labs status </support/status-definitions>`.
.. toctree::
:hidden:

1
docs/source/tools/navigator/database.rst
View File

@ -59,3 +59,4 @@ Filter on the content of an array if the index is specified::
Filter on the content of an array if the index is not specified::
sql select contract.id from contract, json_tree(contract.value) where atom is not null and json_tree.path like '$.template.choices[%]' and json_tree.value ='Accept'

2
docs/source/tools/trigger-service.rst
View File

@ -4,7 +4,7 @@
Trigger Service
###############
**WARNING:** The Trigger Service is an early access feature that is actively being designed and is *subject to breaking changes*. The documentation here at this time is limited to basic usage. As more features become available the documentation will be updated to include them. We welcome feedback about the Trigger Service on our `our issue tracker <https://github.com/digital-asset/daml/issues/new>`_ or `on our forum <https://discuss.daml.com>`_, or on `on Slack <https://slack.daml.com>`_.
The Trigger Service is currently an :doc:`Early Access Feature in Alpha status </support/status-definitions>`. At this time, the documentation is limited to basic usage. As more features become available the documentation will be updated to include them. We welcome feedback about the Trigger Service on our `our issue tracker <https://github.com/digital-asset/daml/issues/new>`_ or `on our forum <https://discuss.daml.com>`_, or on `on Slack <https://slack.daml.com>`_.
The `DAML triggers <../triggers/index.html#running-a-daml-trigger>`_ documentation shows a simple method using the ``daml trigger`` command to arrange for the execution of a single trigger. Using this method, a dedicated process is launched to host the trigger.

2
docs/source/tools/visual.rst
View File

@ -4,6 +4,8 @@
Visualizing DAML Contracts
##########################
Visualizing DAML Contracts is currently an :doc:`Early Access Feature in Labs status </support/status-definitions>`.
You can generate visual graphs for the contracts in your DAML project. To do this:
1. Install `Graphviz <http://www.graphviz.org/download/>`_.

3
docs/source/triggers/index.rst
View File

@ -9,8 +9,7 @@ DAML Triggers - Off-Ledger Automation in DAML
api/index
**WARNING:** DAML Triggers are an early access feature that is actively
being designed and is *subject to breaking changes*.
DAML Triggers are currently an :doc:`Early Access Feature in Alpha status </support/status-definitions>`.
We welcome feedback about DAML triggers on
`our issue tracker <https://github.com/digital-asset/daml/issues/new?milestone=DAML+Triggers>`_,
`our forum <https://discuss.daml.com>`_, or `on Slack <https://slack.daml.com>`_.

4
navigator/backend/src/main/scala/com/digitalasset/navigator/config/Arguments.scala
View File

@ -165,7 +165,7 @@ object Arguments {
.children(hostname, port)
cmd("console")
.text("start the console (early access)")
.text("Early Access (Labs). Start the console")
.action(
(_, arguments) =>
arguments.copy(
@ -176,7 +176,7 @@ object Arguments {
.children(hostname, port)
cmd("dump-graphql-schema")
.text("Dumps the full GraphQL schema to stdout")
.text("Early Access (Labs). Dumps the full GraphQL schema to stdout")
.action((_, arguments) => arguments.copy(command = DumpGraphQLSchema))
cmd("create-config")

2
release/sdk-config.yaml.tmpl
View File

@ -50,7 +50,7 @@ commands:
args: ["run-platform-jar", "--logback-config=sandbox-logback.xml", "sandbox"]
- name: sandbox-classic
path: daml-helper/daml-helper
desc: "Launch Sandbox Classic (the default Sandbox implementation for SDK <= 0.13.55)"
desc: "Deprecated. Launch Sandbox Classic (the default Sandbox implementation for SDK <= 0.13.55)"
args: ["run-platform-jar", "--logback-config=sandbox-logback.xml", "sandbox-classic"]
- name: navigator
path: daml-helper/daml-helper