String deprecation

String deprecation
Project state	Implemented
Tracker issue	MDL-46585
Discussion
Assignee	Marina Glancy

Moodle 2.8

Since Moodle 2.8, strings can be deprecated in a very similar way to how functions are being deprecated. This feature allows us to safely remove strings once we are pretty sure they are no longer used. The process should help to remove unnecessary strings from the language packs (so translators do not spend valuable time by translating them for no real profit) while protecting us from accidentally removing a string that is still being used somewhere.

How it works

There is a file with the list of deprecated strings. When a deprecated string is used (typically via the get_string() call), the warning is displayed. Something like this:

   String [identifier,component] is deprecated. Either you should no longer be using that string,
   or the string has been incorrectly deprecated, in which case you should report this as a bug.

Note that this warning is displayed at the DEBUG_DEVELOPER level only (which is what Moodle developers should have selected). See below on what to do if you see this message.

Why and when should a string be deprecated

The most common case is that you realize that a string is not used any more in standard Moodle code. You will probably search the whole moodle.git for the string identifier and the only relevant place found is the string definition itself. Even if it seems that the given string is not used any more in the standard Moodle code, there can eventually be some additional (contributed) plugins still relying on it. This is typical case for semantically general strings provided by the moodle.php (core) component such as "Yes", "Continue", "Hidden" etc.

Beware that searching for the string identifier only may sometimes lead to false negatives. Imagine you have a suspicion that a hypothetical string "actionloginremote" is no longer used any more as there is no code that would actually use this stringid. However, there can be places like this

$action = optional_param('action', 'loginremote', PARAM_ALPHA); print_string('action'.$action);

that are harder to detect. So, instead of simply removing the string "actionloginremote" you would put it to the list of deprecated strings.

Other scenario may be that the semantically same string was defined twice or it was put into a wrong component. If you think there may be places that rely on the wrong location (component), you should deprecate it. Copy the string to a new location (do not forget to use CPY instruction for AMOS to replay that change in all existing translations) and deprecate the old one.

Also, it may turn out that some strings are quite vaguely defined and do not have clear and unique context / semantics. Ideally, Moodle code should use context-sensitive strings rather than rely on one general string covering all cases. Things like http://en.wikipedia.org/wiki/Grammatical_gender play important role in many languages. For example, in Czech, "a role" or "a question" are of feminine gender and the correct translation of "hidden" in this case is "skrytá", while "a badge" is of masculine gender and the correct translation is "skrytý". So it would be better to have separate strings like "hiddenrole", "hiddenquestion" and "hiddenbadge" even if they all read just "Hidden" in the English language pack. When you are about to split existing string into couple of specific ones, you may wish to deprecate the general one at the end, too (also, do not forget to use the CPY again).

When a string should be just removed

There are situations where deprecation does not make sense. For example when a whole functionality is being removed, or a very specific string (such as error message) is no longer used by the code. If it is very unlikely that the string is not used by any other code, it can be simply removed without the full deprecation process.

Same logic applies to cases when a very specific string is to be moved or renamed. In this situation, it is valid to just move it (together with the matching MOV instruction in the AMOScript).

How to deprecate a string

• Strings can be deprecated and removed on master branch only.
• Locate or create file deprecated.txt either in lang/en/ or componentfullpath/lang/en/
• Add a line "identifier,fullcomponentname" to the end of this file
• Move the string inside the existing language file to the end of the file under the comment "// Deprecated since Moodle X.Y" (this comment will help removing deprecated strings later).

What to do if you get a debugging message

There are two possibilities. Either the code that uses the deprecated string must be fixed, or the string should not have been deprecated and must be removed from the list

Use the git-blame tool on the corresponding lang/en/deprecated.txt and find the commit/issue that deprecated this string. It should give you enough information to decide what action is the most appropriate.

• If you think the string was deprecated by mistake, create a new issue in the tracker Moodle to remove it from the list (on all supported branches, not only on master).
• If the string was renamed or moved, you will probably want to fix the caller to use the new name/location of the string.
• You may as well copy the string to your own plugin scope and make it context-specific.