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

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

=== Power Assertions

Pkl's test output and error output has been improved with power assertions (https://github.com/apple/pkl/pull/1384[#1384])!

Pkl has two places that are effectively assertions.
These are:

* Type constraint expressions
* Test facts

Currently, when these assertions fail, the error message prints the assertion's source section.
However, this information can sometimes be lacking.
It tells you what the mechanics of the assertion is, but doesn't tell you _why_ the assertion is failing.

For example, here is the current error output of a failing typecheck.

[source,text]
----
–– Pkl Error ––
Type constraint `name.endsWith(lastName)` violated.
Value: new Person { name = "Bub Johnson" }

7 | passenger: Person(name.endsWith(lastName)) = new { name = "Bub Johnson" }
----

Just from this error message, we don't know what the last name is supposed to be.
What is `name` supposed to end with?
We just know it's some property called `lastName` but, we don't know what it _is_. 

In Pkl 0.31, the error output becomes:

[source,text]
----
–– Pkl Error ––
Type constraint `name.endsWith(lastName)` violated.
Value: new Person { name = "Bub Johnson" }

    name.endsWith(lastName)
    │    │        │
    │    false    "Smith"
    "Bub Johnson"

7 | passenger: Person(name.endsWith(lastName)) = new { name = "Bub Johnson" }
----

Now, we know what the expecation actually is.

This type of diagram is also added to test facts.
When tests fail, Pkl emits a diagram of the expression, and the values produced.

For example, given the following test:

.math.pkl
[source,pkl]
----
amends "pkl:test"

facts {
  local function add(a: Int, b: Int) = a * b
  local function divide(a: Int, b: Int) = a % b
  ["math"] {
    add(3, 4) == 7
    divide(8, 2) == 4
  }
}
----

The error output now includes a power assertion diagram, which helps explain why the test failed.

[source,text]
----
module math
  facts
    ✘ math
       add(3, 4) == 7 (math.pkl:9)
       │         │
       12        false
       divide(8, 2) == 4 (math.pkl:10)
       │            │
       0            false

0.0% tests pass [1/1 failed], 0.0% asserts pass [2/2 failed]
----

== Noteworthy [small]#🎶#

Ready when you need them.

=== Standard Library changes

New properties have been added to the standard library (https://github.com/apple/pkl/pull/1396[#1396]).

==== Additions to `pkl:base`

The following APIs have been added:

* link:{uri-stdlib-List}#isNotEmpty[`List.isNotEmpty`]
* link:{uri-stdlib-Map}#isNotEmpty[`Map.isNotEmpty`]
* link:{uri-stdlib-Set}#isNotEmpty[`Set.isNotEmpty`]
* link:{uri-stdlib-Listing}#isNotEmpty[`Listing.isNotEmpty`]
* link:{uri-stdlib-Mapping}#isNotEmpty[`Mapping.isNotEmpty`]
* link:{uri-stdlib-String}#isNotEmpty[`String.isNotEmpty`]
* link:{uri-stdlib-String}#isNotBlank[`String.isNotBlank`]

== 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