Skip to content

Release Process

Jump to bottom
Daniel Chao edited this page Nov 3, 2025 · 31 revisions

Prerequisites

  • CI main builds are green

  • If minor version:

    • Update docs/modules/release-notes/x.x.adoc with release notes

    • Submit PR targeting main branch and merge

  • If patch version

    • Update docs/modules/release-notes/pages/changelog.adoc with release notes

    • Update docs/modules/release-notes/pages/x.x.adoc with latest patch version

    • Update jbang-catalog.json with latest patch version

    • Submit PR targeting release/x.x branch and merge

Before Release

  1. apple/pkl-lang.org main branch (minor version), or release/x.x branch (patch version)

    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. Minor release:

    1. 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. pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java: update version annotation attribute

      5. jbang-catalog.json: update the version in the maven dependencies

      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

  3. Patch release:

    1. apple/pkl (release/x.x branch)

      1. gradle.properties: update version

      2. docs/antora.yml: update version

      3. docs/modules/ROOT/partials/component-attributes.adoc: update pkl-version-no-suffix

      4. pkl-core/src/main/java/org/pkl/core/runtime/VmLanguage.java: update version

      5. Update minPklVersion in all stdlib modules, and run gw spotlessApply

      6. Commit "Prepare x.y.z release" and push to upstream

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 monitor build of pkl-lang/pkl.

      1. (when releasing a minor version) create a branch, called release/x.y for the newly released version x.y off of the "Prepare x.y.z release" commit and push it

      2. (when releasing a patch version) push the commit to the existing release/x.y branch

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

  2. Wait until jars are available on Maven Central (takes about 5 minutes after CI build is complete)

    1. Trigger CI for pkl-package-docs again to build the stdlib docs

    2. Manually upload jpkl as a GitHub Releases asset (we should really upload this as part of CI but still need to fix our release build)

      1. Download pkl-cli-java from Maven Central, rename to jpkl

      2. Edit the release, add jpkl as an asset

  3. apple/pkl-evolution

    1. Merge any SPICEs whose changes have landed.

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 with the following contents:

        = Pkl 0.XX Release Notes
:version: 0.XX
:version-minor: 0.XX.0
:release-date: TBD

link:ROOT:partial$component-attributes.adoc[role=include]

Pkl {version} was released on {release-date}. +
[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#

The next release (0.XX) is scheduled for ???..
To see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].

Please send feedback and questions to https://github.com/apple/pkl/discussions[GitHub Discussions], or submit an issue on https://github.com/apple/pkl/issues/new[GitHub]. +

[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].
To get started, follow xref:pkl-cli:index.adoc#installation[Installation].#

== Highlights [small]#💖#

News you don't want to miss.

=== XXX

== Noteworthy [small]#🎶#

Ready when you need them.

=== XXX

== Breaking Changes [small]#💔#

Things to watch out for when upgrading.

=== XXX

== Miscellaneous [small]#🐸#

* XXX

== Bugs fixed [small]#🐜#

The following bugs have been fixed.

* XXX (https://github.com/apple/pkl/issues/XXX[XXX])

== Contributors [small]#🙏#

We would like to thank the contributors to this release (in alphabetical order):

* XXX

      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

    5. update Pkl version in pkl-jvm-examples

  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

  3. Create announcement in https://github.com/apple/pkl/discussions/categories/announcements with the title Pkl X.Y.Z is released and the following template:

Pkl X.Y.Z is released! This is a bugfix release.

For changes, take a look at our [release notes](https://pkl-lang.org/main/current/release-notes/changelog.html#release-X.Y.Z).
Clone this wiki locally