# New automerge requirement: Release notes required for breaking package releases
**URL:** https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955
**Category:** Package Announcements
**Tags:** general-registry, registryci
**Created:** [December 18, 2024, 10:41am UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955 "2024-12-18T10:41:37Z")
**Posts on this page:** 20
**Page:** 2
### Author:  [@adienes](https://discourse.julialang.org/u/adienes)
#### Post date: [December 20, 2024, 6:35pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/21 "2024-12-20T18:35:16Z")
> [@Datseris](#):
>
> Motivating people to release 1.0 faster/sooner if their package has users.
the main motivation here “should” be that users are less willing to depend on packages pre-1.0
if packages instead are pressured to be pseudo-stable once they have users (no matter the version number) then users have no such incentive to care if the package they use is pre- or post- 1.0
> [@giordano](#):
>
> It’s not having a clue of _what_ changed and how to adapt to the changes.
good documentation is a crucial part of any good package, regardless of stability status. if we want to enforce quality standards in General then we should enforce documentation standards, yes. I just don’t think that “breaking” changes should be singled out because “breaking” changes are supposed to be a dime a dozen pre-1.0, per SemVer
---
### Author:  [@gdalle](https://discourse.julialang.org/u/gdalle)
#### Post date: [December 25, 2024, 11:39am UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/22 "2024-12-25T11:39:28Z")
> [@goerz](#):
>
> Personally, I’ve never using release notes during registration (when commenting `@JuliaRegistrator register` to initiate a new version release, I mean). Instead, I use the release notes on GitHub (partly auto-generated)
I wanted to come back to that: GitHub-generated release notes are much better than nothing. They contain a list of PRs with links, and if the commit names follow something like [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), it is very easy to track down breaking changes.
If I add some release notes to the `@JuliaRegistrator register` comment, how will they mix with the automatic release notes from GitHub?
---
### Author:  [@nsajko](https://discourse.julialang.org/u/nsajko)
#### Post date: [December 25, 2024, 12:15pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/23 "2024-12-25T12:15:11Z")
> [@Datseris](#):
>
> SemVer doesn’t say “pre 1.0 nothing matters” at all
It’s really quite clear:
> Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
> **[Semantic Versioning 2.0.0](https://semver.org/)**
>
> Semantic Versioning spec and website
IMO the General Registry shouldn’t accept releases with zero major version.
---
### Author:  [@Datseris](https://discourse.julialang.org/u/Datseris)
#### Post date: [December 25, 2024, 12:44pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/24 "2024-12-25T12:44:52Z")
We are disagreeing in pedantic stuff, while we agree in the majority of the discussion: I also hearthartily support the statement that the General Registry shouldn’t accept releases with zero major version. Now with Julia 1.11 you can easily add dependencies that are not registered in the General Registry _and_ have version control for them via Pkg due to the new system. So I see no obvious reason for packages to be registered before 1.0.
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [December 25, 2024, 1:15pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/25 "2024-12-25T13:15:56Z")
> [@nsajko](#):
>
> IMO the General Registry shouldn’t accept releases with zero major version.
There’s a discussion about that on GitHub: [Auto block registration of packages pre-1.0 · Issue #111019 · JuliaRegistries/General · GitHub](https://github.com/JuliaRegistries/General/issues/111019)
In theory, I’d be open to it, but then we should also have much better automatic quality control to make sure that packages that get registered are actually ready for 1.0: According to SemVer, they must _specify_ the public API (that is, have complete documentation), and I would argue that they must have tests with decent coverage (difficult to detect breaking changes otherwise). I’d worry that packages get tagged as 1.0 just to make the bot happy, even though they’ve not at that stage of development yet. Also, even though we’ve added features to improve working with unregistered package as of late, we’d be expecting newcomers to figure out those workflows and/or the use of a LocalRegistry for those early stages of development. Maybe that’s a good thing, but if we want to go down that route, there’s still a lot to figure out.
---
### Author:  [@aplavin](https://discourse.julialang.org/u/aplavin)
#### Post date: [December 25, 2024, 2:34pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/26 "2024-12-25T14:34:13Z")
As another datapoint regarding versions, I really like how straightforward the Julia package versioning is – both for users and for devs.
There’s only one strict rule, and it is enough for the vast majority of situations:
* * *
Choose whatever version you like, just increment the first non-zero number when making breaking changes and increment other number(s) for non-breaking changes.
* * *
That’s the only thing that matters for package installation, and the only universally followed practice in the ecosystem. Of course, individual packages are free to assign more meaning to different versions: eg, even versions are LTS, or x.y.z is more stable than 0.x.y, but these are far from universal. For more complex scenarios, one may need the distinction between “features” and “bug fixes”, but most packages are fine without it.
As the `]generate` command sets version = 0.1, many packages are naturally registered at 0.1.x version – people like following defaults. If `]generate` set version = 1.0.0, everyone would’ve registered 1.0.x even without restrictions in General.
Merry Christmas 🙂
---
### Author:  [@Eben60](https://discourse.julialang.org/u/Eben60)
#### Post date: [December 25, 2024, 5:35pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/27 "2024-12-25T17:35:55Z")
probably
> [@nsajko](#):
>
> It’s really quite clear:
>
> > Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
> [@nsajko](#):
>
> IMO the General Registry shouldn’t accept releases with zero major version.
The problem is, currently such packages build a fair part ([see the post by ericphanson above](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/8)) of the Julia foundational packages or their dependencies. Probably, none, or almost none of the most used and most important packages is free from downstream dependencies on v0.x packages. Such popular packages as Documenter or Pluto even depend on ANSIColoredPrinters.jl which is v0.0.1 (how it got registered??). If we generally maintain that pre-v1.0 packages are unreliable, then we must accept that Julia (as ecosystem) is not suitable for anything serious. We do not think that is actually the case, do we?
---
### Author:  [@Eben60](https://discourse.julialang.org/u/Eben60)
#### Post date: [December 25, 2024, 5:50pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/28 "2024-12-25T17:50:15Z")
The new automerge requirement is actually decided, and obviously not going to be reversed. Therefore it might make sense to close this specific topic.
What however is worth discussing (and actually being discussed here) is how to provide Quality Control on package registration. We probably should start a new topic, or split part of the discussion above?
May I link here two relevant and relatively recent topics
> [@The present and the future of package registration](https://discourse.julialang.org/t/the-present-and-the-future-of-package-registration/99890):
>
> This has been on my mind for some time, but now that my package registration PR has been closed, I finally decided to take a few minutes to share. TLDR; Due to the fact that Julia packages are registered at “top level”, there is scarcity in regards to package names. This introduces unnecessary limits and friction. What do I mean by “top level”? Simply that the packages are not namespaced under an organisation. Like for example how NPM allows: [Creating and publishing an organization scoped pac…](https://docs.npmjs.com/creating-and-publishing-an-organization-scoped-package)
> [@Please more bureaucracy on package registrations!](https://discourse.julialang.org/t/please-more-bureaucracy-on-package-registrations/100018):
>
> BTW, is there a smiley for tongue-in-cheek? Inspired by the [The present and the future of package registration](https://discourse.julialang.org/t/the-present-and-the-future-of-package-registration/99890) thread, especially by the [response](https://discourse.julialang.org/t/the-present-and-the-future-of-package-registration/99890/49) by @Tamas_Papp to my comment and by the reference to this PR [Check that there are “enough” tests and documentation](https://github.com/JuliaRegistries/RegistryCI.jl/pull/492#top). Yes, automated checking some metrics on documentation and testing coverage of a new package would be nice to have. But what we can also do is to ask the package authors to fill in themselves a questionnaire, answering the questions on …
---
### Author:  [@e3c6](https://discourse.julialang.org/u/e3c6)
#### Post date: [December 25, 2024, 8:38pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/29 "2024-12-25T20:38:22Z")
Hi, I think is a nice idea to try to push towards documenting breaking changes, and perhaps also standardize a location to find these breaking changes listed (e.g., the release notes).
However from the OP it is not completely clear to me where exactly are we supposed to list the breaking changes (or the keywords “breaking” or “changelog”). Where is Automerge expecting to find them? Is it in the `git tag` annotation? So it means I have to create a tag using:
```julia
git tag -a v2.0.0 -m "my version 2.0.0 with some breaking changes"
```
Or is it in the Github release notes? This would be weird since I think those notes are not transferrable if I move my repo from Github to Gitlab.
---
### Author:  [@ericphanson](https://discourse.julialang.org/u/ericphanson)
#### Post date: [December 25, 2024, 8:47pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/30 "2024-12-25T20:47:05Z")
Hi @e3c6, you note the breaking changes when you go to register the new version of the package (_not_ when you create a git tag). So if you use the JuliaRegistrator comment bot, you add the release notes there. If you use JuliaHub to register your package versions, there’s a textbox there. If you register your package versions some other way, let us know!
Then, if you use TagBot (which supports GitHub and GitLab), the final notes will show up in the git tag, as well as the Github “release” (when used on GitHub).
Does that makes sense?
---
### Author:  [@e3c6](https://discourse.julialang.org/u/e3c6)
#### Post date: [December 25, 2024, 8:58pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/31 "2024-12-25T20:58:42Z")
Thanks, it makes sense. However that’s not the workflow I use. I don’t use TagBot.
The reason is I maintain a separate registry that I share with a few colleagues. I register new versions often in this personal registry (creating associated tags), and then more rarely, for selected versions I’m happy with, I also register them on General (which means the tag already exists, as this version was previously registered in my personal registry).
I also cannot anticipate which version will end up in General, as I decide that only after having used the package for a while, which is usually sometime after it was already registered on my personal registry. Does that make sense?
I’m not sure how I’d integrate TagBot into this workflow. So if I understand correctly, I should just do a comment like this on a commit:
> @JuliaRegistrator register
>
> Breaking changes:
>
> - Changed foo to bar.
Is that sufficient to pass the automerge checks? Then what happens? If I don’t use `TagBot`, where do these comments `Breaking changes: ...` end up?
---
### Author:  [@ericphanson](https://discourse.julialang.org/u/ericphanson)
#### Post date: [December 25, 2024, 9:16pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/32 "2024-12-25T21:16:37Z")
Yes, that’s sufficient. If you don’t use TagBot, they don’t go anywhere unfortunately, and it might make sense to be pretty minimal with it (e.g. just “some changes are breaking”) to not waste your time. However, I would be interested in some mechanism to make this information available somewhere.
- The simplest place would be to add it to the registry itself, since we have the information available at registration time. But that would be a bad idea, as it would bloat the registry: everyone would need to download release notes for every package regardless of whether or not they use it.
- We could do something else with the information at registration time. I suppose there could be some secondary system with other metadata that could be queried. This could be a lot of work and maintenance so I think it’s a bad idea too.
- Or, and I think this is likely the best option, there could be some standard place to put release notes in the package itself, and we could modify the automerge rule to skip requiring release-notes-via-registrator if they are present in this other place. This would likely lead to tons of bikeshedding about the format and location, but it would have the advantage that by sitting next to the code, it would get shipped with the package code itself only when necessary by the existing distribution mechanisms (Pkg.jl + PkgServers) and could be queried locally (maybe there could be `pkg> changelog MyPkg` to see the latest changes).
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [December 25, 2024, 9:30pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/33 "2024-12-25T21:30:34Z")
Please correct me if I missed something: we already use semver. The gist is:
So clearly major version introduces incompatibility (breaking change); everything else is fine from the semver point of view.
Why do we need to spell this out explicitly in the release notes?
---
### Author:  [@e3c6](https://discourse.julialang.org/u/e3c6)
#### Post date: [December 25, 2024, 9:37pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/34 "2024-12-25T21:37:25Z")
> [@PetrKryslUCSD](#):
>
> Why do we need to spell this out explicitly in the release notes?
Because it is important that users can find easily what those breaking changes are, to update their code accordingly and be able to support the new version. I often find myself searching for the list of breaking changes when a new major version is registered of some package, and unfortunately often they are not listed anywhere.
---
### Author:  [@e3c6](https://discourse.julialang.org/u/e3c6)
#### Post date: [December 25, 2024, 9:40pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/35 "2024-12-25T21:40:54Z")
> [@ericphanson](#):
>
> Or, and I think this is likely the best option, there could be some standard place to put release notes in the package itself
I also think this would be the best option. I think it would be nice to decouple the annotation of breaking changes from whether a package is registered or not in General. This implies that the information has to exist somehow in the package repository itself. Standardizing this location will be another step towards helping users quickly find such a list of breaking changes when they need it.
Perhaps in the `CHANGELOG.md` ([https://keepachangelog.com/](https://keepachangelog.com/))? Or the tag annotation?
---
### Author:  [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)
#### Post date: [December 25, 2024, 10:00pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/36 "2024-12-25T22:00:40Z")
I see: so not just to say “it is breaking” (which is what semver does, we don’t need to repeat this), but “it is breaking because of A, B, and C”?
---
### Author:  [@giordano](https://discourse.julialang.org/u/giordano)
#### Post date: [December 25, 2024, 10:07pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/37 "2024-12-25T22:07:52Z")
Yes, and if you care about sanity of your users clearly write down somewhere (a changelog file or something like that that’s obviously accessible) how to upgrade from previous version (e.g. “function `xyz` was renamed to `abc`”, or “function `foo` now takes an `Integer` as second positional argument instead of an `AbstractFloat`”), expecting them to figure this out by digging in git history or long discussions in pull requests is not fun.
---
### Author:  [@ianshmean](https://discourse.julialang.org/u/ianshmean)
#### Post date: [December 25, 2024, 11:48pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/38 "2024-12-25T23:48:46Z")
Also, CompatHelper PRs would benefit from showing the release notes of the new breaking version, like dependabot does. So with this improvement, it motivates implementing that.
Then the user experience is:
1. Automatically get a CompatHelper PR for a new breaking dep version
2. Read the release notes directly in the PR, which ideally would give a concise upgrade tip
3. Adapt their code without even having to visit the dep documentation
And the ecosystem is easier & more pleasant to keep up to date.
---
### Author:  [@klafyvel](https://discourse.julialang.org/u/klafyvel)
#### Post date: [December 26, 2024, 9:13am UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/39 "2024-12-26T09:13:40Z")
Hi! How difficult would it be for JuliaRegistrator to fetch the commit history to identify breaking changes? In a similar fashion to what release-please does (see [here](https://github.com/Klafyvel/nvim-smuggler/pull/46) for example). Or maybe that’s out of scope and we could write a second bot that makes the call to JuliaRegistrator?
---
### Author:  [@simsurace](https://discourse.julialang.org/u/simsurace)
#### Post date: [December 26, 2024, 3:34pm UTC](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955/40 "2024-12-26T15:34:25Z")
> [@ericphanson](#):
>
> I think with the current Julia ecosystem, there are a bunch of heavily used, infrequently breaking packages that are nonetheless pre-v1.
How do we get past this? I can see that there are difficult ones like Distributions but for some of them they could just move to v1 as is. But I feel like this is one of those things which are just gonna stay that way without incentives, and it feels like additional requirements past v1 are not helping. Am I too pessimistic?
[Previous page](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955.md?page=1)
[Next page](https://discourse.julialang.org/t/new-automerge-requirement-release-notes-required-for-breaking-package-releases/123955.md?page=3)