From ff03a91e5fe7352ef4703fea5e171c51222dc6bd Mon Sep 17 00:00:00 2001 From: Jen Basch Date: Mon, 27 Oct 2025 17:05:59 -0700 Subject: [PATCH 1/4] Add release notes for 0.30 --- .../ROOT/partials/component-attributes.adoc | 2 + .../language-reference/pages/index.adoc | 4 +- docs/modules/release-notes/pages/0.30.adoc | 154 ++++++++++++++++-- .../release-notes/pages/changelog.adoc | 4 +- 4 files changed, 150 insertions(+), 14 deletions(-) diff --git a/docs/modules/ROOT/partials/component-attributes.adoc b/docs/modules/ROOT/partials/component-attributes.adoc index e31ca65e9..58dd48507 100644 --- a/docs/modules/ROOT/partials/component-attributes.adoc +++ b/docs/modules/ROOT/partials/component-attributes.adoc @@ -131,7 +131,9 @@ endif::[] :uri-stdlib-Class: {uri-stdlib-baseModule}/Class :uri-stdlib-TypeAlias: {uri-stdlib-baseModule}/TypeAlias :uri-stdlib-Deprecated: {uri-stdlib-baseModule}/Deprecated +:uri-stdlib-BaseValueRenderer: {uri-stdlib-baseModule}/BaseValueRenderer :uri-stdlib-ValueRenderer: {uri-stdlib-baseModule}/ValueRenderer +:uri-stdlib-BytesRenderer: {uri-stdlib-baseModule}/BytesRenderer :uri-stdlib-PcfRenderer-converters: {uri-stdlib-baseModule}/PcfRenderer#converters :uri-stdlib-Function: {uri-stdlib-baseModule}/Function :uri-stdlib-Function0: {uri-stdlib-baseModule}/Function0 diff --git a/docs/modules/language-reference/pages/index.adoc b/docs/modules/language-reference/pages/index.adoc index 2a6c94b73..139e47e49 100644 --- a/docs/modules/language-reference/pages/index.adoc +++ b/docs/modules/language-reference/pages/index.adoc @@ -1423,7 +1423,7 @@ The recipe for transforming a listing is: . Transform the list using ``List``'s link:{uri-stdlib-List}[rich API]. . If necessary, convert the list back to a listing. -TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer]. +TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer]. Because most value renderers treat lists the same as listings, it is often not necessary to convert back to a listing. Equipped with this knowledge, let's try to accomplish our objective: @@ -1803,7 +1803,7 @@ The recipe for transforming a mapping is: . Transform the map using ``Map``'s link:{uri-stdlib-Map}[rich API]. . If necessary, convert the map back to a mapping. -TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer]. +TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer]. As most value renderers treat maps the same as mappings, it is often not necessary to convert back to a mapping. Equipped with this knowledge, let's try to accomplish our objective: diff --git a/docs/modules/release-notes/pages/0.30.adoc b/docs/modules/release-notes/pages/0.30.adoc index 20e60e43c..62a7682f3 100644 --- a/docs/modules/release-notes/pages/0.30.adoc +++ b/docs/modules/release-notes/pages/0.30.adoc @@ -1,14 +1,14 @@ = Pkl 0.30 Release Notes :version: 0.30 :version-minor: 0.30.0 -:release-date: TBD +:release-date: October 30th, 2025 -link:ROOT:partial$component-attributes.adoc[role=include] +include::ROOT:partial$component-attributes.adoc[] 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 ???.. +The next release (0.31) is scheduled for January 2026. 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]. + @@ -18,15 +18,134 @@ To get started, follow xref:pkl-cli:index.adoc#installation[Installation].# == Highlights [small]#💖# -News you don't want to miss. +[[formatter]] +=== Canonical Formatter -=== XXX +TODO + +https://github.com/apple/pkl/pull/1107 +https://github.com/apple/pkl/pull/1208 +https://github.com/apple/pkl/pull/1211 +https://github.com/apple/pkl/pull/1215 +https://github.com/apple/pkl/pull/1217 +https://github.com/apple/pkl/pull/1235 +https://github.com/apple/pkl/pull/1246 +https://github.com/apple/pkl/pull/1247 +https://github.com/apple/pkl/pull/1252 +https://github.com/apple/pkl/pull/1260 + +[IMPORTANT] +==== +By default, `pkl format` will add <> to formatted code. +The resulting code will be compatible only with Pkl 0.30 and later. +When code compatibility with older Pkl releases is required the CLI must be invoked with `--grammar-version 1` to prevent adding trailing commas. +This is especialy important for semantically versioned package, as increasing the minimum required Pkl version is a breaking change and entails incrementing the package's major version. +==== + +To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0014-canonical-formatter.adoc[SPICE-0014]. + +[[binary-renderer-parser]] +=== `pkl-binary` Renderer and Parser + +TODO + +https://github.com/apple/pkl/pull/1203 +https://github.com/apple/pkl/pull/1250 + +To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021]. == Noteworthy [small]#🎶# -Ready when you need them. +[[trailing-commas]] +=== Trailing Commas + +Pkl's grammar has been updated to allow including a comma following the final item of comma-separated syntax elements (https://github.com/apple/pkl/pull/1137[#1137]). +These syntax elements are affected: + +[source,pkl] +---- +function add(bar, baz,) = bar + baz // <1> +foo = add(1, 2,) // <2> +bar: Mapping // <3> +class MyMapping {} // <4> +baz: Listing(!isEmpty, isDistinct,) // <5> +quz: (String, Int,) -> Boolean // <6> +quux: Mixin = new { parent, -> // <7> + corge = 5 +} +---- +<1> Function parameter lists in method definitions. +<2> Argument lists in method calls. +<3> Type argument lists in declared type names. +<4> Type parameter lists in class headers (standard library only). +<5> Type constraint lists. +<6> Function type parameter lists in function type annotations. +<7> Object body parameter lists in syntax-sugared lambdas. + +To learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0019-trailing-commas.adoc[SPICE-0019]. + +=== Pretty-printed traces + +TODO + +https://github.com/apple/pkl/pull/1100 +https://github.com/apple/pkl/pull/1227 +https://github.com/apple/pkl/pull/1230 + +=== pkldoc data model revisions + +TODO + +https://github.com/apple/pkl/pull/1169 +https://github.com/apple/pkl/pull/1224 +https://github.com/apple/pkl/pull/1241 +https://github.com/apple/pkl/pull/1242 + +=== Java API changes + +==== New classes + +New classes are introduced to the Java API. + +* `org.pkl.core.PklBinaryDecoder` + +==== New methods + +New methods are introduced to the Java API. + +* `org.pkl.core.Evaluator.evaluateExpressionPklBinary` +* `org.pkl.core.EvaluatorBuilder.setTraceMode` +* `org.pkl.core.EvaluatorBuilder.getTraceMode` + +=== Standard Library changes + +New modules, properties, methods, classes and typealiases have been added to the standard library (https://github.com/apple/pkl/pull/1106[#1106]). + +==== Additions to `pkl:base` + +* {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`] +* {uri-stdlib-ValueRenderer}[`ValueRenderer`] (now a subclass of {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`]) +* {uri-stdlib-BytesRenderer}[`BytesRenderer`] +* {uri-stdlib-baseModule}/RenderDirective#bytes[`RenderDirective.bytes`] + +==== Additions to `pkl:EvaluatorSettings` + +* {uri-stdlib-evaluatorSettingsModule}#traceMode[`traceMode`] + +=== Additions to `pkl:reflect` + +* {uri-stdlib-reflectModule}/Class#allMethods[`Class.allMethods`] +* {uri-stdlib-reflectModule}/Class#allProperties[`Class.allProperties`] +* {uri-stdlib-reflectModule}/Propterty#allAnnotations[`Propterty.allAnnotations`] +* {uri-stdlib-reflectModule}/Propterty#allModifiers[`Propterty.allModifiers`] + +=== `pkl` CLI changes + +==== REPL interrupt handling + +TODO -=== XXX +https://github.com/apple/pkl/pull/1188 == Breaking Changes [small]#💔# @@ -34,20 +153,33 @@ Things to watch out for when upgrading. === Minimum Kotlin version bump -For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/900[#900]). +For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/1232[#1232]). == Miscellaneous [small]#🐸# -* XXX +* Dependency updates (https://github.com/apple/pkl/pull/1184[#1184], https://github.com/apple/pkl/pull/1225[#1225], https://github.com/apple/pkl/pull/1226[#1226], https://github.com/apple/pkl/pull/1228[#1228]). +* Enforce Pkl formatting of stdlib (https://github.com/apple/pkl/pull/1236[#1236], https://github.com/apple/pkl/pull/1253[#1253], https://github.com/apple/pkl/pull/1258[#1258]). +* Add internal IntelliJ plugin that's meant to assist with development of the Pkl codebase itself (https://github.com/apple/pkl/pull/1248[#1248]). +* Update CircleCI macOS instance type and Xcode version (https://github.com/apple/pkl/pull/1243[#1243], https://github.com/apple/pkl/pull/1244[#1244]). +* Disable multi-jdk testing when running on Windows ARM (https://github.com/apple/pkl/pull/1223[#1223]). +* Refine documentation for class `Any` (https://github.com/apple/pkl/pull/1194[#1194]). == Bugs fixed [small]#🐜# The following bugs have been fixed. -* XXX (https://github.com/apple/pkl/issues/XXX[XXX]) +* Fix error message when reading a resource/module past root dir (https://github.com/apple/pkl/pull/1234[#1234]). +* Fix publication of pkl-config-kotlin after Gradle 9.1 upgrade (https://github.com/apple/pkl/pull/1240[#1240]). +* Fix Lexer EOF sentinel collision with valid Unicode code points (https://github.com/apple/pkl/pull/1251[#1251]). +* Fix fallback certificates not working in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1198]). == Contributors [small]#🙏# We would like to thank the contributors to this release (in alphabetical order): -* XXX +* https://github.com/bioball[@bioball] +* https://github.com/HT154[@HT154] +* https://github.com/netvl[@netvl] +* https://github.com/spyoungtech[@spyoungtech] +* https://github.com/srueg[@srueg] +* https://github.com/stackoverflow[@stackoverflow] diff --git a/docs/modules/release-notes/pages/changelog.adoc b/docs/modules/release-notes/pages/changelog.adoc index 16f8f0c8c..7fde1a3c7 100644 --- a/docs/modules/release-notes/pages/changelog.adoc +++ b/docs/modules/release-notes/pages/changelog.adoc @@ -2,7 +2,9 @@ include::ROOT:partial$component-attributes.adoc[] [[release-0.30.0]] -== 0.30.0 (TBD) +== 0.30.0 (2025-10-30) + +xref:0.30.adoc[Release notes] [[release-0.29.1]] == 0.29.1 (2025-08-27) From 0c2dad2aacca760ee64a81d9361aa0f74f407108 Mon Sep 17 00:00:00 2001 From: Dan Chao Date: Tue, 28 Oct 2025 17:32:36 -0700 Subject: [PATCH 2/4] continued WIP on changelog --- .../ROOT/partials/component-attributes.adoc | 1 + .../pkl-cli/partials/cli-common-options.adoc | 8 + docs/modules/release-notes/pages/0.29.adoc | 1 + docs/modules/release-notes/pages/0.30.adoc | 274 ++++++++++++++---- 4 files changed, 225 insertions(+), 59 deletions(-) diff --git a/docs/modules/ROOT/partials/component-attributes.adoc b/docs/modules/ROOT/partials/component-attributes.adoc index 58dd48507..47b640282 100644 --- a/docs/modules/ROOT/partials/component-attributes.adoc +++ b/docs/modules/ROOT/partials/component-attributes.adoc @@ -74,6 +74,7 @@ endif::[] :uri-stdlib-mathModule: {uri-pkl-stdlib-docs}/math :uri-stdlib-xmlModule: {uri-pkl-stdlib-docs}/xml :uri-stdlib-protobufModule: {uri-pkl-stdlib-docs}/protobuf +:uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary :uri-stdlib-evaluatorSettingsModule: {uri-pkl-stdlib-docs}/EvaluatorSettings :uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary :uri-stdlib-evaluatorSettingsHttpClass: {uri-stdlib-evaluatorSettingsModule}/Http diff --git a/docs/modules/pkl-cli/partials/cli-common-options.adoc b/docs/modules/pkl-cli/partials/cli-common-options.adoc index 8f2b84409..5b9a3c891 100644 --- a/docs/modules/pkl-cli/partials/cli-common-options.adoc +++ b/docs/modules/pkl-cli/partials/cli-common-options.adoc @@ -163,3 +163,11 @@ The left-hand side describes the source prefix, and the right-hand describes the This option is commonly used to enable package mirroring. The above example will rewrite URL `\https://pkg.pkl-lang.org/pkl-k8s/k8s@1.0.0` to `\https://my.internal.mirror/pkl-k8s/k8s@1.0.0`. ==== + +.--trace-mode +[%collapsible] +==== +Default: `compact` + +Specifies how `trace()` output is formatted. +Possible options are `compact` and `pretty`. +==== diff --git a/docs/modules/release-notes/pages/0.29.adoc b/docs/modules/release-notes/pages/0.29.adoc index 2f424f064..d3ea4e461 100644 --- a/docs/modules/release-notes/pages/0.29.adoc +++ b/docs/modules/release-notes/pages/0.29.adoc @@ -342,6 +342,7 @@ In Pkl 0.29, it is an error to load a module or resource with an opaque `file:` NOTE: To import or read a relative path, omit `file:` from the import string. For example, `import("foo/bar.txt")` instead of `import("file:foo/bar.txt")`. +[[new-base-module-names]] === New base module names: `Bytes` and `Charset` Two new names are introduced to the base module: `Bytes` and `Charset`. diff --git a/docs/modules/release-notes/pages/0.30.adoc b/docs/modules/release-notes/pages/0.30.adoc index 62a7682f3..2241e1153 100644 --- a/docs/modules/release-notes/pages/0.30.adoc +++ b/docs/modules/release-notes/pages/0.30.adoc @@ -8,7 +8,9 @@ include::ROOT:partial$component-attributes.adoc[] Pkl {version} was released on {release-date}. + [.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])# -The next release (0.31) is scheduled for January 2026. +This release introduces a code formatter, and an in-language API for producing `pkl-binary` output. + +The next release (0.31) is scheduled for February 2026. 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]. + @@ -19,38 +21,119 @@ To get started, follow xref:pkl-cli:index.adoc#installation[Installation].# == Highlights [small]#💖# [[formatter]] -=== Canonical Formatter - -TODO - -https://github.com/apple/pkl/pull/1107 -https://github.com/apple/pkl/pull/1208 -https://github.com/apple/pkl/pull/1211 -https://github.com/apple/pkl/pull/1215 -https://github.com/apple/pkl/pull/1217 -https://github.com/apple/pkl/pull/1235 -https://github.com/apple/pkl/pull/1246 -https://github.com/apple/pkl/pull/1247 -https://github.com/apple/pkl/pull/1252 -https://github.com/apple/pkl/pull/1260 - -[IMPORTANT] -==== -By default, `pkl format` will add <> to formatted code. -The resulting code will be compatible only with Pkl 0.30 and later. -When code compatibility with older Pkl releases is required the CLI must be invoked with `--grammar-version 1` to prevent adding trailing commas. -This is especialy important for semantically versioned package, as increasing the minimum required Pkl version is a breaking change and entails incrementing the package's major version. -==== +=== Formatter + +Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1260[#1260])! + +Pkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options. +The goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding. + +The formatter is available both as a CLI subcommand and as a Java API. To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0014-canonical-formatter.adoc[SPICE-0014]. +==== Using the CLI + +The Pkl formatter is available under the `pkl format` subcommand. By default, the command will concatenate and write all formatted content to standard out. + +To simply check for formatting violations, getting formatted output on stdout is likely too verbose. +The `--silent` flag can be used to omit any output, and the <> can be used to determine +if there are formatting violations. + +[source,shell] +---- +pkl format --silent . || echo "Formatting violations were found!" +---- + +Alternatively, the `--names` flag will print out the names of any files that have formatting violations. + +[source,shell] +---- +pkl format --names . +---- + +To apply formatting, use the `--overwrite` (`-w`) flag. +This also implies the `--names` flag. + +[source,shell] +---- +pkl format -w . +---- + +[[formatting-exit-codes]] +==== Exit codes + +The formatter will exit with the following codes: + +|=== +|Code |Description + +|0 +|No formatting violations were found. + +|1 +|Non-formatting errors occurred. + +|11 +|Formatting violations were found. +|=== + +==== Grammar version + +The formatter can be configured with a _grammar version_, which maps to a Pkl version range. + +|=== +|Grammar version |Pkl versions + +|1 +|0.25 - 0.29 + +|2 +|0.30+ +|=== + +Grammar version 2 uses the newly introduced <> feature, and therefore is not compatible with existing versions of Pkl. +To ensure compatibility, use the `--grammar-version 1` CLI flag. + [[binary-renderer-parser]] -=== `pkl-binary` Renderer and Parser +=== `pkl-binary` in-language Renderer + +A new in-language API has been added to render values into xref:bindings-specification:binary-encoding.adoc[pkl-binary encoding] (https://github.com/apple/pkl/pull/1203[#1203], +https://github.com/apple/pkl/pull/1250[#1250]). + +It's sometimes useful to separate Pkl evaluation from data consumption when used as application or service configuration. +This is possible with the pkl-binary format, which is a lossless encoding of Pkl data. + +In this approach, Pkl is first rendered into pkl-binary during build time, and then deserialized into classes and structs at startup time. +This means that the Pkl evaluator does not need to be shipped with the application, which improves code portability and eliminates runtime overhead. -TODO +However, currently, the API for getting this binary format is somewhat cumbersome. +Only the host languages have access to this API (for example, https://swiftpackageindex.com/apple/pkl-swift/0.6.0/documentation/pklswift/evaluator/evaluateexpressionraw(source:expression:)[`evaluateExpressionRaw`] in pkl-swift). +This means that one-off logic must be written to render this format in the host language. -https://github.com/apple/pkl/pull/1203 -https://github.com/apple/pkl/pull/1250 +In 0.30, this renderer is added as an in-language API, through the {uri-stdlib-pklbinaryModule}[`pkl:pklbinary`] standard library module. +Additionally, it is available through CLI flag `--format pklbinary`. + +For example: + +[source%tested,pkl] +---- +import "pkl:pklbinary" + +output { + renderer = new pklbinary.Renderer {} +} +---- + +==== New renderer type: `BytesRenderer` + +To enable the `pkl-binary` renderer feature, Pkl now supports renderers that produce `Bytes` output (https://github.com/apple/pkl/pull/1203[#1203]). + +The existing `ValueRenderer` class now extends new class `BaseValueRenderer`, and a new `BytesRenderer` class is introduced. + +Setting a module's output renderer to a `BytesRenderer` will control its resulting `output.bytes`. + +This affects usage scenarios where a module's `output.bytes` is evaluated, for example, when using `pkl eval`. To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021]. @@ -60,46 +143,99 @@ To learn more about this feature, consult https://github.com/apple/pkl-evolution === Trailing Commas Pkl's grammar has been updated to allow including a comma following the final item of comma-separated syntax elements (https://github.com/apple/pkl/pull/1137[#1137]). + These syntax elements are affected: -[source,pkl] +[source%tested,pkl] ---- -function add(bar, baz,) = bar + baz // <1> -foo = add(1, 2,) // <2> -bar: Mapping // <3> -class MyMapping {} // <4> -baz: Listing(!isEmpty, isDistinct,) // <5> -quz: (String, Int,) -> Boolean // <6> -quux: Mixin = new { parent, -> // <7> +function add( + bar, + baz, // <1> +) = bar + baz + +foo = add( + 1, + 2, // <2> +) + +bar: Mapping< + String, + Int, // <3> +> + +typeealias MyMapping< + Key, + Value, // <4> +> = Mapping + +baz: Listing( + !isEmpty, + isDistinct, // <5> +) + +quz: ( + String, + Int, // <6> +) -> Boolean + +quux: Mixin = new { + paramA, + paramB, // <7> + -> corge = 5 } ---- <1> Function parameter lists in method definitions. <2> Argument lists in method calls. <3> Type argument lists in declared type names. -<4> Type parameter lists in class headers (standard library only). +<4> Type parameter lists. <5> Type constraint lists. <6> Function type parameter lists in function type annotations. -<7> Object body parameter lists in syntax-sugared lambdas. +<7> Object body parameter lists. To learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0019-trailing-commas.adoc[SPICE-0019]. === Pretty-printed traces -TODO +A new evaluator option is added to enable pretty-printed traces (https://github.com/apple/pkl/pull/1100[#1100], https://github.com/apple/pkl/pull/1227[#1227], https://github.com/apple/pkl/pull/1230[#1230]). + +Currently, the `trace()` operator will render values as a single line, and trims the output after 100 characters. +This can obscure information when debugging. -https://github.com/apple/pkl/pull/1100 -https://github.com/apple/pkl/pull/1227 -https://github.com/apple/pkl/pull/1230 +In 0.30, a new evaluator option is added to control how traces are emitted. +Two trace modes are introduced: -=== pkldoc data model revisions +* `compact` - the current output mode (default). +* `pretty` - multiline, with no limit on output size. + +For example, users of the CLI can specify `--trace-mode` as a flag. + +[source,shell] +---- +pkl eval --trace-mode pretty myModule.pkl +---- -TODO +Thanks to https://github.com/ssalevan[@ssalevan] for their contribution to this feature! -https://github.com/apple/pkl/pull/1169 -https://github.com/apple/pkl/pull/1224 -https://github.com/apple/pkl/pull/1241 -https://github.com/apple/pkl/pull/1242 +[[pkldoc-perf-improvements]] +=== `pkldoc` performance improvements + +The `pkldoc` documentation generator has been overhauled (https://github.com/apple/pkl/pull/1169[#1169], https://github.com/apple/pkl/pull/1224[#1224], https://github.com/apple/pkl/pull/1241[#1241], https://github.com/apple/pkl/pull/1242[#1242]). + +Currently, the `pkldoc` tool needs to consume much of an existing documentation website whenever generating new documentation. +This adds significant I/O overhead as a pkldoc documentation website grows. + +The generator has been overhauled to minimize the amount of data needed to be read from the current site. + +To read more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0018-pkldoc-io-improvements.adoc[SPICE-0018]. + +[[pkldoc-migration]] +==== Migration + +The new pkldoc website introduces breaking changes to the data model. +Because of this, existing sites must be migrated before using the `0.30` version of pkldoc. + +To migrate, run the one-time command `pkldoc --migrate`. === Java API changes @@ -121,9 +257,11 @@ New methods are introduced to the Java API. New modules, properties, methods, classes and typealiases have been added to the standard library (https://github.com/apple/pkl/pull/1106[#1106]). -==== Additions to `pkl:base` +==== Changes to `pkl:base` + +Additions: -* {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`] +* New class: {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`] * {uri-stdlib-ValueRenderer}[`ValueRenderer`] (now a subclass of {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`]) * {uri-stdlib-BytesRenderer}[`BytesRenderer`] * {uri-stdlib-baseModule}/RenderDirective#bytes[`RenderDirective.bytes`] @@ -132,20 +270,26 @@ New modules, properties, methods, classes and typealiases have been added to the * {uri-stdlib-evaluatorSettingsModule}#traceMode[`traceMode`] -=== Additions to `pkl:reflect` +==== Additions to `pkl:reflect` * {uri-stdlib-reflectModule}/Class#allMethods[`Class.allMethods`] * {uri-stdlib-reflectModule}/Class#allProperties[`Class.allProperties`] -* {uri-stdlib-reflectModule}/Propterty#allAnnotations[`Propterty.allAnnotations`] +* {uri-stdlib-reflectModule}/Property#allAnnotations[`Propterty.allAnnotations`] * {uri-stdlib-reflectModule}/Propterty#allModifiers[`Propterty.allModifiers`] -=== `pkl` CLI changes +==== New module: `pkl:pklbinary` -==== REPL interrupt handling +The `pkl:pklbinary` standard library module is added. -TODO +=== `pkl repl` improvements -https://github.com/apple/pkl/pull/1188 +The REPL now handles interrupts (Ctrl-C) in a more user-friendly way (https://github.com/apple/pkl/pull/1188[#1188]). + +Instead of exiting immediately, it behaves like other REPLs: + +* If the line is non-empty or in a continuation, the buffer is cleared. +* If the line is empty, print a message with instructions on exiting the REPL. +** If another interrupt is sent immediately after, exit. == Breaking Changes [small]#💔# @@ -155,6 +299,19 @@ Things to watch out for when upgrading. For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/1232[#1232]). +=== New base module names: `BaseValueRenderer`, `BytesRenderer` + +Two new names are introduced to the base module: `BaseValueRenderer`, and `BytesRenderer`. +That means that any code that currently references these names on implicit `this` will break (https://github.com/apple/pkl/pull/1203[#1203]). + +To learn more about how this breaks code and how to fix it, see xref:0.29.adoc#new-base-module-names[New base module names] in 0.29's release notes. + +=== `pkldoc` sites need to be migrated + +Due to breaking changes made in pkldoc's data model, existing pkldoc websites must be migrated. + +See <> for more details. + == Miscellaneous [small]#🐸# * Dependency updates (https://github.com/apple/pkl/pull/1184[#1184], https://github.com/apple/pkl/pull/1225[#1225], https://github.com/apple/pkl/pull/1226[#1226], https://github.com/apple/pkl/pull/1228[#1228]). @@ -168,10 +325,9 @@ For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped The following bugs have been fixed. -* Fix error message when reading a resource/module past root dir (https://github.com/apple/pkl/pull/1234[#1234]). -* Fix publication of pkl-config-kotlin after Gradle 9.1 upgrade (https://github.com/apple/pkl/pull/1240[#1240]). -* Fix Lexer EOF sentinel collision with valid Unicode code points (https://github.com/apple/pkl/pull/1251[#1251]). -* Fix fallback certificates not working in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1198]). +* Incorrect error message when refusing to read past root dir (https://github.com/apple/pkl/pull/1234[#1233]). +* Unicode U+7FFF character (翿) incorrectly parsed as EOF (https://github.com/apple/pkl/pull/1251[#1251]). +* Fallback certificates do not work in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1199]). == Contributors [small]#🙏# From b7dbc5a5d414973e6504c9de3666e3f23c00f2ef Mon Sep 17 00:00:00 2001 From: Jen Basch Date: Wed, 29 Oct 2025 11:06:48 -0700 Subject: [PATCH 3/4] Document consuming pkl-binary data, polish --- docs/modules/release-notes/pages/0.30.adoc | 93 +++++++++++++++++----- 1 file changed, 71 insertions(+), 22 deletions(-) diff --git a/docs/modules/release-notes/pages/0.30.adoc b/docs/modules/release-notes/pages/0.30.adoc index 2241e1153..23a0681ba 100644 --- a/docs/modules/release-notes/pages/0.30.adoc +++ b/docs/modules/release-notes/pages/0.30.adoc @@ -13,7 +13,7 @@ This release introduces a code formatter, and an in-language API for producing ` The next release (0.31) is scheduled for February 2026. 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]. + +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].# @@ -23,7 +23,7 @@ To get started, follow xref:pkl-cli:index.adoc#installation[Installation].# [[formatter]] === Formatter -Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1260[#1260])! +Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1256[#1256], https://github.com/apple/pkl/pull/1259[#1259], https://github.com/apple/pkl/pull/1260[#1260], https://github.com/apple/pkl/pull/1263[#1263], https://github.com/apple/pkl/pull/1265[#1265], https://github.com/apple/pkl/pull/1266[#1266])! Pkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options. The goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding. @@ -102,9 +102,9 @@ A new in-language API has been added to render values into xref:bindings-specifi https://github.com/apple/pkl/pull/1250[#1250]). It's sometimes useful to separate Pkl evaluation from data consumption when used as application or service configuration. -This is possible with the pkl-binary format, which is a lossless encoding of Pkl data. +This is possible with the `pkl-binary` format, which is a lossless encoding of Pkl data. -In this approach, Pkl is first rendered into pkl-binary during build time, and then deserialized into classes and structs at startup time. +In this approach, Pkl is first rendered into `pkl-binary` during build time, and then deserialized into classes and structs at startup time. This means that the Pkl evaluator does not need to be shipped with the application, which improves code portability and eliminates runtime overhead. However, currently, the API for getting this binary format is somewhat cumbersome. @@ -112,11 +112,12 @@ Only the host languages have access to this API (for example, https://swiftpacka This means that one-off logic must be written to render this format in the host language. In 0.30, this renderer is added as an in-language API, through the {uri-stdlib-pklbinaryModule}[`pkl:pklbinary`] standard library module. -Additionally, it is available through CLI flag `--format pklbinary`. +Additionally, it is available through CLI flag `--format pkl-binary`. For example: -[source%tested,pkl] +// this is parsed instead of tested because DocSnippetTests only handles textual output (via ReplServer) +[source%parsed,pkl] ---- import "pkl:pklbinary" @@ -125,6 +126,8 @@ output { } ---- +To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021]. + ==== New renderer type: `BytesRenderer` To enable the `pkl-binary` renderer feature, Pkl now supports renderers that produce `Bytes` output (https://github.com/apple/pkl/pull/1203[#1203]). @@ -135,7 +138,48 @@ Setting a module's output renderer to a `BytesRenderer` will control its resulti This affects usage scenarios where a module's `output.bytes` is evaluated, for example, when using `pkl eval`. -To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021]. +==== Using `pkl-binary` data + +Users of `pkl-config-java` can decode `pkl-binary` data into a `Config` value for mapping to Java types: + +[source,java] +---- +var encodedData; // some byte[] or InputStream +var config = Config.from(encodedData); +var pigeon = config.get("pigeon"); +var age = pigeon.get("age").as(int.class); +var diet = pigeon.get("diet").as(JavaType.listOf(String.class)); +---- + +Users of `pkl-config-kotlin` can decode `pkl-binary` data into a `Config` value for mapping to Kotlin types: + +[source,kotlin] +---- +val encodedData // some ByteArray or InputStream +val config = Config.from(encodedData, ValueMapper.preconfigured().forKotlin()) +val pigeon = config["pigeon"] +val age = pigeon["age"].to() +val hobbies = pigeon["diet"].to>() +---- + +Users of `pkl-go` can unmarshal `pkl-binary` data directly into structs generated by `pkl-gen-go`: + +[source,go] +---- +var encodedData []byte +var result MyGeneratedStruct +if err := pkl.Unmarshal(encodedData, &result); err != nil { + // handle error +} +---- + +Users of `pkl-swift` can unmarshal `pkl-binary` data directly into structs generated by `pkl-gen-swift`: + +[source,swift] +---- +let encodedData: [UInt8] +let result = try PklDecoder.decode(MyGeneratedStruct.self, from: encodedData) +---- == Noteworthy [small]#🎶# @@ -158,37 +202,40 @@ foo = add( 2, // <2> ) +typealias MyMapping< + Key, + Value, // <3> +> = Mapping + bar: Mapping< String, - Int, // <3> + Int, // <4> > -typeealias MyMapping< - Key, - Value, // <4> -> = Mapping - -baz: Listing( - !isEmpty, - isDistinct, // <5> +baz: Mapping( + !containsKey("forbidden key"), + !containsKey("forbidden value"), // <5> ) -quz: ( +qux: ( String, Int, // <6> -) -> Boolean +) -> Dynamic = + (paramA, paramB) -> new Dynamic { + quux = "\(paramA): \(paramB)" + } -quux: Mixin = new { +corge = (qux) { paramA, paramB, // <7> -> - corge = 5 + grault = paramA.length * paramB } ---- <1> Function parameter lists in method definitions. <2> Argument lists in method calls. -<3> Type argument lists in declared type names. -<4> Type parameter lists. +<3> Type parameter lists in generic type definitions. +<4> Type argument lists in type annotations and casts. <5> Type constraint lists. <6> Function type parameter lists in function type annotations. <7> Object body parameter lists. @@ -252,6 +299,7 @@ New methods are introduced to the Java API. * `org.pkl.core.Evaluator.evaluateExpressionPklBinary` * `org.pkl.core.EvaluatorBuilder.setTraceMode` * `org.pkl.core.EvaluatorBuilder.getTraceMode` +* `org.pkl.config.java.Config.from` === Standard Library changes @@ -338,4 +386,5 @@ We would like to thank the contributors to this release (in alphabetical order): * https://github.com/netvl[@netvl] * https://github.com/spyoungtech[@spyoungtech] * https://github.com/srueg[@srueg] +* https://github.com/ssalevan[@ssalevan] * https://github.com/stackoverflow[@stackoverflow] From d5663b42d8092f986713c96682886773127732c2 Mon Sep 17 00:00:00 2001 From: Jen Basch Date: Wed, 29 Oct 2025 18:43:24 -0700 Subject: [PATCH 4/4] Address review feedback --- docs/modules/release-notes/pages/0.30.adoc | 49 +++++++++++----------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/modules/release-notes/pages/0.30.adoc b/docs/modules/release-notes/pages/0.30.adoc index 23a0681ba..ff95c39c9 100644 --- a/docs/modules/release-notes/pages/0.30.adoc +++ b/docs/modules/release-notes/pages/0.30.adoc @@ -1,7 +1,7 @@ = Pkl 0.30 Release Notes :version: 0.30 :version-minor: 0.30.0 -:release-date: October 30th, 2025 +:release-date: November 3rd, 2025 include::ROOT:partial$component-attributes.adoc[] @@ -23,7 +23,7 @@ To get started, follow xref:pkl-cli:index.adoc#installation[Installation].# [[formatter]] === Formatter -Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1256[#1256], https://github.com/apple/pkl/pull/1259[#1259], https://github.com/apple/pkl/pull/1260[#1260], https://github.com/apple/pkl/pull/1263[#1263], https://github.com/apple/pkl/pull/1265[#1265], https://github.com/apple/pkl/pull/1266[#1266])! +Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1256[#1256], https://github.com/apple/pkl/pull/1259[#1259], https://github.com/apple/pkl/pull/1260[#1260], https://github.com/apple/pkl/pull/1263[#1263], https://github.com/apple/pkl/pull/1265[#1265], https://github.com/apple/pkl/pull/1266[#1266], https://github.com/apple/pkl/pull/1267[#1267], https://github.com/apple/pkl/pull/1270[#1270], https://github.com/apple/pkl/pull/1271[#1271], https://github.com/apple/pkl/pull/1272[#1272], https://github.com/apple/pkl/pull/1273[#1273], https://github.com/apple/pkl/pull/1274[#1274])! Pkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options. The goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding. @@ -49,11 +49,11 @@ Alternatively, the `--names` flag will print out the names of any files that hav [source,shell] ---- -pkl format --names . +pkl format --diff-name-only . ---- To apply formatting, use the `--overwrite` (`-w`) flag. -This also implies the `--names` flag. +This also implies the `--diff-name-only` flag. [source,shell] ---- @@ -140,46 +140,47 @@ This affects usage scenarios where a module's `output.bytes` is evaluated, for e ==== Using `pkl-binary` data -Users of `pkl-config-java` can decode `pkl-binary` data into a `Config` value for mapping to Java types: +Users of Pkl's language binding libraries can decode `pkl-binary` data into instances of code-generated types. +[tabs] +==== +Java:: ++ [source,java] ---- -var encodedData; // some byte[] or InputStream +var encodedData = fetchEncodedData(); // some byte[] or InputStream var config = Config.from(encodedData); -var pigeon = config.get("pigeon"); -var age = pigeon.get("age").as(int.class); -var diet = pigeon.get("diet").as(JavaType.listOf(String.class)); +var appConfig = config.as(AppConfig.class); ---- -Users of `pkl-config-kotlin` can decode `pkl-binary` data into a `Config` value for mapping to Kotlin types: - +Kotlin:: ++ [source,kotlin] ---- -val encodedData // some ByteArray or InputStream +val encodedData = fetchEncodedData() // some ByteArray or InputStream val config = Config.from(encodedData, ValueMapper.preconfigured().forKotlin()) -val pigeon = config["pigeon"] -val age = pigeon["age"].to() -val hobbies = pigeon["diet"].to>() +val appConfig = config.to() ---- -Users of `pkl-go` can unmarshal `pkl-binary` data directly into structs generated by `pkl-gen-go`: - +Go:: ++ [source,go] ---- -var encodedData []byte -var result MyGeneratedStruct +encodedData := fetchEncodedData() // some []byte +var appConfig AppConfig if err := pkl.Unmarshal(encodedData, &result); err != nil { // handle error } ---- -Users of `pkl-swift` can unmarshal `pkl-binary` data directly into structs generated by `pkl-gen-swift`: - +Swift:: ++ [source,swift] ---- -let encodedData: [UInt8] -let result = try PklDecoder.decode(MyGeneratedStruct.self, from: encodedData) +let encodedData = fetchEncodedData() // some [UInt8] +let appConfig = try PklDecoder.decode(AppConfig.self, from: encodedData) ---- +==== == Noteworthy [small]#🎶# @@ -299,7 +300,7 @@ New methods are introduced to the Java API. * `org.pkl.core.Evaluator.evaluateExpressionPklBinary` * `org.pkl.core.EvaluatorBuilder.setTraceMode` * `org.pkl.core.EvaluatorBuilder.getTraceMode` -* `org.pkl.config.java.Config.from` +* `org.pkl.config.java.Config.fromPklBinary` === Standard Library changes