Deprecation Process

User level functions (prefixed \gre)

If a change necessitates that a User level function be deprecated, then the following procedure is to be followed for phasing out said function:

1. The function is marked as deprecated: Use of it raises a warning (using \gre@deprecated) which points to the new syntax which achieves the same effect, and calls said syntax for the user. An entry under ### Deprecated should also appear in CHANGELOG.md which indicates the appropriate new syntax.
2. The function is marked as obsolete: Use of it does not work, but raise an error (using \gre@obsolete) which points to the new syntax which achieves the same effect. An entry under ### Removed should also appear in CHANGELOG.md which indicates the appropriate new syntax.
3. The function no longer exists in the code base. Anyone still using it gets the generic "Undefined control sequence" error.

Each of these steps should be in a major or minor release, with step 1 or 2 being a mandatory major (i.e., if step 1 is a minor release, then step 2 must be major, if step 1 is a major release, then step 2 is allowed to be a minor release). It is advisable, therefore, that existing functions which are deprecated or obsolete be moved along this path on the develop branch immediately after a major or minor release is made.

When deprecating/obsoleting code, please mark appropriate lines with a comment that indicates the status of the line (either DEPRECATED or OBSOLETE). Appropriate lines are ones which are slated for removal but which still exist to comply with the above procedure in step 1 or 2. Lines which are to be altered but not removed should also be so marked and the comment should also indicate what the altered line should look like in the end.

gregorio written functions (prefixed \Gre and written by the executable)

Changes to the way gregorio functions are called (i.e. their name and number and order of arguments) can only be made on the develop branch. These changes do not need to be marked as deprecated or obsolete.

If you are altering the way a function at this level works but leaving the way it is called intact, no markings are usually necessary and can be made on the ctan branch. However, if your changes suggest that the way the function is called should be altered (for instance an argument is ignored after your changes, and thus should be removed) then you should mark the documentation for those arguments (both in the actual documentation and, if present, in the code comments) with DEPRECATED. Further, you should go into the source code for the executable and add comments marked DEPRECATED in the appropriate locations which indicate what changes should be made the next time the executable is updated. Once the ctan change is accepted, make another PR against develop which includes these changes and removes the DEPRECATED comments in the source code and makes the appropriate alterations to the documentation.

Internal level functions (prefixed \gre@ or lua functions)

These functions may be changed at any time without being marked as deprecated or obsolete.