digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-11-10 10:46:11 +03:00
Code Issues Projects Releases Wiki Activity
37d74287f1
daml/release/RELEASE.md
Gary Verhaegen 8a96093158
update release instructions (#7118) 
I tried to cut through most of the noise, and updated for the new "don't
copy release notes three times" idea.

CHANGELOG_BEGIN
CHANGELOG_END
2020-08-13 15:36:32 +02:00

12 KiB
Raw Blame History

Making a Release

For snapshot releases, skip the steps marked [STABLE]. For stable releases, skip the steps marked [SNAPSHOT].

Valid commits for a release should come from either the master branch or one of the support release/a.b.x branches (e.g. release/1.0.x branch is for patches we backport to the 1.0 release branch).

Important

: If the release fails, please delete it from the releases page and write how it failed on the PR.

  1. [STABLE] Go through the checklist before making the release. Note that the checklist is not available publicly.

  2. [STABLE] Stable releases are promoted from snapshot releases. Open a PR that changes the LATEST file to remove the -snapshot suffix on the corresponding snapshot, and add the Standard-Change label.

  3. [SNAPSHOT] For most snapshot releases, the PR is created automatically. Double-check the snapshot version: it may need incrementing. Ask on Slack (#team-daml) if you're not sure.

    If you are manually creating the PR for an out-of-schedule snapshot, start from latest master and run

    ./release.sh snapshot <sha> <prefix>

    for example:

    $ ./release.sh snapshot cc880e2 0.1.2
cc880e290b2311d0bf05d58c7d75c50784c0131c 0.1.2-snapshot.20200513.4174.0.cc880e29

    Then open a PR with the changed LATEST file, and add the Standard-Change label.

  4. Once the PR has built, check that it was considered a release build by our CI. You can do that by looking at the output of the check_for_release build step.

  5. [STABLE] The PR must be approved by a team lead before merging. As of this writing (2020-08-13), @bame-da, @gerolf-da, @cocreature or @hurryabit.

  6. Merge the PR and wait for the corresponding master build to finish. You will be notified on #team-daml.

  7. On Windows, install the new SDK using the installer on https://github.com/digital-asset/daml/releases.

    On macOS/Linux:

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

    where $VERSION is the full version tag of the new release you are making, i.e. the second column of the LATEST file.

  8. Prerequisites for running the tests:

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

  10. Tests for the getting started guide (macOS/Linux and Windows). Note: if using a remote Windows VM and an RDP client that supports copy/paste, you can run through this on both Windows and your local unix in parallel fairly easily.

    1. For these steps you will need the documentation for the release you are about to make. Documentation is published at every hour so if you wait for a bit you can go to https://docs.daml.com/$VERSION/getting-started/index.html. Otherwise, check out the commit that you are referencing in the LATEST file and build documentation locally via ./docs/scripts/preview.sh.

    2. To open a new terminal on Windows: Start menu -> type "cmd" -> click cmd.exe.

    3. daml new create-daml-app --template create-daml-app

    4. cd create-daml-app

      1. daml build

      2. daml codegen js .daml/dist/create-daml-app-0.1.0.dar -o daml.js

      3. daml start

    5. In a new terminal, from the ui folder:

      1. yarn install

      2. yarn start

    6. Open two browser windows (you want to see them simultaneously ideally) at localhost:3000.

    7. Log in as Alice in the first window, log in as Bob in the second window.

    8. Make Alice follow Bob. Verify that Bob appears in the list of users Alice is following. Verify in the other browser window that Alice shows up in Bob’s network.

    9. Make Bob follow Alice. Verify that Alice appears in the list of users Bob is following. Verify in the other browser window that Bob shows up in Alice’s network.

    10. Kill the daml start process and the yarn start process.

    11. Open the your first feature section of the GSG, e.g., from https://docs.daml.com/$VERSION/getting-started/first-feature.html if you did not build docs locally.

    12. Run daml studio --replace=always from the project root directory and open User.daml.

    13. Copy the Message template from the documentation to the end of User.daml.

    14. Copy the SendMessage choice from the documentation to the User template below the Follow choice.

    15. Close VSCode.

    16. Run daml build && daml codegen js .daml/dist/create-daml-app-0.1.0.dar -o daml.js.

    17. From the ui directory run yarn install --force --frozen-lockfile.

    18. Run code . from the project root directory (the extension is already installed, no need to use daml studio).

    19. Create MessageList.tsx, MessageEdit.tsx and modify MainView.tsx as described in the documentation.

    20. Verify that you do not see errors in the typescript code in VSCode.

    21. Close VSCode.

    22. Run daml start from the project root directory.

    23. In a separate terminal, run yarn start from the ui directory.

    24. As before, open two browser windows at localhost:3000 and log in as Alice and Bob.

    25. Make Alice follow Bob.

    26. From Bob, select Alice in the Select a follower drop down, insert hi alice in the message field and click on Send.

    27. Verify that Alice has received the message in the other window.

    28. Make Bob follow Alice.

    29. From Alice, select Bob in the drop down insert hi bob in the message field and click on Send.

    30. Verify that Bob has received the message in the other window.

    31. You can now close both browser windows and both running processes (daml start and yarn start).

    32. Don't forget to run this on the other platform! E.g. if you just ran through on Linux or macOS, you still need to run on Windows, and vice versa.

  11. Tests for quickstart-java (Linux/macOS)

    While this is no longer the default getting started guide we still test it for now since it covers things not covered by the new GSG (Navigator, scenarios, Maven artifacts, …)

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

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

    3. Run daml start. Your browser should be opened automatically at http://localhost:7500. Login as Alice and verify that there is 1 contract and 3 templates. Close the tab and kill daml start using Ctrl-C.

    4. Run daml build.

    5. In 3 separate terminals (since each command blocks), run:

      1. daml sandbox --wall-clock-time --port 6865 .daml/dist/quickstart-0.0.1.dar
      2. daml script --dar .daml/dist/quickstart-0.0.1.dar --script-name Setup:initialize --ledger-host localhost --ledger-port 6865 --wall-clock-time && daml navigator server localhost 6865 --port 7500
      3. daml codegen java && mvn compile exec:java@run-quickstart

      Note: It takes some time for our artifacts to be available on Maven Central. If you try running the last command before the artifacts are available, you will get a "not found" error. Trying to build again in the next 24 hours will result in:

      Failure to find ... was cached in the local repository, resolution will not be reattempted until the update interval of digitalasset-releases has elapsed or updates are forced

      This is Maven telling you it has locally cached that "not found" result and will consider it valid for 24h. To bypass that and force Maven to try the network call again, add a -U option, as in mvn compile exec:java@run-quickstart -U. Note that this is required to bypass your local cache of the failure; it will not be required for a user trying to run the quickstart after the artifacts have been published.

    6. Point your browser to http://localhost:7500, login as Alice and verify that there is 1 contract, 3 templates and 1 owned IOU.

    7. Check that curl http://localhost:8080/iou returns:

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

    8. Kill all processes.

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

    10. Open daml/Main.daml.

    11. Click on Scenario results above setup and wait for the scenario results to appear.

    12. Add + at the end of line 12, after "Alice" and confirm you get an error in line 13.

    13. Add 1 after the + and confirm you get an error in line 12.

    14. Delete the +1 and the e in Alice and verify that the scenario results are updated to the misspelled name.

    15. Right click on eurBank in line 18 and verify that "Go to Definition" takes you to the definition in line 15.

    16. Close all files.

  12. On your PR, add the comment:

    Manual tests passed on [Linux/macOS].

    specifying which platform you tested on.

  13. Run through the following test plan on Windows. This is slightly shortened to make testing faster and since most issues are not platform specific.

    1. Run daml new quickstart to create a new project and switch to it using cd quickstart.
    2. Run daml start.
    3. Open your browser at http://localhost:7500, verify that you can login as Alice and there is one template and one contract.
    4. Kill daml start with Ctrl-C.
    5. Run daml studio --replace=always and open daml/Main.daml. Verify that the scenario result appears within 30 seconds.
    6. Add + at the end of line 23 after "Alice" and verify that you get an error.

  14. On your PR, add the comment:

    Manual tests passed on Windows.

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

  16. Announce the release on the relevant internal Slack channels (#product-daml, #team-daml). For a stable release, direct people to the release blog post; for a prerelease, you can include the raw output of the unreleased.sh script.

  17. [STABLE] 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. Documentation for this release will be added to docs.daml.com on the next hour.

  18. [STABLE] Coordinate with product (& marketing) for the relevant public announcements (public Slack, Twitter, etc.).

  19. [STABLE] Documentation is published automatically once the release is public on GitHub, though this runs on an hourly cron.

Thanks for making a release!