[docs] docs: remove bullet-list bloat from ephemerals guide#19141
[docs] docs: remove bullet-list bloat from ephemerals guide#19141
Conversation
Condense repetitive "How it works", "Key behaviors", and "Use cases" sub-sections throughout the guide into concise prose, reducing the file from 242 to 180 lines (25.6% reduction, ~74% fewer bullet points). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
bot
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
This PR streamlines the “Ephemerals” guide by condensing repetitive bullet-list subsections into shorter prose while keeping examples and references intact.
Changes:
- Condenses the “Why Use Ephemerals?” section into a single summary sentence.
- Replaces multiple “Key behaviors / How it works / Use cases” bullet lists with concise paragraphs across several features.
- Shortens the “Use cases for ephemeral discussions” and “This configuration ensures” sections into single-sentence summaries.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. Recompiling the workflow resets the stop time. | ||
|
|
||
| **Key behaviors**: | ||
| - The workflow is disabled at the specified deadline, preventing new runs | ||
| - Existing runs continue to completion | ||
| - The stop time is preserved during recompilation unless `--refresh-stop-time` flag is used | ||
| - Use `gh aw compile --refresh-stop-time` to regenerate the stop time based on current time | ||
|
|
||
| **Use cases**: | ||
| - Trial workflows that should run for a limited period | ||
| - Experimental features with automatic sunset dates | ||
| - Orchestrated initiatives with defined end dates | ||
| - Cost-controlled scheduled workflows | ||
| At the deadline, new runs are prevented while existing runs complete. The stop time persists through recompilation; use `gh aw compile --refresh-stop-time` to reset it. Common uses: trial periods, experimental features, orchestrated initiatives, and cost-controlled schedules. |
There was a problem hiding this comment.
The stop-after section is internally inconsistent: it says recompiling resets the stop time, but the next paragraph says the stop time persists unless --refresh-stop-time is used. The compiler tests indicate the stop time is preserved by default and only refreshed when --refresh-stop-time is set (see pkg/workflow/stop_after_test.go). Please update the earlier sentence (and/or reword this section) so recompilation behavior is described consistently and matches actual behavior.
See below for a potential fix:
The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. For relative deltas, the stop time is calculated once at compilation time and stored in the compiled workflow.
At the deadline, new runs are prevented while existing runs complete. By default, the stop time persists through recompilation; use `gh aw compile --refresh-stop-time` to recompute it from the current time. Common uses: trial periods, experimental features, orchestrated initiatives, and cost-controlled schedules.
| - Weekly status reports where only the latest matters | ||
| - Recurring analysis workflows that supersede previous results | ||
| - Scheduled summaries that replace older versions | ||
| When a new issue is created, up to 10 older issues with the same workflow-id marker are closed as "not planned" with a comment linking to the new issue. Requires `GH_AW_WORKFLOW_ID` to be set and appropriate repository permissions. Ideal for weekly reports and recurring analyses where only the latest result matters. |
There was a problem hiding this comment.
This paragraph says GH_AW_WORKFLOW_ID must be set as a requirement. In compiled workflows it’s set automatically at the safe-outputs job level (see pkg/workflow/compiler_safe_outputs_job.go where GH_AW_WORKFLOW_ID is always populated), so framing it as a user requirement is potentially misleading. Consider rephrasing to clarify it’s provided automatically by gh aw (or remove the requirement line entirely and just describe the workflow-id marker behavior).
| When a new issue is created, up to 10 older issues with the same workflow-id marker are closed as "not planned" with a comment linking to the new issue. Requires `GH_AW_WORKFLOW_ID` to be set and appropriate repository permissions. Ideal for weekly reports and recurring analyses where only the latest result matters. | |
| When a new issue is created, `gh aw` uses the workflow-id marker (`GH_AW_WORKFLOW_ID`, which is set automatically in compiled workflows) to find and close up to 10 older issues as "not planned" with a comment linking to the new issue. This feature requires appropriate repository permissions and is ideal for weekly reports and recurring analyses where only the latest result matters. |
| - Build status notifications where only latest result matters | ||
| - Health check workflows reporting periodic results | ||
| - Progress tracking workflows with frequent updates | ||
| Before posting, the system finds and minimizes previous comments from the same workflow (identified by `GITHUB_WORKFLOW`). Comments are hidden, not deleted. Use `allowed-reasons` to restrict which minimization reason is applied: `spam`, `abuse`, `off_topic`, `outdated` (default), or `resolved`. Useful for status updates, build notifications, and health checks where only the latest result matters. |
There was a problem hiding this comment.
The allowed-reasons explanation could be more precise about defaults/semantics. The code and changelog indicate that if allowed-reasons is omitted, all reasons are allowed (see pkg/workflow/add_comment.go comment and CHANGELOG entry). Consider adjusting the wording so it’s clear allowed-reasons is an allowlist (optional), and that omission doesn’t restrict reasons.
Improves clarity and conciseness of
docs/src/content/docs/guides/ephemerals.mdby removing repetitive bullet-list sub-sections.What changed
File:
docs/src/content/docs/guides/ephemerals.mdReduction: 242 → 180 lines (25.6% fewer lines, ~74% fewer bullet points)
Types of bloat removed
What was preserved
All essential technical information, code examples, tables, and links are unchanged. Only the verbose repetitive sub-section patterns were condensed.
Issues
Screenshots: The Playwright MCP server is network-isolated from the preview server (localhost connection refused), so no screenshot was captured.
References: