Add structured Changes blocks to Crane accepted iteration commits

Open Beginner friendly
#5 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
markdown
Domain
tooling

Research direction

Start by reading Step 5a in workflows/crane.md and inspect the existing accepted-iteration commit prompt and summary fallback wording. Update the prompt to require the compact Changes: block before Run: {run_url}, then add the suggested prompt test to verify the subject template, ordering, and fallback guidance.

Written by the indexing model from the issue text.

Description

enhancement

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.

Dominant language
Python
Stars
10
Forks
0
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from githubnext/crane

All issues in githubnext/crane

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.