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.
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
- Sync the old package and documentation as
- Inform about deprecating the old package as a last minor version
2.5with warning messages, publish documentation that has information about the upgrade
- Deprecate the old package and publish the rewritten version as
3.0and 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.
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.