LightGraphs is currently at v1.3.1. We’ve made some really big changes to the LightGraphs API in the master branch, and have added deprecation warnings for all old functions. The deprecation warnings apply to almost all of the existing codebase and slow things down tremendously.
We were planning on releasing 1.4.0 with the deprecation warnings, but some discussions on Github made me realize that this might not be the right approach, since users who do a package update will get 1.4.0 (since it’s non-breaking) but then will have warnings (and their associated performance penalties) all over the place even if they don’t use LightGraphs directly, if any of their other installed packages use LightGraphs. This is, as one person put it, not a good user experience.
So the way I see it, there are three options, and I don’t particularly like any of them:
- Release 1.4.0 with deprecations, and 2.0.0 with the deprecations removed. This produces the user experience problem described above.
- Release 2.0.0 with the deprecations, and 2.1.0 with the deprecations removed. This may break SemVer, and will break any code that goes to 2.1.0 directly without having had the benefit of the depwarns in 2.0.0 (if we release 2.0.0 and 2.1.0 simultaneously, 2.0.0 essentially will be skipped by anyone who moves to v2).
- Release 2.0.0 with the deprecations, and 3.0.0 with the deprecations removed. This is just silly - we’re wasting an entire major version number.
When Julia was at 0.7/1.0, it was a bit of a different story since it was pre-1.0 and SemVer rules (even Julia’s interpretation of them) are different.
What should we be doing post-1.0? Is there a better option here that I haven’t considered?
You cannot do option 2. You are not permitted to making any breaking changes between 2.0.0 and 2.1.0.
4 Likes
What’s wrong with option 3? Each component of a version number is an unsigned 32-bit integer. So there really isn’t such a thing as “wasting” a major version number.
Also, what’s wrong with option 1? Is the only performance impact from these deprecation warnings? If so, end-users can simply turn off deprecation warnings with a command-line flag.
I would probably go with option 3, especially if the performance impact from these deprecation warnings is significant.
But, both option 1 and option 3 are compliant with SemVer. But option 2 is not - if you make a breaking change, SemVer says that you MUST increment the major version number.
2 Likes
Choosing from the above, I would go for option 1, making sure that 1.4 and 2.0 are released at the same time, so the users who are bothered by the deprecations have an option to upgrade.
That said, I probably would not bother to deprecate at all, just make a breaking release, and write up a nice transition guide, linked from the CHANGELOG. With the way Pkg and the registrator handle SemVer, deprecations make little sense anyway; when you bump the versions you will be using the new API.
6 Likes
See also https://github.com/JuliaLang/julia/pull/35362 which would make this easier. Maybe you don’t want to wait for Julia 1.5 though.
With that you should be able to just release 1.4 and then just keep the deprecations around until 2.0.
3 Likes
What about placing the deprecations in a separate branch and releasing 2.0.0 with the deprecations removed? Then the upgrade procedure would be to add LightGraphs#deprecations, fix the deprecations, and upgrade to LightGraphs 2.
3 Likes
Thanks for all the advice and information. I think @GunnarFarneback’s idea – specifically, to have a separate branch for developers who need to migrate existing code – is probably the easiest to implement.
Having a 2.0.0 version that has no future upgrades (option 3) will be confusing in the long run. It also has the potential to disrupt our “supported versions” policy.
The point that someone made (that prompted this post) is that performance regressions and warning messages are really disruptive to end users and could arguably be considered breaking in their own right. I don’t know how strongly I agree with this but I do think that doing a package upgrade should not result in dozens/hundreds of depwarns and worse performance.
Again, thanks for the feedback. In retrospect, including deprecations was probably a mistake. The time would’ve been better spent improving the upgrade documentation and creating a special upgrade guide (which we’re going to have to do anyway).
Look for LightGraphs 2.0 later this summer 
2 Likes