Publishing packages from the charmlibs monorepo

The charmlibs monorepo has CI that automatically releases your library to PyPI each time you bump your library’s version to a non-dev version. That is, whenever a PR is merged, if the version of a library has changed, and the new version is not a dev version like X.Y.Z.devN, the CI will try to publish your library to PyPI.

Warning

Merging a PR that would publish a library will be blocked unless the library’s CHANGELOG.md is also updated.

Trusted publishing

Before you can make your first release, you’ll need to set up trusted publishing on PyPI for your library. Remember that the package name should be charmlibs-<LIBRARY>, or charmlibs-interfaces-<LIBRARY> for an interface library. The repository owner is canonical, the repository name is charmlibs, and the workflow name is publish.yaml.

Testing

You should also set this up on test.pypi.org – if you run the publish.yaml workflow manually, you’ll have to specify a package, and this package will be published to test.pypi.org (regardless of whether it’s a dev version or not).

Semantic versioning

Libraries in the charmlibs monorepo should follow semantic versioning.

It’s a good idea to initially add new libraries with a major version of 0. In semantic versioning, this communicates that the API design is still in progress, so even when the library is released, you’re free to make well-considered breaking changes before your 1.0 release.

However, if you’re porting an existing Charmhub-hosted library as-is, then it’s better to start with a major version of 1, to communicate that you won’t break the existing API without a major version bump.

Dev versions

You may want to make your initial PR with a dev version – that is, a version with a .devN suffix, like 1.2.3.dev0.

Dev versions are excluded from the charmlibs monorepo’s release CI, so they won’t be released to PyPI. This means you can make follow ups to your initial PR before your initial release, and publish your library on test.pypi.org by manually running the publish workflow. When you’re ready to make a release, make a PR that bumps your library’s version to a non-dev version. All version bumps (to non-dev versions) will automatically trigger a release on merge. After a release, you can follow up with a bump to a dev version, or leave the version unchanged until you’re ready for the next release.

Changelog

Every release should be accompanied by an entry in your library’s CHANGELOG.md with the following format:

# A.B.C - N Month 20XX

...

That is, a heading with the version number, separated by spaces and a hyphen from the release date. The body of the section should include a meaningful description of the changes in this release. This could be a bulleted list of commits, or a short paragraph, or both.

Merging a PR that would release your library will be blocked unless the CHANGELOG.md is updated.