About News Download Docs Bugs Contact





Spell deprecation process


Sometimes spells need to be removed in favor of other spells, e.g. when an application gets renamed. This should happen automatically for users that have the spell installed. Here's how to do this:

If a spell simply doesn't build for a long time it should be just removed, otherwise the casting of the deprecated spell would remove it also for the people that still have a working install (built long ago).


Note: you can use Quill to deprecate, remove and rename spells. Run quill -u <spell> and use the deprecation menu options.

Here is a low-level description of the process ("<old>" is the spell to be removed, "<new>" is the spell that replaces it):

When this process is used, a user casting the deprecated <old> will get <new> installed, removing <old> in the process.

If the old spell had PROVIDES, don't delete it. Otherwise the spell changeover/removal will happen as soon as something that depends on the particular provider is cast. Keeping it is useful for people who have the old spell installed and don't want to switch to the new spell or in case of removal, that want to continue using the old spell (they have it installed from the times the spell was OK).

However, this can cause trouble for the people that already switched the provider, since the queries will also show the old spell. So this should only be used for a grace period after the deprecation, let's say a week or a month. Users who want to keep the old spell and keep it as a provider are encouraged to copy it to a local grimoire with scribbler, readd the PROVIDES file and run scribe reindex over that grimoire.

Change all the spells that depended in any way on the deprecated spell to either point to the new one or simply remove the depends if it isn't needed anymore.

Deprecated spells should be removed from the test grimoire once the deprecation has made its way to stable.

What else?

If the deprecation is a rename, and the old spell had some persistent variables from configuration settings (CONFIGURE or PREPARE), you should transfer those settings as defaults to the new spell. Basically, no user settings should be lost.
So how do you do that?