I have rewritten a package that has been abandoned for a while now. The previous package is in active use, but has problems. It is a client of another API and does not provide all the functions that the underlying API supports. And its documentation, the repository and the version of GitHub are not synchronized with each other, which is very confusing for new users, including me when I tried it for the first time.
I have acquired rights to manage the launch and also for the Read The Docs project site soon. Now I am struggling with what to do with the publication of the new package and the care of the previous package. This is what I and some helpful contributors have considered:
The original package must be synchronized
It is currently out of sync, which means that the repository contains code that has not been published. But it has been incorporated into the online documentation! Therefore, package users have essentially incorrect code and the only way to update is by cloning the repository. Synchronization would mean releasing the final contents of the repository as new minor versions of the package and documentation.
The rewritten package must be the next major version
This is subject to debate. It is based on the previous one, although it is almost completely incompatible with previous versions due to name changes and refactorings in the client. It could be said that it could be launched with a different name, which would avoid confusion when updating and providing a clean start for our package. Some applications may also break if they are updated recklessly.
On the other hand, the users of the previous package would be hung up. Without an update, the library will slowly become obsolete. Our rewriting 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 an established user base already exists, so discovery should not be a problem.
So far I have been convinced that we should launch the package with the same name as the next major version. Based on that, I have devised a plan to update the package. The current released version is
- Synchronize the previous package and documentation as
- Disapprove the previous package as a last minor version
2.5 with warning messages, publish documentation that has information about the update
- Publish the rewritten version as
3.0 and continue the development
For me, updating the version and breaking the incompatibility with previous versions doesn't sound too bad. The original package must be updated. After all, we are issuing warnings and the version requirement can be specified. After reading about the semantic versions, the fact that incompatible backward changes can be made, which are not the most evil thing in the world, was reinforced.
Still, I turn to you for advice. Is this a sensible plan? If not, What would be the correct way to proceed? I want to respect the previous package and its users, whether they want to update or not. But I think letting the old package rot is not the way to go.
Here is my original question on the subject of starting to maintain the old repository. If you are interested in details, here is our problem about the update plan.
I originally asked this question in Open Source SE, but I thought it might be a more appropriate forum, since it is not limited to open source projects. Let me know if it is also off topic here, and if I could be elsewhere, although I think it falls into the category of software launch.