daml/release/RELEASE.md

# 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:

1. 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.

2. 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.

4. 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:
>
> 1. First you should clone the [ad-hoc] repository and then enter the
>    cloned repo.
> 2. 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](https://go.microsoft.com/fwlink/?linkid=868963).
>
> 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.

1. 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](https://github.com/digital-asset/daml/releases) page). The
   automated message on `#team-daml` should contain a direct link to the
   installer.

1. Run `daml version --assistant=yes` and verify that the new version is
   selected as the assistant version and the default version for new projects.

1. Run `daml new myproject` to create a new project and switch to it using
   `cd myproject`.

1. Run `daml start`. Wait for the yellow message.

1. Kill `daml start` with `Ctrl-C` (followed by "y" because Windows).

1. 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.

1. Add `+` at the end of line 26 after `(PartyIdHint "Alice")` and verify that
   you get an error on line 27.

1. On the [assembly] PR, add the comment:

   > Manual tests passed on Windows.

1. Destroy your Windows VM.


### Linux/macOS

1. Run:

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

1. Make sure you have the prerequisites for running the tests:

   - [Visual Studio Code, Java-SDK](https://docs.daml.com/getting-started/installation.html)
   - [Maven](https://maven.apache.org)

1. Run `daml version --assistant=yes` and verify that the new version is
   selected as the assistant version and the default version for new projects.

1. Create a new project with `daml new quickstart --template quickstart-java`
   and switch to it using `cd quickstart`.

1. Verify the new version is specified in `daml.yaml` as the `sdk-version`.

1. Run `daml start`, and wait for the yellow line.

1. Kill `daml start` using `Ctrl-C`.

1. Run `daml build`.

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

   1. In Terminal 1, run:

      ```
      daml sandbox --port 6865
      ```

   1. In Terminal 2, run each of the following:

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

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

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

   1. In Terminal 3, run:

      ```sh
      cat output.json
      ```

      and verify that the output looks like this:

      ```json
      ["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.

   1. Still in Terminal 3, run:

      ```sh
      curl http://localhost:8080/iou` returns:
      ```

      and verify that the output looks like:

      ```json
      {"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.

1. Kill the processes running in Terminals 1 and 2 using CTRL-C.

1. 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.)

1. Open `daml/Main.daml`.

1. Click on `Script results` above `initialize` (in the code) and wait for the
   script results to appear.

1. Add `+` at the end of line 14, after `(PartyIdHint "Alice")` and confirm you
   get an  error in line 15.

1. Add `1` after the `+` and confirm you get a type error in line 14, which
   says that `Script Party` does not match `Int`.

1. Delete the `+1` and the `e` in the second `"Alice"` and verify that the
   script results are updated to the misspelled name.

1. Right click on `eurBank` in line 28 and verify that "Go to Definition" takes
   you to the definition in line 17.

1. 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
> ```

1. On the [assembly] PR, add the comment:

   > Manual tests passed on [Linux/macOS].

   specifying which platform you tested on.

### Wrap up

1. 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.

1. 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:

1. 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!

[Remmina]: https://remmina.org
[`LATEST`]: https://github.com/digital-asset/daml/blob/main/LATEST
[`NIGHTLY_PREFIX`]: https://github.com/digital-asset/daml/blob/main/NIGHTLY_PREFIX
[`release.sh`]: https://github.com/digital-asset/daml/blob/main/release.sh
[ad-hoc]: https://github.com/DACH-NY/daml-language-ad-hoc
[assembly]: https://github.com/DACH-NY/assembly
[daml]: https://github.com/digital-asset/daml
[release notes]: https://daml.com/release-notes/
[releases page]: https://github.com/digital-asset/daml/releases