Renaming a Plugin

Leseratte_10 · 09-05-2022, 01:42 AM

Hello everyone,

I've got a quick question, is there a good way to rename an existing plugin?
My ACSM Input Plugin used to be called "DeACSM" for the first couple versions, but then I wanted to re-name it to "ACSM Input" so it's named more like all the other file-type plugins (KFX Input, DOC Input, KePub Input, ...).

I found that the plugin index thread contains a section about deprecated and renamed plugins, but I don't fully understand that:

Quote:

The following plugins should be removed from your system as they have been superseded by newer plugins above or other reasons listed. They are listed here both for your interest and for use by the Calibre Plugin Updater which will advise you to remove these if they are installed (and automatically uninstall them if you install their replacement).

So if I mark the old name "DeACSM" as deprecated and put the plugin onto that list with a new name ("ACSM Input"), A) How does Calibre know to automatically uninstall the old plugin upon installation of the new one?, and B) is there a way to get this to work automatically?

Right now it looks like if I were to do that, then everyone who is currently using my plugin would get it auto-removed and would need to search for and redownload it under the new name through the plugin search. I have not found a way to mark it as "hey, ACSM Input is just the new name for DeACSM, just replace it".

Does such a functionality exist? What's the best way to rename a plugin without causing issues for users?

EDIT: Sorry for this file attachment, I'm just testing something with the calibre plugin updater, please ignore ...

kovidgoyal · 09-05-2022, 01:49 AM

It is only auto removed if the user installs the replacement. Which the plugin updater advises the user to do when a replacement exists.

Leseratte_10 · 09-05-2022, 02:02 AM

Thanks for the quick response. I got that part, yes. But in order for that to work I'd need some place to mark "Hey, the plugin 'ACSM Input' *is* the replacement for the old deprecated plugin 'DeACSM' - don't I?

What would be the exact steps I'd need to do to rename my plugin?
Just change the "name" entry in the class, rename the ZIP file in the Mobileread thread, have a moderator edit the name of the entry in the plugin index and the updater will take care of the rest (because it notices the thread ID is the same but the name changed)?

Or do I need to add an entry to the "deprecated" section of the plugin index thread, even though the old Plugin thread URL and the new Plugin thread URL would be identical?

kovidgoyal · 09-05-2022, 03:07 AM

You will need to create a new thread. The index will need to be updated to move the old thread into the deprecated section, and a new entry will be created for the new thread, which will have the "Uninstall: Old Plugin Name" in its metadata. The plugin updater will use that to auto-uninstall the deprecated plugin when the new one is installed.

And you should of course edit the first post in the old thread with a link to the new plugin thread.

Leseratte_10 · 09-05-2022, 01:01 PM

Okay, I've spent a loooot of time with this problem and I believe I found a solution.

I tried to hand-craft a plugins.json.bz2 to see how Calibre behaves when encountering a deprecated plugin - but all the updater offered was to remove the deprecated plugin. It did not automatically offer to install the new one (which is what I hoped - a section in the plugin metadata that says "uninstall me and install replacement X"). That would be annoying as then everyone would need to manually download the new plugin either through a plugin search or from the new forum thread.

It looks like Calibre will auto-remove the old deprecated plugin when I install the new one, but it does not offer the user an auto-update from the old deprecated plugin to the new one.

So, I decided to implement a hack-y little trick to avoid A) having to make a new thread and B) having users have to re-install the renamed plugin:

- I've created a new build of my plugin that has the new name, a higher version number, and a bunch of install / migration code.
- I will attach that new build both to my plugin's thread, as well as to this thread I'm currently posting in.
- I will update (or rather, have a moderator update) the plugin index thread so that both the old and the new plugin are in there as non-deprecated plugins. The old one "DeACSM" will point to this thread, the new one "ACSM Input" will point to my plugin's thread. Of course the plugin description will be labelled accordingly so users don't get confused why this is there twice.

Then, the following steps should happen, if I tested this correctly:
- Calibre finds an update for the "DeACSM" plugin which gets downloaded from this thread.
- In this thread's ZIP, there's the new plugin that's actually already named "ACSM Input"
- Upon upgrading from the old installed version to this one, the plugin gets installed under the old "DeACSM.zip" name by Calibre (because that's what Calibre thinks it's installing).
- Then, it's initialization method copies the "DeACSM.zip" (which is now the new plugin) to "ACSM Input.zip" and restarts Calibre.
- At that point Calibre loads the new "ACSM Input" plugin from the ZIP file, and future updates will again come from the original thread of my plugin.

This has the disadvantage that I cannot yet label the "old" DeACSM plugin as deprecated in the plugin index (as then the migration to the new one would never happen; but it has the advantage of being completely seamless to the user, without him having to re-install the new plugin.

During my tests with a modified plugins.json.bz2 that worked just fine, so I hope it will work with the "official" one, too.

I hope that this is okay with the forum moderators, as it would mean my plugin would "occupy" two entries in the plugin list (neither of which can be in the "deprecated" section), and I would also need to "abuse" this particular thread to host my "migration build" of my plugin that moves everything from "DeACSM" to "ACSM Input"; but hey, this thread already exists anyways so that shouldn't be an issue - right?

kovidgoyal · 09-05-2022, 01:09 PM

Seems awfully complex and fragile. Why not just create a new plugin named ACSM Input. Publish it separately. Push an update to your old plugin that pops up a dialog telling the user to install acsm input instead, it can just have an OK button which when clicked will install acsm input automatically using calibre apis.

Then after a couple of moths you can deprecate the old plugin, the vast majority of your users will have migrated.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Renaming styles?	Phssthpok	Editor	2	07-17-2021 07:52 AM
Goodread Perception Expander plugin not shown on plugin list (kobo h2o)	www	KOReader	4	09-28-2017 10:34 AM
Renaming error	geminii_77	Calibre	7	07-31-2013 09:16 AM
Renaming help	fairuza	Calibre	3	11-27-2010 02:13 PM
Need your help renaming!	GatorDeb	Kindle Formats	1	08-01-2009 05:47 PM

09-05-2022, 01:49 AM	#2
kovidgoyal creator of calibre Posts: 44,017 Karma: 22669822 Join Date: Oct 2006 Location: Mumbai, India Device: Various	It is only auto removed if the user installs the replacement. Which the plugin updater advises the user to do when a replacement exists.

09-05-2022, 02:02 AM	#3
Leseratte_10 Groupie Posts: 182 Karma: 2010542 Join Date: Sep 2021 Device: PB Era, PB InkPad 3 Pro	Thanks for the quick response. I got that part, yes. But in order for that to work I'd need some place to mark "Hey, the plugin 'ACSM Input' is the replacement for the old deprecated plugin 'DeACSM' - don't I? What would be the exact steps I'd need to do to rename my plugin? Just change the "name" entry in the class, rename the ZIP file in the Mobileread thread, have a moderator edit the name of the entry in the plugin index and the updater will take care of the rest (because it notices the thread ID is the same but the name changed)? Or do I need to add an entry to the "deprecated" section of the plugin index thread, even though the old Plugin thread URL and the new Plugin thread URL would be identical?

09-05-2022, 03:07 AM	#4
kovidgoyal creator of calibre Posts: 44,017 Karma: 22669822 Join Date: Oct 2006 Location: Mumbai, India Device: Various	You will need to create a new thread. The index will need to be updated to move the old thread into the deprecated section, and a new entry will be created for the new thread, which will have the "Uninstall: Old Plugin Name" in its metadata. The plugin updater will use that to auto-uninstall the deprecated plugin when the new one is installed. And you should of course edit the first post in the old thread with a link to the new plugin thread.

09-05-2022, 01:01 PM	#5
Leseratte_10 Groupie Posts: 182 Karma: 2010542 Join Date: Sep 2021 Device: PB Era, PB InkPad 3 Pro	Okay, I've spent a loooot of time with this problem and I believe I found a solution. I tried to hand-craft a plugins.json.bz2 to see how Calibre behaves when encountering a deprecated plugin - but all the updater offered was to remove the deprecated plugin. It did not automatically offer to install the new one (which is what I hoped - a section in the plugin metadata that says "uninstall me and install replacement X"). That would be annoying as then everyone would need to manually download the new plugin either through a plugin search or from the new forum thread. It looks like Calibre will auto-remove the old deprecated plugin when I install the new one, but it does not offer the user an auto-update from the old deprecated plugin to the new one. So, I decided to implement a hack-y little trick to avoid A) having to make a new thread and B) having users have to re-install the renamed plugin: - I've created a new build of my plugin that has the new name, a higher version number, and a bunch of install / migration code. - I will attach that new build both to my plugin's thread, as well as to this thread I'm currently posting in. - I will update (or rather, have a moderator update) the plugin index thread so that both the old and the new plugin are in there as non-deprecated plugins. The old one "DeACSM" will point to this thread, the new one "ACSM Input" will point to my plugin's thread. Of course the plugin description will be labelled accordingly so users don't get confused why this is there twice. Then, the following steps should happen, if I tested this correctly: - Calibre finds an update for the "DeACSM" plugin which gets downloaded from this thread. - In this thread's ZIP, there's the new plugin that's actually already named "ACSM Input" - Upon upgrading from the old installed version to this one, the plugin gets installed under the old "DeACSM.zip" name by Calibre (because that's what Calibre thinks it's installing). - Then, it's initialization method copies the "DeACSM.zip" (which is now the new plugin) to "ACSM Input.zip" and restarts Calibre. - At that point Calibre loads the new "ACSM Input" plugin from the ZIP file, and future updates will again come from the original thread of my plugin. This has the disadvantage that I cannot yet label the "old" DeACSM plugin as deprecated in the plugin index (as then the migration to the new one would never happen; but it has the advantage of being completely seamless to the user, without him having to re-install the new plugin. During my tests with a modified plugins.json.bz2 that worked just fine, so I hope it will work with the "official" one, too. I hope that this is okay with the forum moderators, as it would mean my plugin would "occupy" two entries in the plugin list (neither of which can be in the "deprecated" section), and I would also need to "abuse" this particular thread to host my "migration build" of my plugin that moves everything from "DeACSM" to "ACSM Input"; but hey, this thread already exists anyways so that shouldn't be an issue - right?

09-05-2022, 01:09 PM	#6
kovidgoyal creator of calibre Posts: 44,017 Karma: 22669822 Join Date: Oct 2006 Location: Mumbai, India Device: Various	Seems awfully complex and fragile. Why not just create a new plugin named ACSM Input. Publish it separately. Push an update to your old plugin that pops up a dialog telling the user to install acsm input instead, it can just have an OK button which when clicked will install acsm input automatically using calibre apis. Then after a couple of moths you can deprecate the old plugin, the vast majority of your users will have migrated.

Advert

Advert