How Charmcraft 2.0 will break backwards compatibility

charmcraft
1

The new release of Charmcraft 2.0, currently in beta (planned for candidate in some days, stable a week after that) brings several new features, but also as you can expect from a major version update (and the title of this post) some backwards compatibility is not fully maintained.

The following are the breaking changes and alternatives to keep everything nice and green, but before getting into those details let me remind you that if you want to stay out of this update, and keep the Charmcraft as you know it today, you only need to follow the 1.x track; if you’re not there already it’s easy to switch:

sudo snap switch charmcraft --channel=1.x/stable

So, the changes:

  • A bases configuration is now required in charmcraft.yaml (so far it was optional, deprecated since Charmcraft 1.1). If you still don’t have this key, the following was the default until now (so probably what you want to keep):

    ...
bases:
  - build-on:
    - name: "ubuntu"
      channel: "20.04"
    run-on:
    - name: "ubuntu"
      channel: "20.04"
...

  • Use charm-entrypoint in charmcraft.yaml parts to define the entry point. The --entrypoint command line option was deprecated in Charmcraft 1.2 and now it’s not available anymore. Note that if the option is not included in the file, the default src/charm.py is still valid and used.

    Example configuration:

    ...
parts:
  charm:
    charm-entrypoint: "src/my_entrypoint.py"
...

  • Use charm-requirements in charmcraft.yaml parts to specify any particular Python requirements file. The --requirements command line option was deprecated in Charmcraft 1.2 and it’s no longer present. Note that if the option is not included, and a requirements.txt file is present in the project’s root, it will be used.

    Example configuration:

    ...
parts:
  charm:
    charm-requirements: ["reqs1.txt", "reqs2.txt"]
...

  • Use the pack command to pack the project into a .charm file. The build command was deprecated in Charmcraft 1.5 and is now removed (this verb will have a different meaning in the future).

    $ charmcraft help pack
Usage:
    charmcraft pack [options]

Summary:
    Build and pack a charm operator package or a bundle.
...

  • The --trace option to set a verbosity level was removed after the introduction of Craft CLI 1.0. The --quiet and --verbose options still remain available, and you also can use the new --verbosity=LEVEL option (allowed levels are quiet, brief, verbose, debug and trace).

    E.g.:

    $ charmcraft pack --verbosity=trace
... (a **very** verbose output) ...

  • After starting to use the new version of Craft CLI, several progress and output messages were improved. If you were using charmcraft programmatically and parsing those messages, you should start using the --format=json option (introduced in Charmcraft 1.7) to get commands results in an easier way to consume from other programs.

    E.g.:

    $ charmcraft revisions mycharm --format=json | jq .[0].revision
4

  • The JSON-formatted output for the status command was improved: the channels key (that holds everything released for a track) was renamed to mappings, and the channel value in each release now properly includes the track (fixed the bug of showing only the risk or risk/branch).

5 Likes