Encouraging 1.x versions for registered packages?

[Eben60]

Would it somehow be possible to adapt the technique proposed in Solving one based indexing?

[Norman]

Whether 1.x versioning is a good practice or not is one thing. Whether all packages should follow the 1.x versioning is a different matter. There are always possibilities of good reasons to depart from a single standard. Enforcing following a single standard just creates too much centrality of decision making. It’s better off to let individual package developer to decide what he/she wants to do based on the specific circumstances.

[mkitti]

@mkitti

Interesting. We should relegate v0 to indicate pre-registration status. Perhaps package registration should only automerge packages at v1 into the registry?

Just to be very clear about my suggestion, I was referring to the automerge of new packages into the Julia General Registry. This does not preclude v0 packages from being merged into the Julia General Registry. This could still be done manually.

Updates to existing v0 packages in the registry should continue to be automerged.

[goerz]

Please don’t. First of all, 0.x releases indicate an experimental API. That is, as the package author, I will make changes without any consideration for backward compatibility. This is an important part of software development: A good API often only becomes apparent after extended usage. I want to absolutely push back on @oxinabox’s statement that

For open-source libraries users immediately depend on your API.

I definitely want “the public” use experimental versions of my package because their experience will inform the final design of the API that will become 1.0. But they should also know that they cannot yet rely on a stable API. I strongly believe that in most cases, v0.1.0 is the appropriate initial release of a package. “We’ll only release v1.0.0” might make sense for companies, but certainly not for smaller or academic projects.

That doesn’t necessarily preclude limiting the General registry to v1.x versions, but given the current state of Julia’s package tooling, it does not seem like a good idea. In principle, you could make General more restrictive, but I think that should mean putting actual quality control into what can be registered to make sure that the v0.1.0 label is actually justified: At the very least, the package should be fully documented and have good test coverage. I’d even say it should fulfill standards similar to that of a JOSS submission.

The problem with making General very restrictive is that (despite everyone’s claims how great Pkg is compared to, e.g., Python packaging), Julia’s support for non-registered packages is, frankly, terrible. You are almost certain to run into severe issues if you ever have something that depends on an unregistered package. I’ve moved to using a local org registry to avoid most of these problems, but even that isn’t ideal. There would be some ways to improve the situation:

• Have a lower-tier “test”/“experimental” registry that’s also available to Julia by default and has very minimal requirements for automatic registration (basically anything will be auto-merged as long as it installs and doesn’t conflict with any existing names)
• Add support for recording non-default registries in Project.toml: this would get around having to put “Run pkg"registry add <repository url>" before instantiating this project:” in my project README (which people will miss and then be confused)
• More generally, add support for specifying the location of unregistered packages in Project.toml: Source of packages should be recorded in the manifest · Issue #378 · JuliaLang/Pkg.jl · GitHub

If Pkg can be significantly improved so that working with packages not in General actually becomes feasible, then by all means: add more quality control to General. Until then, though, all that requiring 1.x for auto-merging is going to do is to make people change the initial version of their barely functional new package to 1.0 just to make the bot happy. I don’t think that’s something anyone would like to encourage.

[Elrod]

@goerz

In principle, you could make General more restrictive, but I think that should mean putting actual quality control into what can be registered to make sure that the v0.1.0 label is actually justified: At the very least, the package should be fully documented and have good test coverage. I’d even say it should fulfill standards similar to that of a JOSS submission.

I disagree, a sentiment I expressed before here.
Stricter policies would heavily used libraries like FunctionWrappersWrappers would instead exist as undocumented code inside SciMLBase.jl, or something similar.
I prefer having the flexibility of placing that code in its own repo instead.
The library currently has 7 direct and 369 indirect dependencies.
The people I created it for obviously have no trouble using it, and I don’t have a reason to care about anything else.
I have zero intention to publish in JOSS.

I don’t see why a package like this should be banned, forcing further centralization into aggregate packages.

[goerz]

Would it really hurt to add a paragraph or two of documentation to the README?

[jules]

If we start requiring 1.0.0 for merging into General, we weaken the signal of version numbers >=1 because our ecosystem has just been built around starting at 0.1. It doesn’t really matter though, I think the “signaling” part is very overrated and other cues for maturity are much more relevant. Also, even breaking releases aren’t all the same. In Makie, we have made small and big breaking releases, we always tag breaking if it’s technically so but the effort for users to keep up can vary a lot. I don’t like holding development back or bundling such updates over a longer time just to reduce the number of breaking releases, I think the amount that Makie breaks will only reduce the more problems we work out, not because we decide “no more breakage” and move to 1.0 for some psychological reason. The bugs and problems would still be there.

[simsurace]

My view on this as someone who depends on Julia packages in a professional development/production environment:

• If we were only allowed to use packages past 1.x.y, we wouldn‘t get anything done. Many cornerstones of the ecosystem are fairly mature, but are still in version 0.x.y. I would like to see them move to v1 while making those long overdue breaking changes that would also remove some technical debt, but I understand that everyone is busy with more important stuff or that sometimes it is hard to achieve consensus about these matters.
• To prevent things from constantly breaking in development, we use compat bounds that exclude breaking releases. If everyone uses semver properly, this will keep things fairly stable. Most of the time when something breaks, it is accidental, and there is little that can be done to prevent that except better tests and more people reviewing. People also depend on internals of other packages, which accounts for many bugs and could be avoided at the cost of perhaps slower development in some cases.
• Because of compat, moving to breaking releases is a somewhat conscious effort. I think that‘s good, even though it is not the most exciting type of work.
• In production, freezing everything (Julia version, manifest) is almost mandatory because of those accidental bugs creeping in otherwise.

I don‘t think that changing the registry policy would solve any of the above problems, but it would create additional friction for developers. Registering for me is about ease of distribution and installation, and encourages experimentation and testing. One can always restrict a package version to stay wherever it is currently, until it creates an unresolvable constraint, and this can make even experimental packages stable. My bigger concern is that very good packages get abandoned for various reasons and the ecosystem evolves past them to the point where they become unusable.

[e3c6]

@Eben60

if the package is already used by many other registered packages

As far as I understand, it’s impossible that a registered package depends on non-registered packages.

[Palli]

@Elrod

To be serious for a moment, I don’t want to create a breaking release for no reason. But I’ll definitely consider starting at 1.0 for the next package I register.

Would it be possible to relax the rule about 1.0 being a breaking change? I.e. from now on it could signal people are somehow happy with their package, and can then go from 0.x to 1.0 without a breaking change. And then in case you need a breaking change go straight to 2.0?

[Mason]

@Palli

And then in case you need a breaking change go straight to 2.0?

You wouldn’t go straight to 2.0, you’d first go to 0.(x+1) and then immediately tag 1.0 after that with the same code, like what we did with Julia 0.7 and 1.0 releasing simultaneously.

[mbaz]

Wild suggestion: 1.0 must not be breaking, but rather it must be compatible with 0.x for the largest x on the registry. A compat bound ^1 would include the range 1.x to 0.1, so packages would update to 1.0 transparently. Packages depending on 0.z can specify that explicitly.

[goerz]

This. A hundred times Yes.

[GunnarFarneback]

@e3c6

As far as I understand, it’s impossible that a registered package depends on non-registered packages.

The General registry has this policy, for very good reasons. It’s not a requirement from the package manager though and other registries could do things differently if they want. However, for most private registries it would still be recommended to have all dependencies in either the own registry or in General.

[Eben60]

" used by" - in passive.

Meaning e.g. if many other registered packages already depend on one’s package, currently e.g. in version 0.3.4, for a year or two, the package author should consider moving to version 1.0, even if (s)he doesn’t consider the API perfectly stable yet.

[stevengj]

@simsurace

If we were only allowed to use packages past 1.x.y, we wouldn‘t get anything done. Many cornerstones of the ecosystem are fairly mature, but are still in version 0.x.y. I would like to see them move to v1 while making those long overdue breaking changes that would also remove some technical debt

I think you are misunderstanding the proposal.

• 0.x versions would still be allowed, but would require manual merging for new packages, and perhaps for old packages if x is incremented (= breaking releases). So, if you have a good reason to use a 0.x version it will still be okay, it’s just that 0.x would just get registered a little more slowly.
• The reason we want versions ≥ 1.0 is that they provide more information in semver — you can do breaking upgrades (1.x → 2.0), non-breaking feature upgrades (1.1 → 1.2), and non-breaking bugfixes (1.1.3 → 1.1.4). In contrast, 0.x versions provide strictly less information because you can only do breaking (0.1 → 0.2) and non-breaking (0.1.3 → 0.1.4) releases.
• 1.x doesn’t need to be a perfect release that is set in stone forever. You can always increment the first digit. The whole argument here is that people are artificially setting too high a bar for 1.0 versions, and as a result a lot of longstanding packages are still at 0.x
• The fact that “cornerstones of the ecosystem” are still at 0.x is a problem, because they have lots of dependencies but their version upgrades provide too little information (see above). It would be better for the ecosystem if they tagged their next breaking release (0.15 → 0.16) as 1.0 (0.15 → 1.0) instead, even if they still plan future breaking changes.

TLDR: Once other people depend on your package, you want a ≥ 1.x version just because it provides more information in semver, even if you expect future breaking changes. Disabling auto-merging would gently encourage this but would not require it.

A more conservative change would be to disable registry auto-merging of breaking 0.x upgrades (e.g. 0.15 → 0.16) for any package that has downstream dependencies, with a message suggesting that they tag the breaking release as 1.0 instead. (Again, manual merging/registering would still be allowed!)

[e3c6]

@mbaz

Wild suggestion: 1.0 must not be breaking, but rather it must be compatible with 0.x for the largest x on the registry. A compat bound ^1 would include the range 1.x to 0.1, so packages would update to 1.0 transparently. Packages depending on 0.z can specify that explicitly.

I think changing the meaning of semver (even just for 1.0) at this point would be a massively breaking change on the ecosystem.

[e3c6]

@stevengj

• The whole argument here is that people are artificially setting too high a bar for 1.0 versions, and as a result a lot of longstanding packages are still at 0.x

This is exactly my feeling. There is a subjective appreciation of what 1.0 means, that is entirely artificial.

[lmiq]

@stevengj

people are artificially setting too high a bar for 1.0 versions, and as a result a lot of longstanding packages are still at 0.x

What I think does not close here is the fact that these “people” are, particularly for these important packages, very experienced developers and contributors to the Julia ecosystem. And they are aware about the semver differences. These “people” are following this thread and, for some reason, have not yet just updated their packages to 1.0.0. Some may be good reasons, some not, but these are all people quite aware of the issues involved.

Creating a barrier, even if only psychological, to the registration of 0.X versions will have an effect on new contributors, which (I speak by my own experience), feel more conformable in registering 0.X versions in the process of learning both programming (in Julia and in general), and the workings of package registering. As feel it, having possibly a series of 1.X, 2.X, 3.X etc. which are useless and full of bugs to then have a 14.X version which is the one actually useful and ready to prime time does not feel right. One may say that these buggy versions should not be registered, but then I insist that registering is part of the learning curve to contributing to the ecosystem, and also for a real-life testing, even if only for a small set of users heavily involved in the package development. I think it is better to have good software tagged 0.X than to have bad software with stable major releases.

If anything, I think that in the process of registering a 0.X package the author could receive an encouraging automatic message to register a 1.X version as soon as possible, for the reasons mentioned above.

[stevengj]

@lmiq

If anything, I think that in the process of registering a 0.X package the author could receive an encouraging automatic message to register a 1.X version as soon as possible, for the reasons mentioned above.

I suspect that would be better accomplished by my alternate suggestion above:

@stevengj

A more conservative change would be to disable registry auto-merging of breaking 0.x upgrades (e.g. 0.15 → 0.16) for any package that has downstream dependencies, with a message suggesting that they tag the breaking release as 1.0 instead. (Again, manual merging/registering would still be allowed!)