I have rewritten a package that has been abandoned for a while now. The old package is in active use, but has problems. It is a client of another API, and does not provide all features that the underlying API supports. And its documentation, GitHub repository and release are out of sync with each other, which is very confusing for new users, including me when I first tried it out.

I have acquired rights to manage the release and also to the Read The Docs site of the project soon. Now I'm struggling with what to do with publishing the new package and taking care of the old package. This is what I and some helpful contributors have considered:

The original package should be synced

It is currently out of sync, meaning the repository contains code which has not been released. But it has been built into online documentation! So users of the package have essentially incorrect code and the only way to upgrade is cloning the repository. Syncing would mean releasing the final contents of the repository as new minor versions of the package and documentation.

The rewritten package should be the next major version

This one is subject to debate. It is based on the old one, though almost completely backwards incompatible due to name changes and refactorings in the client. Arguably, it could be released under a different name, which would avoid confusion when upgrading and provide a clean start for our package. Some applications could also break if upgraded recklessly.

On the other hand, users of the old package would be left hanging. Without an upgrade the library will slowly become obsolete. Our rewrite is complete with respect to the underlying API and in my humble opinion is written in better style. For the new package this could be advantageous in the sense that there is already an established user base, so discovery shouldn't be a problem.

The plan

Thus far I've been convinced that we should release the package under the same name as the next major version. Based on that I've devised a plan of updating the package. The current released version is 2.4.4.

  • Sync the old package and documentation as 2.4.5
  • Inform about deprecating the old package as a last minor version 2.5 with warning messages, publish documentation that has information about the upgrade
  • Deprecate the old package and publish the rewritten version as 3.0 and continue development

To me, upgrading the version and breaking backwards incompatibility do not sound that bad. The original package should be updated. After all, we are issuing warnings and the version requirement can be pinned down. After reading on semantic versioning the fact that backwards incompatible changes can be made, that they are not the most evil thing in the world, was reinforced.

Still, I turn to you for advice. Is this a sensible plan? And if not, what would the correct way to proceed be? I want to respect the old package and its users, whether they want to upgrade or not. But I think letting the old package rot is not the way to go.

Here is my original question on the topic of starting to maintain the old repository. If you're interested in specifics, here is our issue on the upgrade plan.

I originally asked this question on Open Source SE, but thought this might be a more appropriate forum, as it is not limited to open-source projects. Let me know if it is off-topic here as well, and if it could be on-topic somewhere else, although I believe it falls within the category of releasing software.

  • I think the biggest issue with your plan is removing features without a deprecation period. If it's possible to leave the legacy API intact, but provide deprecation notices (for at least a few minor versions), that would be much closer to library management best practice. – robinsax Dec 1 at 19:17
  • @robinsax That's a very good point, thank you! Considering that the rewrite took almost everything, it might be hard to apply in this context but I'll se what I can do. – Felix Dec 2 at 18:16
  • @robinsax Or maybe I wasn't clear in my plan, which I edited just now. I would only inform about the deprecation in the final minor version of 2. Then at version 3 I would deprecate the functionality and introduce the rewritten version. – Felix Dec 2 at 19:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.