Component deprecation

Commodore supports components being marked as deprecated. Components can be marked as "deprecated" by adding deprecated: true to parameter parameters.<component_name>._metadata. To avoid allowing the inventory hierarchy to overwrite a component’s _metadata parameter, it must be labeled as constant by prefixing it with a =. The component template adds the _metadata parameter (with no content) for new components.

class/defaults.yml

parameters:
  component_name:
    =_metadata:
      deprecated: true

If the component is deprecated in favor of a new component, the new component can be indicated by adding replaced_by: another-component in the component’s _metadata parameter. In general, the value of replaced_by isn’t verified to be an existing component. The component named in replaced_by is allowed to take over the deprecated component’s library prefix in order to provide a transitional library to make switching components easy.

class/defaults.yml

parameters:
  component_name:
    =_metadata:
      deprecated: true
      replaced_by: another-component

Commodore will append the contents of field deprecation_notice in the component’s _metadata parameter to the deprecation notice. This field is intended to be used to give extended information about the deprecation. This could be a link to a migration guide, if a replacement component exists, or simply a link to a longer deprecation notice in the component’s documentation.

class/defaults.yml

parameters:
  component_name:
    =_metadata:
      deprecated: true
      replaced_by: another-component
      deprecation_notice: >-
        See https://github.com/projectsyn/component-another-component/docs/.../how-tos/migrating-from-component-name.adoc
        for a migration guide.

Commodore will print a deprecation notice for each component which has parameters.<component_name>._metadata.deprecated set to true.

If field replaced_by in the component’s _metadata parameter isn’t empty, the deprecation notice will use the field’s value as the name of the replacement component.
If field deprecation_notice in the component’s _metadata parameter isn’t empty, the value of the field will be appended to the deprecation notice.

Components can indicate that they replace another component by setting _metadata.replaces. By providing this information, a component is allowed to use its predecessor’s library prefix in the following two cases. First, the component is allowed to use the additional prefix if its predecessor isn’t deployed on the cluster which is being compiled. Second, the component is allowed to use the additional prefix if its predecessor has set _metadata.deprecated: true and _metadata.replaced_by to the component’s name.

class/defaults.yml

parameters:
  another-component:
    =_metadata:
      replaces: component-name