Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
chaptersix wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions internal/commandsgen/code.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,9 +237,9 @@ func (c *Command) writeCode(w *codeWriter) error {
w.writeLinef("s.Command.Annotations = make(map[string]string)")
w.writeLinef("s.Command.Annotations[\"ignoresMissingEnv\"] = \"true\"")
}
if c.Deprecated != "" {
w.writeLinef("s.Command.Deprecated = %q", c.Deprecated)
}
// Note: We intentionally don't set s.Command.Deprecated here because Cobra
// prints deprecation warnings to stdout, which breaks JSON output. Instead,
// the deprecation warning is prepended to the description/help text.
// Add subcommands
for _, subCommand := range subCommands {
w.writeLinef("s.Command.AddCommand(&New%v(cctx, &s).Command)", subCommand.structName())
Expand Down
26 changes: 24 additions & 2 deletions internal/commandsgen/parse.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ type (
Description string `yaml:"description"`
DescriptionPlain string
DescriptionHighlighted string
Deprecated string `yaml:"deprecated"`
HasInit bool `yaml:"has-init"`
Deprecated bool `yaml:"deprecated"`
DeprecationMessage string `yaml:"deprecation-message"`
HasInit bool `yaml:"has-init"`
ExactArgs int `yaml:"exact-args"`
MaximumArgs int `yaml:"maximum-args"`
IgnoreMissingEnv bool `yaml:"ignores-missing-env"`
Expand Down Expand Up @@ -137,6 +138,22 @@ var markdownInlineCodeRegex = regexp.MustCompile("`([^`]+)`")
const ansiReset = "\033[0m"
const ansiBold = "\033[1m"

const defaultDeprecationMessage = "This command is deprecated and will be removed in a later release."

// generateDeprecationBox creates a formatted CAUTION box for deprecated commands.
// If message is empty, uses the default deprecation message.
func generateDeprecationBox(message string) string {
if message == "" {
message = defaultDeprecationMessage
}
content := "CAUTION: " + message
// Calculate box width (content + 2 spaces padding + 2 border chars)
boxWidth := len(content) + 4
border := "+" + strings.Repeat("-", boxWidth-2) + "+"
middle := "| " + content + " |"
return "```\n" + border + "\n" + middle + "\n" + border + "\n```\n\n"
}

func (o OptionSets) processSection() error {
if o.Name == "" {
return fmt.Errorf("missing option set name")
Expand Down Expand Up @@ -172,6 +189,11 @@ func (c *Command) processSection() error {
return fmt.Errorf("missing description for command: %s", c.FullName)
}

// Prepend deprecation warning box if command is deprecated
if c.Deprecated {
c.Description = generateDeprecationBox(c.DeprecationMessage) + c.Description
}

if len(c.NamePath) == 2 {
if c.Docs.Keywords == nil {
return fmt.Errorf("missing keywords for root command: %s", c.FullName)
Expand Down
48 changes: 48 additions & 0 deletions internal/commandsgen/parse_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
package commandsgen

import "testing"

func TestGenerateDeprecationBox(t *testing.T) {
tests := []struct {
name string
message string
expected string
}{
{
name: "default message when empty",
message: "",
expected: "```\n" +
"+-----------------------------------------------------------------------------+\n" +
"| CAUTION: This command is deprecated and will be removed in a later release. |\n" +
"+-----------------------------------------------------------------------------+\n" +
"```\n\n",
},
{
name: "custom message",
message: "Use the new API instead.",
expected: "```\n" +
"+-----------------------------------+\n" +
"| CAUTION: Use the new API instead. |\n" +
"+-----------------------------------+\n" +
"```\n\n",
},
{
name: "short custom message",
message: "Removed.",
expected: "```\n" +
"+-------------------+\n" +
"| CAUTION: Removed. |\n" +
"+-------------------+\n" +
"```\n\n",
},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := generateDeprecationBox(tt.message)
if got != tt.expected {
t.Errorf("generateDeprecationBox(%q) =\n%q\nwant:\n%q", tt.message, got, tt.expected)
}
})
}
}
4 changes: 2 additions & 2 deletions internal/temporalcli/commands.gen.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2544,9 +2544,9 @@ func NewTemporalTaskQueueVersioningCommand(cctx *CommandContext, parent *Tempora
s.Command.Use = "versioning"
s.Command.Short = "Manage Task Queue Build ID handling (Deprecated)"
if hasHighlighting {
s.Command.Long = "\x1b[1m+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+---------------------------------------------------------------------+\x1b[0m\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n\x1b[1mtemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID."
s.Command.Long = "\x1b[1m+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\x1b[0m\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n\x1b[1mtemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\x1b[0m\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID."
} else {
s.Command.Long = "```\n+---------------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+---------------------------------------------------------------------+\n```\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n```\ntemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID."
s.Command.Long = "```\n+-------------------------------------------------------------+\n| CAUTION: This API has been deprecated by Worker Deployment. |\n+-------------------------------------------------------------+\n```\n\nProvides commands to add, list, remove, or replace Worker Build ID assignment\nand redirect rules associated with Task Queues:\n\n```\ntemporal task-queue versioning [subcommands] [options] \\\n --task-queue YourTaskQueue\n```\n\nTask Queues support the following versioning rules and policies:\n\n- Assignment Rules: manage how new executions are assigned to run on specific\n Worker Build IDs. Each Task Queue stores a list of ordered Assignment Rules,\n which are evaluated from first to last. Assignment Rules also allow for\n gradual rollout of new Build IDs by setting ramp percentage.\n- Redirect Rules: automatically assign work for a source Build ID to a target\n Build ID. You may add at most one redirect rule for each source Build ID.\n Redirect rules require that a target Build ID is fully compatible with\n the source Build ID."
}
s.Command.Args = cobra.NoArgs
s.Command.AddCommand(&NewTemporalTaskQueueVersioningAddRedirectRuleCommand(cctx, &s).Command)
Expand Down
22 changes: 4 additions & 18 deletions internal/temporalcli/commands.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2603,13 +2603,8 @@ commands:

- name: temporal task-queue get-build-id-reachability
summary: Show Build ID availability (Deprecated)
deprecated: true
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
in Namespaces that support Worker versioning:

Expand Down Expand Up @@ -2650,13 +2645,8 @@ commands:

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

Fetch sets of compatible Build IDs for specified Task Queues and display their
information:

Expand Down Expand Up @@ -2861,13 +2851,9 @@ commands:

- name: temporal task-queue versioning
summary: Manage Task Queue Build ID handling (Deprecated)
deprecated: true
deprecation-message: This API has been deprecated by Worker Deployment.
description: |
```
+---------------------------------------------------------------------+
| CAUTION: This API has been deprecated by Worker Deployment. |
+---------------------------------------------------------------------+
```

Provides commands to add, list, remove, or replace Worker Build ID assignment
and redirect rules associated with Task Queues:

Expand Down
Loading