Problem
The template's workflow comments are long and carry a lot of context that helps when designing the pipeline but is noise for someone reading the code later:
- Cross-project references and provenance ("mirrors NxWitness's ...", "homeassistant-purpleair targets develop only because ...").
- Historic/design background ("this is a CONSCIOUS choice over ...", "the close/reopen dance previously used by ...", "Action-aware grouping has its own race ...").
- Rule citations ("see AGENTS.md 'Branching Model'", "per AGENTS.md 'Per-target subsetting'", "Documented exception to ... see AGENTS.md 'Workflow YAML Conventions'").
- Comparisons with targets/registries a given repo may not ship ("unlike NuGet's
--skip-duplicate and PyPI's skip-existing").
- Several multi-line block comments where one or two sentences would do, and some comments on self-explanatory inputs.
In a derived repo these read as clutter and, worse, some become factually wrong after adaptation (e.g. a Docker-only repo has no NuGet/PyPI; a public repo isn't "private").
Suggestion
Adopt a house rule for workflow comments: short, current-state, reviewer-focused - explain what the code does and only the non-obvious why, in a sentence or two; no cross-project references, no historic/design narrative, no rule citations. Governance belongs in AGENTS.md, not echoed inline. Trimming the template's own comments to that bar would make every derived repo cleaner by default and avoid the post-adaptation staleness.
For reference, applying this to a derived repo cut ~240 lines of comments from the carried workflows with no loss of necessary context.
Surfaced while adopting the template in ptr727/ESPHome-NonRoot (see ptr727/ESPHome-NonRoot#61).
Problem
The template's workflow comments are long and carry a lot of context that helps when designing the pipeline but is noise for someone reading the code later:
--skip-duplicateand PyPI'sskip-existing").In a derived repo these read as clutter and, worse, some become factually wrong after adaptation (e.g. a Docker-only repo has no NuGet/PyPI; a public repo isn't "private").
Suggestion
Adopt a house rule for workflow comments: short, current-state, reviewer-focused - explain what the code does and only the non-obvious why, in a sentence or two; no cross-project references, no historic/design narrative, no rule citations. Governance belongs in AGENTS.md, not echoed inline. Trimming the template's own comments to that bar would make every derived repo cleaner by default and avoid the post-adaptation staleness.
For reference, applying this to a derived repo cut ~240 lines of comments from the carried workflows with no loss of necessary context.
Surfaced while adopting the template in
ptr727/ESPHome-NonRoot(see ptr727/ESPHome-NonRoot#61).