Upgrading

Easel is constantly being improved with new features and optimizations. Most of the time, the improvements are backwards-compatible, and so you can receive the benefits of the improvements without needing to do anything. Sometimes however, we have to make breaking changes, which means that you may need to update your code to take advantage of the new features or improvements. This page describes how breaking changes are managed in Easel.

Edition numbers

The edition number of Easel is used to track breaking changes. Whenever a breaking change is made, we increment the edition number of Easel. You specify which edition of Easel your project uses in the [engine] section of easel.toml. When you create a new project, the edition number is automatically initialized with the latest edition at the time the project was created.

Upgrading to a new edition

When you want to upgrade to a newer edition of Easel, you change the edition in easel.toml to the new number. You may also need to update your code according to the upgrade instructions for the new edition. See the List of Editions for a list of all editions and their upgrade instructions.

Opting out of certain upgrades

It is possible to opt-out of certain upgrades using the legacy.toml file. We recommend you avoid this whenever possible as all documentation will be written for the latest edition of Easel, and opting out of upgrades may cause subtle differences that may make it difficult to follow the examples.

Documentation

The Easel documentation is always for the latest edition of Easel. If you are working with an older edition, you may need to refer to the upgrade instructions for that edition to understand the differences. For this reason, it is recommended to upgrade to the latest edition of Easel wherever possible.

List of editions

A full list of all editions, along with any upgrade instructions, can be found on the Editions page.