Skip to content

Add structured Changes blocks to Crane accepted iteration commits #5

Description

@mrjf

Background

In githubnext/apm, later Crane PR comments needed a reliable way to explain what a newly accepted commit actually did. Sometimes score fields, issue comments, or state-file summaries are unavailable, stale, or too sparse. The commit itself should carry enough structured information to be a fallback source.

APM updated its local Crane workflow prompt so accepted iteration commits include a compact Changes: section before the Run: URL.

Problem

Today an accepted Crane commit may only have a subject and a run URL. That is not enough for downstream summaries, PR comments, or issue updates to reconstruct the useful reviewer-facing facts.

When a PR has many iteration commits, reviewers need to know which module, milestone, or command family each commit advanced. A generic subject plus a workflow link forces everyone to open logs.

Proposed implementation

Update workflows/crane.md so Step 5a requires accepted iteration commit messages to use this shape:

[Crane: {migration-name}] Iteration <N>: <short description>

Changes:
- <compact bullet describing the main migrated unit or behavior change>
- <optional second bullet with test, parity, or milestone movement>

Run: {run_url}

Guidance:

  • Keep Changes: compact and structured.
  • Prefer one or two bullets, three max.
  • Mention the migrated unit or behavior, not generic process.
  • Mention test or parity movement when useful.
  • Keep Run: as the final evidence link.

The accepted-iteration summary logic should then be allowed to fall back to the commit subject plus Changes: bullets when richer state is missing.

Suggested test coverage

Add a prompt test asserting:

  • The commit subject template is present.
  • Changes: appears before Run: {run_url}.
  • The prompt says the Changes: block is used as summary fallback.

Acceptance criteria

  • Accepted Crane commits contain structured Changes: bullets.
  • Later PR or issue comments can summarize a commit without reading workflow logs.
  • Existing commit subject and run-link behavior is preserved.
  • The prompt test prevents regressions.

Provenance

This came from the githubnext/apm migration, where maintainer-facing summaries needed to describe what happened in each new Crane commit, not just that a commit was pushed.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions