New automerge requirement: Release notes required for breaking package releases

ericphanson
Wed, 18 Dec 2024 10:41:37 +0000
Package Announcements

When registering a breaking release of a package, you now need to add release notes to the registration that mention what the breaking changes are, so that your users have an easier time understanding what they need to change in their code in order to use the new version of your package.

The release notes must include the keyword “breaking” (or “changelog”), because the intention is for you to describe what the breaking changes are, or where to find them, to help your users update their code.

What is a breaking release?

Julia’s package manager Pkg.jl uses semantic versioning, often shortened to semver, to manage the compatibility between packages (see 7. Compatibility · Pkg.jl for the specific notation and rules), meaning version numbers take the form $major.$minor.$patch. If you declare compatibility with 0.2.3 of a package via MyDep = "0.2.3", Pkg will allow upgrades for any 0.2.x patch (for x\geq 3), and likewise for MyDep = "1.2.3" any upgrade up to (but not including) version 2. A breaking release is in (Julia) semver terms is a minor version change when pre-v1, and a major version change post-v1.

How do I add release notes to my package registration when registering with Registrator.jl?

See Registrator.jl’s documentation here. In short, you add them just after the @JuliaRegistrator register command. If you forget them, you can retrigger registration again and add them and it will update your PR automatically.

How do I add release notes to my package registration when registering with JuliaHub?

Enter them in the box labeled “Release notes” when you register:

What if I use a changelog to describe my breaking changes?

You still need to enter some form of release notes, but you can simply point to your changelog. E.g. “See CHANGELOG.md for a description of changes in this release”. (Your release notes need to mention “breaking” or “changelog”, case insensitive, to pass the check).

What if I make a huge number of breaking changes and can’t mention all the changes?

You could summarize the most important points, e.g. “The main breaking change is a renaming of the type MyType to MyType2. There are other breaking changes but you need to look at the code changes to find them all”. This is discouraged since it is less helpful to your users, but would suffice to pass the automerge check.

Where do the release notes show up?

Registrator (via comment bot or juliahub) will add the release notes to the registration PR. Then if you have TagBot configured for your repository, once the version is merged, it will add those release notes to the git tag / github release it creates.

Where are all the AutoMerge requirements listed?

They are here: Automatic merging guidelines · RegistryCI.jl

See also General’s README which links to them and also contains a useful FAQ for package registraton.

Do I need to comply with all AutoMerge requirements for my package to be registered?

No. Complying with AutoMerge’s requirements is highly recommended because it means your registration can be processed automatically without manual intervention, and because it helps meet some basic best-practices. However, if you cannot meet the requirements for some reason, you can ask for your registration to be manually merged. Make a request in the #pkg-registration channel on the public Julia Language Slack, or directly on the registration PR itself (or both).

I don’t like this, can we not?

We can change this rule if it proves to be unduly burdensome. Let’s try it out.

This check is great, can we add more?

This check came about since @ianshmean kindly filed a PR to implement it, and it seemed reasonable to the registry maintainers who reviewed it (e.g. Dilum reviewed and did not leave a blocking comment, and I approved it). If you would like to add a check, give it a try!

Note that we try to balance burden to developers and benefit to the ecosystem, so if your proposed check is much stricter than the current rules, it may be worth an issue or discussion here on Discourse to discuss it first.

51 posts - 20 participants