Governance RFC: Introduce a deprecation policy

[xenoworf]

Issue Description

Terra UI lacks an actionable and public deprecation policy. In a kind of chicken-and-egg problem: lack of a deprecation policy discourages some needed and natural deprecation while at the same time makes it harder for consumers to plan for any would-be deprecations.

Proposal

I propose terra adopt a deprecation policy with these features:

1. Meta: Publishing the policy to the Terra site, so that it's known to all of our consumers just as our license is known.
2. A clear definition of what deprecation means, and what end-of-life means to Terra.
3. A list of scopes of deprecation (feature, component, pattern) that Terra honors.
4. A description of the lifecycle of something that is deprecated (e.g. living, deprecated, then dead).
   4.1. Each stage of life should have a reasonable time period given so that our consumers can plan confidently.
5. Instructions on how to suggest a something be deprecated and how the that suggestion can be accepted or rejected.
6. Instructions on how consumers can learn what deprecations are in process.

I'm certainly not suggesting Terra get deprecation-happy, we should continue to try and support as we can.

Example deprecation policy

This is my take on a simple deprecation policy:

• A component, or an API feature (e.g. a prop) or a documented pattern of usage (consuming) a component(s) can be marked deprecated.
• Deprecations are requested/suggested by logging an issue, and ratified by the core group after careful consideration.
• A deprecation is marked in the next relevant release notes and called out loudly in the relevant documentation pages.
• Once something is deprecated: for six months it is no longer enhanced or supported other than security-related patches.
• Six months after deprecation: the thing is noted as removed in the release notes, is scrubbed from the doc site, and is removed from the codebase. It is now dead.

[CT014330]

I agree with this approach and also like the simple depreciation policy. I do think we may adjust the cadence to align with major releases which I expect to be set yearly, but we need to further define/refine that.

@elliott-hoffman-cerner do you think we should log something to track the documentation updates?

[xenoworf]

@CT014330 I think this issue is the tracking point, and when someone (me?) submits a PR to fix the doc they can tie it to this issue. Discussion can continue on this issue or on the PR.

[xenoworf]

I have not forgotten about this - I just haven't had time to work on it yet.