Release Process

Prerequisites

• CI main builds are green

• release notes and changelog update have been merged

Before Release

1. apple/pkl-lang.github.io (main branch)

   1. run gw validateLocalSite.

      1. It’s okay if there are errors like Unexpected HTTP status code 404 for external link https://pkl-lang.org/pkl/<new-version>-dev/…​; because we do not publish docs for unreleased versions of Pkl.

   2. do a quick manual check of the generated site (esp. the release notes)

2. apple/pkl (main branch)

   1. gradle.properties: update version as necessary

   2. docs/antora.yml: update version (no suffix for release, -rc.n suffix for RC) and prerelease properties (true → false)

   3. docs/modules/ROOT/partials/component-attributes.adoc: update top two properties

   4. docs/modules/release-notes/<current>.adoc: update :version-minor as necessary

   5. pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java: update version annotation attribute

   6. to be on the safe side, do a file search for latest dev version and replace as necessary

   7. commit "Prepare x.y.z release" but do not push yet

      1. avoids issue where docs build fails because main branch and tag have same Antora component version

Perform/Validate Release

1. apple/pkl

   1. run git tag -a x.y.z -m "Release version x.y.z"

   2. push to upstream (git push upstream refs/tags/x.y.z) and wait for pkl-lang/pkl release build to finish

   3. once CI build is complete, do a quick manual check of https://pkl-lang.org/main/current

2. apple/pkl-jvm-examples (main branch, if new minor version)

   1. update Pkl version (search and replace)

   2. make sure that gw build succeeds and push to upstream

After Release

1. If new minor release:

   1. apple/pkl (main branch)

      1. docs/antora.yml: Update version (use -dev suffix) and prerelease properties (false → true)

      2. docs/modules/ROOT/partials/component-attributes.adoc: update top two properties

   2. gradle.properties: set version to next dev version (do not use -dev or -SNAPSHOT suffix)

      1. pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java: update version annotation attribute (use -dev suffix)

      2. stdlib/: update minPklVersion of all stdlib modules (do not use -dev suffix)

      3. changelog.adoc: add the next release version and date

      4. create a new release notes file in docs/modules/release-notes/pages/<next-version>.adoc

      5. update docs/nav.adoc and docs/modules/release-notes/pages/index.adoc to link to the next version

      6. to be on the safe side, do a file search for current release version and replace as necessary

      7. commit "Start next dev iteration", and push to upstream

   3. release new versions of pkl-spring, and pkl-intellij (update to latest version of Pkl)

   4. release new versions of pkl-vscode, pkl-neovim if grammar has changed

2. If new patch release

   1. apple/pkl (main branch)

      1. Cherry-pick commit that adds release notes for recently released patch to CHANGELOG

      2. Submit PR and merge into main