Skip to content

feat: auto-generate deprecation warning box from YAML config#941

Open
chaptersix wants to merge 4 commits intotemporalio:mainfrom
chaptersix:feat/auto-deprecation-warning
Open

feat: auto-generate deprecation warning box from YAML config#941
chaptersix wants to merge 4 commits intotemporalio:mainfrom
chaptersix:feat/auto-deprecation-warning

Conversation

@chaptersix
Copy link
Copy Markdown
Contributor

@chaptersix chaptersix commented Feb 6, 2026

Summary

  • Add deprecated: true field to command YAML config to auto-generate CAUTION deprecation box
  • Add optional deprecation-message field for custom deprecation messages
  • Remove need to manually add deprecation warning boxes to command descriptions

Usage

# Default message: "This command is deprecated and will be removed in a later release."
- name: temporal some-command
  deprecated: true
  description: |
    Command description here...

# Custom message
- name: temporal other-command
  deprecated: true
  deprecation-message: This API has been deprecated by Worker Deployment.
  description: |
    Command description here...

Test plan

  • Unit tests for generateDeprecationBox() function
  • Verified code generation produces correct output
  • All existing tests pass

Closes #673

Add `deprecated: true` and optional `deprecation-message` fields to
command YAML config. When set, the generator auto-prepends a CAUTION
box to the command description, removing the need to manually add
deprecation warnings.
@chaptersix chaptersix requested review from a team as code owners February 6, 2026 22:59
@chaptersix chaptersix marked this pull request as draft February 7, 2026 01:26
@chaptersix chaptersix marked this pull request as ready for review April 8, 2026 22:40
@chaptersix chaptersix requested a review from a team as a code owner April 8, 2026 22:40
@chaptersix
Copy link
Copy Markdown
Contributor Author

chaptersix commented Apr 8, 2026

Before/after samples

1. Cobra Command.Deprecated — deprecation warning printed to stdout

Before (old behavior using s.Command.Deprecated): Cobra prints a warning line to stdout when the command is invoked, contaminating JSON output:

$ temporal task-queue get-build-id-reachability --task-queue foo --build-id bar -o json
Command "get-build-id-reachability" is deprecated, This command is deprecated and will be removed in a later release.
Error: failed reaching server: ...

After (this PR — s.Command.Deprecated is never set): no warning on stdout, deprecation notice only appears in --help:

$ temporal task-queue get-build-id-reachability --task-queue foo --build-id bar -o json
Error: failed reaching server: ...

2. Deprecation box in --help

Before (manually written in YAML):

- 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...

After (this PR — deprecated: true auto-generates the box):

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

Rendered --help output (same in both cases):

$ 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
in Namespaces that support Worker versioning:
...

Custom message via deprecation-message:

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

Provides commands to add, list, remove, or replace Worker Build ID assignment...

@chaptersix chaptersix requested a review from dandavison April 9, 2026 14:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Set a "deprecated:true" flag for CLI command generation YAML

1 participant