feat: auto-generate deprecation warnings from YAML config

[chaptersix]

Related issues

Closes #673

What changed?

Auto-generate deprecation warnings from a deprecated: true YAML flag instead of manually writing CAUTION boxes in command descriptions. Deprecation warnings are also printed to stderr at runtime so users see them when invoking deprecated commands, without breaking JSON output.

Before

Deprecation required manually adding a CAUTION box to the description and (Deprecated) to the summary:

- name: temporal task-queue get-build-id-reachability
  summary: Show Build ID availability (Deprecated)
  description: |
    ` `` 
    +-----------------------------------------------------------------------------+
    | CAUTION: This command is deprecated and will be removed in a later release. |
    +-----------------------------------------------------------------------------+
    ` ``

    Show if a given Build ID can be used for new, existing, or closed Workflows...

No runtime warning was shown when invoking the command.

After

Set deprecated: true and optionally deprecation-message. The CAUTION box, (Deprecated) summary suffix, and stderr runtime warning are all auto-generated:

- name: temporal task-queue get-build-id-reachability
  deprecated: true
  description: |
    Show if a given Build ID can be used for new, existing, or closed Workflows...

- name: temporal task-queue versioning
  deprecated: true
  deprecation-message: This API has been deprecated by Worker Deployment.
  description: |
    Provides commands to add, list, remove, or replace...

Runtime stderr output:

$ temporal task-queue get-build-id-reachability --task-queue foo --build-id bar
warning: this command is deprecated and will be removed in a later release
...

JSON output is not affected (warning goes to stderr only):

$ temporal task-queue get-build-ids -o json --task-queue foo 2>/dev/null
[{"buildIds":["1.0"],"defaultForSet":"1.0","isDefaultSet":true}]

Checklist

Stability

• Breaking changes are marked with 💥 in the PR title and release notes
• Changes to JSON output (-o json / -o jsonl) are treated as breaking changes

Design

• This feature does not depend on Cloud-only APIs or behavior (it works against an OSS server)

Help text (see style guide at the top of commands.yaml)

• Summaries use sentence case and have no trailing period
• Long descriptions end with a period and include at least one example invocation

Behavior

• Results go to stdout; errors and warnings go to stderr
• Error messages are lowercase with no trailing punctuation

Tests

• Added functional test(s) (SharedServerSuite)
• Added unit test(s) (func TestXxx) where applicable

Manual tests

Setup

temporal server start-dev --headless

Happy path -- stderr warning on deprecated command

$ temporal task-queue get-build-ids \
    --task-queue YourTaskQueue
warning: this command is deprecated and will be removed in a later release
...

Happy path -- JSON output not polluted

$ temporal task-queue get-build-ids \
    -o json \
    --task-queue YourTaskQueue 2>/dev/null
[...]

Happy path -- help text shows CAUTION box

$ temporal task-queue get-build-id-reachability --help
+-----------------------------------------------------------------------------+
| CAUTION: This command is deprecated and will be removed in a later release. |
+-----------------------------------------------------------------------------+

Show if a given Build ID can be used for new, existing, or closed Workflows...

Happy path -- custom deprecation message

$ temporal task-queue versioning --help
+-------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment. |
+-------------------------------------------------------------+
...

[fretz12]

Nice cleanup! I love how deprecation is defined as a YAML flag now.