Skip to content

Add structured Changes blocks to Crane accepted iteration commits #5

@mrjf

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions