Making a Release

Daml releases are made in the assembly repo by combining the releases of individual components. SDK releases are triggered in this repo by modifying the LATEST file.

Release Branches

In this repo, the release branch for minor version A.B must be named release/A.B.x, e.g. release/2.7.x.

Note: This also means you should not create branches with those (or similar) names if they are not meant to be release branches.

Note: In most cases work should not be done on a release branch directly. Changes should go into the main branch first, and then be backported to the release branch.

When you create the release branch in the daml repo, make a PR to main bumping NIGHTLY_PREFIX accordingly. You may also want to bump it in the release branch (e.g. from 2.8.0 to 2.8.1).

Creating an SDK Release

The steps to create a release are:

In the daml repo, edit the LATEST file. The format of that file is a commit sha of the code you want to release (at this point typically the tip of the release branch), the version number you want to attribute to the build, and the words SPLIT_RELEASE (for historical reason dating to pre-2.0 days). For a release candidate, one can generate a snapshot version string using the release.sh script. For example, to create a PR for a 2.0.0 release candidate:
```
$ git fetch
$ ./release.sh snapshot origin/release/2.0.x 2.0.0
```
You should put that line in the file in order to preserve semver ordering, and overwrite any existing snapshot with the same prefix.

Stable releases should use the same code as the last RC, so instead of adding a new line you should simply remove the -snapshot.* part of the version string on the appropriate line of the LATEST file.
Make a PR targeting the main branch with just that one line added, touching no other file. Add the Standard-Change label to that PR.
When the PR is merged, the build of the corresponding commit on main will create a "split release" bundle and push it to Artifactory. It should notify on #team-canton on Slack.

Daily Snapshots

CI will automatically create a daily snapshot using the tip of the main branch. This does not appear in the LATEST file but is otherwise identical to a snapshot one would have created on the same commit using the steps in the previous section.

Testing

This testing procedure starts once the release is listed on the releases page.

In the following notes, we assume that $VERSION contains the full version tag for the release you are testing - in other words, the full version as recorded on the Slack #team-daml message that is generated by the assembly repo. Remember that these steps are for testing the SDK within a Daml release.

Windows

Tips for Windows testing in an ad-hoc machine

If you are part of the release rotation, you should b able to create Windows VMs through the ad-hoc project. If you don't have permission, follow these steps:

First you should clone the ad-hoc repository and then enter the cloned repo.

Edit tf/main.tf and add your username to the members field of the google_project_iam_binding.machine_managers resource. Generate and submit a PR with these changes. Once the PR has been accepted, you should now have permission to create GCP compute instances.

Assuming direnv is installed, entering the daml-language-ad-hoc project directory will be sufficient to configure and install the extra software (e.g. the GCP SDK) required for your environment. Note that this could take a few minutes.

A new GCP windows instance can be created by running ./ad-hoc.sh temp windows inside the daml-language-ad-hoc project. This command prints IP address, username and password for the created Windows VM. Save this output. You will need this information later when you create an RDP connection.

‼️ After starting, it's going to take some time for the machine to be configured (see notes below).

Before you may connect to this windows instance, you need to ensure that the VPN is connected. On macOS you can do this by selecting the preconfigured Connect GCP Frankfurt full tunnel VPN profile.

If you're on a Mac, you can use Microsoft Remote Desktop to connect. This can be installed via the Mac App Store or directly here.

If you're on Linux, you can use Remmina.

Remmina notes: when creating an RDP connection, you may want to specify custom resolution. The default setting is to use client resolution. You may notice a failure due to color depth settings. You can adjust those in the settings panel right below the resolution settings.

The ad-hoc machines take a bit of time to be available after being reported as created, so be patient for a bit if your first connection attempt(s) fail. Also note that the machine will accept connections before it is fully initialized; initialization is finished when the Firefox icon appears on the Desktop.

Once the Windows machine is up and running, use Firefox (in Windows) to download and install daml-sdk-$VERSION-windows.exe from the releases page (please ensure $VERSION is expanded correctly!.

Ad-hoc machines come with VSCode and OpenJDK preinstalled.

NOTE 2: After logging in, it takes some time for the machine to be configured. The script that installs Firefox, VSCode and OpenJDK runs once the machine is available for login. The software you need should appear within about 10 minutes (an easy way to check is to try to open D:\ , as this volume is created after all the software is installed).

All the commands mentioned in this testing section can be run from a simple DOS prompt (start menu -> type cmd.exe -> click "Command prompt").

At the end of your Windows testing session, please be sure to terminate the GCP instance by running ./ad-hoc.sh destroy $ID. Here $ID is the identity for your GCP instance - this is printed when you create your Windows instance.

Install the new SDK using the installer on the releases page. This will typically be the asset named daml-sdk-$VERSION-windows.exe (located on the DAML releases page). The automated message on #team-daml should contain a direct link to the installer.
Run daml version --assistant=yes and verify that the new version is selected as the assistant version and the default version for new projects.
Run daml new myproject to create a new project and switch to it using cd myproject.
Run daml start. Wait for the yellow message.
Kill daml start with Ctrl-C (followed by "y" because Windows).
Run daml studio --replace=always and open daml/Main.daml. Verify that there is a Script results link on top of the script, click on it, and verify that the script result appears within 30 seconds.
Add + at the end of line 26 after (PartyIdHint "Alice") and verify that you get an error on line 27.
On the assembly PR, add the comment:

Manual tests passed on Windows.
Destroy your Windows VM.

Linux/macOS

Run:

curl -sSL https://get.daml.com/ | sh -s "$VERSION"

Make sure you have the prerequisites for running the tests:
- Visual Studio Code, Java-SDK
- Maven
Run daml version --assistant=yes and verify that the new version is selected as the assistant version and the default version for new projects.
Create a new project with daml new quickstart --template quickstart-java and switch to it using cd quickstart.
Verify the new version is specified in daml.yaml as the sdk-version.
Run daml start, and wait for the yellow line.
Kill daml start using Ctrl-C.
Run daml build.

In 3 separate terminals (each being in the quickstart-java project directory), run:

In Terminal 1, run:
```
daml sandbox --port 6865
```

In Terminal 2, run each of the following:

daml ledger upload-dar --host localhost --port 6865 .daml/dist/quickstart-0.0.1.dar

daml script --ledger-host localhost --ledger-port 6865 --dar .daml/dist/quickstart-0.0.1.dar --script-name Main:initialize --output-file output.json

daml codegen java && mvn compile exec:java@run-quickstart -Dparty=$(cat output.json | sed 's/\[\"//' | sed 's/".*//')

In Terminal 3, run:
```
cat output.json
```
and verify that the output looks like this:
```
["Alice::NAMESPACE", "EUR_Bank::NAMESPACE"]
```
where NAMESPACE is some randomly generated series of hex digits.

Note that this step scrapes the Alice::NAMESPACE party name from the output.json produced in the previous steps.

Still in Terminal 3, run:

curl http://localhost:8080/iou

and verify that the output looks like:

{"0":{"issuer":"EUR_Bank::NAMESPACE","owner":"Alice::NAMESPACE","currency":"EUR","amount":100.0000000000,"observers":[]}}

where NAMESPACE is the same series of hex digits as in the previous step.

Kill the processes running in Terminals 1 and 2 using CTRL-C.
Run daml studio --replace=always. This should open VSCode and trigger the Daml extension that's bundled with the new SDK version. (The new VSCode extension will not be in the marketplace at this point.)
Open daml/Main.daml.
Click on Script results above initialize (in the code) and wait for the script results to appear.
Add + at the end of line 14, after (PartyIdHint "Alice") and confirm you get an error in line 15.
Add 1 after the + and confirm you get a type error in line 14, which says that Script Party does not match Int.
Delete the +1 and the e in the second "Alice" and verify that the script results are updated to the misspelled name.
Right click on eurBank in line 28 and verify that "Go to Definition" takes you to the definition in line 17.
Close VS Code.

Note: when running daml studio --replace=always, you force the installation of the VSCode extension bundled with the Daml SDK, and disable the auto-upgrade mechanism in VSCode. To instruct VSCode to go back to the published version of the extension, including auto-upgrades, you can run
daml studio --replace=published

On the assembly PR, add the comment:

Manual tests passed on [Linux/macOS].

specifying which platform you tested on.

Wrap up

If the release is bad, ask Gary to delete the release from the releases page. Mention why it is bad as a comment on your PR, and stop the process here.

Note that the Standard-Change label must remain on the PR, even if the release has failed.
Announce the release on #product-daml on Slack. For a stable release, direct people to the release blog post. If there were any errors during testing, but we decided to keep the release anyway, report those on the PR and include a link to the PR in the announcement.

For a stable release, you need to additionally:

Go to the releases page and remove the prerelease marker on the release. Also change the text to See [the release notes blog]() for details. adding in the direct link to this version's release notes.

Thanks for making a release!

12 KiB Raw Blame History