Skip to content

Reconcile Comments That Echo a Contract Section With the Comment Rule #2907

Closed

Description

@ptr727

A local review of the amended Comments rule in the comment-and-doc-style Skill, which now lets a comment name a contract section and forbids echoing that section's text, found follow-ups outside that change.

  • Some comments name a section and also copy its wording, for example the step comment citing D5.2 in the publish-release snippet and the tag-create comment citing D4.7 in the build-release-task workflow. Each should keep the name and drop the copied reasoning.
  • GOVERNANCE.md Workflow YAML Conventions, Concurrency bullet, asks each documented exception to record its rationale in its own header comment, which reads against the rule that a comment restates no rule inline.
  • Wording in the amended bullet leaves open whether echoing covers a paraphrase, whether the file must be named beside a bare section id, and what counts as a contract section (a D-guarantee, a numbered WORKFLOW.md section, or a section of another document).

None of these were caused by the amendment.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions