1. Obsolete feature management

As in any software, some Scilab features get deprecated over time. The transition is done through a Major or Medium release (depends on what will be the next release).

Taking an obsolete feature OldFunction available in the version {X.Y}-2. OldFunction will be tagged as obsolete in version {X.Y}-1 to be actually removed in version X.Y
NewFunction is now providing the feature.

The procedure is the following.

1.1. Replacement function

Provide a replacement function as macro or C-code.

1.2. Obsolete function source code

Indicate obsolete status in the deprecated function source code. The deprecated function must remain working, documented and available.

If the function is a macro then you have to call the warnobsolete function to explain:

• When this feature will be removed
• How to replace it

The help page for warnobsolete is available here: << TODO >>

Here is an example of use of warnobsolete:

warnobsolete("NewFunction", "6.0");

with NewFunction being the name of the replacement function and 6.0 the number of the next major release.

If the function is a gateway then you have to use sciprint to explain:

• When this feature will be removed
• How to replace it

Here is an example of use of sciprint in this case:

sciprint(_("%s: Feature %s is obsolete.\n"), _("Warning"), fname);
sciprint(_("%s: Please use %s instead.\n"), _("Warning"), "NewFunction");
sciprint(_("%s: This feature will be permanently removed in Scilab %s\n\n"), _("Warning"), "6.0");

1.3. CHANGES_{X.Y}-1 file

Add an item about this obsolete function into the CHANGES_{X.Y}-1 file.

* 'OldFunction' is obsolete and will be removed in Scilab 6.0, please use '!NewFunction' instead.

1.4. Obsolete function documentation

In the help page of the obsolete function, you have to do some updates.

First you have to modify the <refnamediv> part:

  <refnamediv>
    <refname>OldFunction</refname>
    <refpurpose>Returns a value.</emphasis>
    </refpurpose>
  </refnamediv>

will become:

  <refnamediv>
    <refname>OldFunction (Obsolete)</refname>
    <refpurpose><emphasis role="bold">This function is obsolete and will be removed in Scilab 6.0.</emphasis> Please use <link linkend="NewFunction">NewFunction</link> instead.</refpurpose>
  </refnamediv>

The old <refpurpose> contents has to be moved to the Description <refsection> if not already part of it.

Then a History <refsection> has to be created at the end of the help file (or modified if it already exists):

  <refsection>
    <title>History</title>
    <revhistory>
      <revision>
        <revnumber>5.4.0</revnumber>
        <revremark>This function is obsolete and will be removed in Scilab 6.0.</emphasis> Please use <link linkend="NewFunction">NewFunction</link> instead.</revremark>
      </revision>
    </revhistory>
  </refsection>

Do not forget to add a link to the replacement function NewFunction in the See also <refsection>.

1.5. New function documentation

If it is relevant, in the replacement function documentation, explicit the fact that this function replaces the deprecated one.

1.6. X.Y release

During the release process of X.Y:

• Remove the actual obsolete function
• Update the documentation

• Update the CHANGES_X.Y to show that the function OldFunction has been removed and replaced by NewFunction

Note a deprecation process can not be done over a minor release.