digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 09:17:43 +03:00
Code Issues Projects Releases Wiki Activity

Improve support statement in docs (#7729)

Browse Source 
* Improve support statement in docs

CHANGELOG_BEGIN
CHANGELOG_END

* Incorporate feedback

* Rename the last minor version "terminal"

* Lowercase drivers

* Incorporate Derek's Feedback
This commit is contained in:
Bernhard Elsner 2020-10-27 16:52:39 +01:00 committed by GitHub
parent 1c8c6deef4
commit c20bd82f47
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 21 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,7 +4,7 @@
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>`.
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:
@ -17,7 +17,7 @@ A DAML Ledger is a server serving the
the :doc:`/concepts/ledger-model/index` and the
`DAML-LF specification <https://github.com/digital-asset/daml/blob/master/daml-lf/spec/daml-lf-1.rst>`_.
The DAML Integration Kit helps third-party ledger developers to
The DAML integration kit helps third-party ledger developers to
implement a DAML Ledger on top of their distributed ledger or database of
choice.
@ -44,7 +44,7 @@ and General Availability (GA) will come quite a bit later. The roadmap below exp
these different statuses, and what's missing to progress.
ALPHA (current status)
In the ALPHA status, the DAML Integration Kit is ready to be used by
In the ALPHA status, the DAML integration kit is ready to be used by
third-parties willing to accept the following caveats:
- The architecture includes everything required to run DAML Applications using the
@ -90,7 +90,7 @@ BETA
GA
For us GA (General Availability) means that there are several
production-ready DAML ledgers built using the DAML Integration Kit.
production-ready DAML ledgers built using the DAML integration kit.
We expect to reach GA in 2019.
Related links

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

@ -8,11 +8,11 @@ The DAML Ecosystem offers a number of forward and backward compatibility guarant
Application Portability
A DAML application should not depend on the underlying Database or DLT used by a DAML Network.
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.
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.
DAML Connect Upgradeability
@ -25,14 +25,14 @@ Application Portability and to some extent Network Upgradeability are achieved b
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.
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.
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.

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

@ -26,22 +26,22 @@ A high level view of the architecture of a DAML application or solution is helpf
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.
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.
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`.
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.
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
..................

11
docs/source/support/releases.rst
View File

@ -22,13 +22,20 @@ 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.
Regular snapshot releases are made every Wednesday, with additional snapshots released as needed. These releases contain DAML Connect 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.
Individual DAML drivers follow their own release cadence, using already released Integration Components as a dependency.
.. _support_duration:
Support Duration
----------------
Major versions will be supported for a minimum of one year after a subsequent Major version is release. Within a major version, only the latest minor version receives security and bug fixes.
.. _release-notes: