Deprecating a Token

Introduction

We have a formal method around removing tokens, the first step being to deprecate them for the next major release cycle. e.g. If the current PCGen version is 5.14.2 then we can deprecate a token for the 5.16.x line and perform the actual removal in the 6.0.x line.

Steps

1. Ensure you have approval for the token change via the New_.lst_Tag_process. The token should have gone through a NEWTAG proposal ( http://jira.pcgen.org/browse/NEWTAG ) and discussion on the pcgen_experimental list ( https://groups.yahoo.com/neo/groups/pcgen_experimental/conversations/messages )
2. SVN Move the token itself to the plugin.lsttokens.deprecated package (e.g. FROM branches/5.14.x/pcgen/code/src/java/plugin/lsttokens/template/BonusfeatsToken.java TO pcgen/code/src/java/plugin/lsttokens/deprecated/BonusfeatsToken.java
3. Move the location of the JAR/Plugin build in the pluginbuild.xml file (this can be found in the code folder of our build). The proper location in the file is in the section "jar-deprecated-plugin"
   1. Move the item to a different location in the XML
   2. You will need to update to the new package (above)
   3. You will need to specifically name the new JAR: ???-DEPRECATED-YYY where YYY is the prefix (everything in the class name except the trailing "Lst" or "Token" - this is case insensitive) [This is required due to our plugin build checking]
   4. Make sure the deprecated plugin is written to ${lstplugins.dir} if it was not before
4. Edit the deprecated token
   1. Make the token implement the DeprecatedToken interface.
   2. If there is a known replacement token, then ensure that the contents loaded into the rules context in parse represents the load config of the replacement token
   3. If there is a known replacement token, then have the Deprecated token implement CDOMCompatibilityToken RATHER THAN CDOMPrimaryToken or CDOMSecondaryToken. Note that this may require some special changes if the item was previously a secondary token, as CDOMCompatibilityToken is a primary token.
5. Run a full test (clean & test targets). Really. There are tests out there that are very sensitive to the tokens. Ensure it runs clean.
6. Advance the NEWTAG JIRA entry by indicating "Complete Development". This will trigger documentation and prettylst
7. Ask the data team if they need a Data Issue so that people convert from the old token to the new token.