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
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
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, 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?
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.
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.
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.
The problem is, currently such packages build a fair part (see the post by ericphanson above) 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?
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
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:
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.
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).
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?
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).
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.
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.
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.
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:
Automatically get a CompatHelper PR for a new breaking dep version
Read the release notes directly in the PR, which ideally would give a concise upgrade tip
Adapt their code without even having to visit the dep documentation
And the ecosystem is easier & more pleasant to keep up to date.
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 for example). Or maybe that’s out of scope and we could write a second bot that makes the call to JuliaRegistrator?
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?
