Impacts/advice for changing package name in 1.0 release

Hi there!

I just took over maintainership of docopt-ng, which is a jazzband-maintained fork of the popular but abandoned docopt.

When fork was originally forked, they distributed it as docopt-ng (ie pip install docopt-ng), so as not to clash with the existing docopt. BUT, they made what I think was a tragic decision to keep the package name the same, so you still import it as import docopt. This makes it impossible to install both libraries in the same environment, since you don’t know which docopt you get when you import docopt.

What are the solutions here? I assume it’s to do a breaking change in a 1.0 release and change both the distribution name and package name to something like docopt2. Do you know of any projects that have done this, so I could see how that went and maybe learn a lesson or two? Any other advice?

Thanks all!

References:

2 Likes

You could distribute a shim docopt module that just wraps your renamed docopt_ng or etc, and raises a deprecation warning – that would allow a longer transition period. Not sure what you are referring to by changing the distribtution name, I assume you’d still pip install docopt-ng?

A

Not exactly the same situation, but skimage · PyPI is an example of a shim / dummy package for scikit-image · PyPI (imported as import skimage).

On the other hand opencv-python · PyPI (imported as import cv2) does not have any such shims.

Both seem very confusing, inconvenient, and potentially dangerous (supply chain attacks), but will probably never be fixed for practical reasons.

A prominent example of a similar situation is Pillow, an imaging library. It originated as a fork of PIL, but even now, more than a decade later, it is imported with “import PIL”.

Ask for a claim to the name on PyPI if abandoned.

The shim module is a good idea, if I change the name then this will probably be the route I follow.

I figured that while I was changing the package name, I might as well also change the distribution name so that both names match (seems sane, and recommended by the [non-accepted] PEP 423). I could shim the distribution name as well as Peter Suter suggests following the skimage → scikit-image shim. If a user has to make the change in their code for the package rename, I figure it would be minimal additional work to also update the distribution name.

A prominent example of a similar situation is Pillow, an imaging library. It originated as a fork of PIL, but even now, more than a decade later, it is imported with “import PIL”.

Great point. So that’s evidence that just keeping things exactly how they are is feasible.

Ask for a claim to the name on PyPI if abandoned.

The original docopt is too popular still to pull the rug out from underneath all the folks still using that.

Still waiting a bit longer to see if anyone else chimes in before I make a decision…

1 Like

One downside of renaming is splitting the audience. Many, many users/libraries don’t update to the new name and keep using the old one.

For example, the original, abandoned docopt has 12 million downloads per month. The new docopt-ng fork has 162k downloads per month.

If you create a new docopt2 package, expect another big drop in users.

My advice is to keep the names you have, to best serve your users.

I would even consider claiming the abandoned docopt name (see PEP 541) and re-start using that as the canonical name (with a shim for the fork).

4 Likes

This doesn’t do that at all; rather, it benefits them by allowing them to take advantage of your maintenance and improvements (if they choose) without having to switch to a totally new distribution package. If its been over a year since the last release and the maintainer can’t reasonably be reached (or can and okays it), then it can be all yours.

docopt-ng has several breaking changes as compared to docopt, plus the versioning is going to be inconsistent between them, so if someone’s requirements.txt, still saying docopt, suddenly begins pointing to my fork, then their code is going to inexplicably break. Unless I’m missing something that you’re saying?

I think that’s perfectly acceptable as long as you do a major version bump. In fact, I think this is the right thing to do.

4 Likes

If docopt development had continued, it would inevitably released a new major version with breaking changes, unless its goal was 100% backward compat with every previous version of docopt forever. Therefore, what you would be doing is no different form the original project, if it was still being developed (or development resumed at some point). That’s what major versions are for in semver, and many projects release breaking changes without even doing that.

Yes, of course, but you just make your first new release to the existing PyPA project name a new major version relative to the current docopt version.

If they haven’t upper capped it to at least the current major version, yes, but the same would be true if and when the original docopt authors released a new major version with breaking changes, and that’s on them, not yet. And its not that; inexplicable, if they aren’t upper capping their dep versions properly, then their library/application would almost certainly broken before due to breaking changes in a dependency.

Releasing a pre-release (alpha, beta, rc) could help devs ensure their versions are either upper capped or compatible, assuming they are paying attention as they should.

4 Likes

OK, thanks for the input. I emailed the original maintainer of docopt to see what they think about transferring the name on PyPI. Hopefully PEP 541 doesn’t have to come into it at all!

3 Likes

I also support the idea of name transfer or PEP 541 (if necessary). It’s in the best interest of users and the supply-chain who may have an unsupported dependency without awareness. Having a fresh maintainer come along is healthier, even if it does temporarily break certain unpinned builds because it highlights to the user that they have 2 options: update their code to a new supported version or pin to an unsupported version.