An idea came up in an internal conversation about Liberty server.xml config deprecation.
In this scenario, a config element/attribute is declared "internal" in the DS metatype definition to support the desire to "deprecate" this XML construct.
At first, this might seem to be a violation of Liberty's zero migration promise. However, it's really not, because the DS metatype property is not removed from the metatype definition. The "internal" designation simply affects the process by which the documentation is generated, effectively hiding the now-deprecated property from the doc.
In a similar way, an internal-only construct is hidden from the XSD generated and used in LCLS server.xml validation.
In a case such as this, Liberty Tools would, using a newly-generated XSD, declare the new construct as invalid, per-schema.
This is less than desirable for two reasons:
The server.xml is still functional, since the metatype construct is still part of the definition and supported by the runtime component impl in spite of not being doc'd.
We miss an opportunity to explain the deprecation decision and guide the user to the new alternative we're recommending in place of what's deprecated.
TODO
Investigate what the set of relevant config deprecations have been performed in the lifetime of the Open Liberty / WebSphere Liberty projects. Is this more than 1-5 items?
What is a good way to search the history? Is there a better way than scripting a search through git logs and diffs for metatype.xml changes? Does IBM maintain a more direct record of such decisions perhaps?
An idea came up in an internal conversation about Liberty server.xml config deprecation.
In this scenario, a config element/attribute is declared "internal" in the DS metatype definition to support the desire to "deprecate" this XML construct.
At first, this might seem to be a violation of Liberty's zero migration promise. However, it's really not, because the DS metatype property is not removed from the metatype definition. The "internal" designation simply affects the process by which the documentation is generated, effectively hiding the now-deprecated property from the doc.
In a similar way, an internal-only construct is hidden from the XSD generated and used in LCLS server.xml validation.
In a case such as this, Liberty Tools would, using a newly-generated XSD, declare the new construct as invalid, per-schema.
This is less than desirable for two reasons:
TODO
Investigate what the set of relevant config deprecations have been performed in the lifetime of the Open Liberty / WebSphere Liberty projects. Is this more than 1-5 items?
What is a good way to search the history? Is there a better way than scripting a search through git logs and diffs for metatype.xml changes? Does IBM maintain a more direct record of such decisions perhaps?