Skip to content

feat(inkless:release): add prep/upstream-sync skills and cherry-pick tooling - #718

Draft
jeqo wants to merge 7 commits into
jeqo/changelogfrom
jeqo/upstream-sync-skills
Draft

feat(inkless:release): add prep/upstream-sync skills and cherry-pick tooling#718
jeqo wants to merge 7 commits into
jeqo/changelogfrom
jeqo/upstream-sync-skills

Conversation

@jeqo

@jeqo jeqo commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Add the inkless-release-prep and inkless-upstream-sync agent skills and refresh the inkless-sync docs/prompts. Enhance the cherry-pick flow:

  • branch-consistency.sh --check: exit non-zero only on actionable-missing commits (matched by PR number; old below-window commits do not count), for CI gates.
  • cherry-pick-to-release.sh: stop on first conflict (never auto-abort-and-continue, which reordered picks); restore version-owned files (gradle.properties/Makefile/ .env) to the branch value after every pick so version bumps land without changing the branch version; --dry-run reports version-owned handling and no longer requires a clean worktree.

Branch-specific divergences are handled in history (cherry-pick + sync(revert):/ sync(align):), documented in the skill and README -- no skip-list side file.

jeqo added 7 commits July 22, 2026 18:26
…cy.sh

The release workflow's validate job invokes branch-consistency.sh --check
to gate on actionable missing commits (by PR presence). Add the flag: it
turns the actionable-missing count into a process exit code so CI can gate
without parsing human-readable output. Old below-window commits are not
actionable and do not fail the check.
…partial release

Replace the validate job's exact-SHA ancestry check (git merge-base
--is-ancestor MAIN_COMMIT) with branch-consistency.sh --check: release branches
are built by cherry-picking, so commits exist under different SHAs and the SHA
check could never pass. --check matches by PR number, the correct measure.

Add resume=true: when a run created the tags but never published the Release,
re-run with the same inkless_version to skip tagging and re-run build+publish
(discovers branches/Kafka versions from the existing tags).
…dentation

The release notes were built as a YAML block-scalar heredoc, so the
leading indentation leaked into the markdown and rendered headings and
bullets as an indented code block. Build the notes in a temp file with
printf and pass --notes-file instead.

The curated-changelog injection is split out to land with the
inkless-changelog skill (the generator it calls lives there).
Clarify the prep->release seams in RELEASES.md: push branches is the prep gate;
tags are created by the workflow (never by hand); resume=true finishes a
partially-completed release; and a corrected break-glass build/publish procedure
using the make targets with the right image tag format (<kafka>-<increment>-<arch>).

The changelog-generation docs are split out to land with the inkless-changelog
skill (the generator they reference lives there).
Add gen-changelog.py + the inkless-changelog skill: diff conventional-commit
history and configs.rst/metrics.rst between two inkless-release tags to produce a
detailed CHANGELOG.md entry and a curated release-notes summary. Detects upstream
syncs (apache/kafka merges + gradle version delta) and notes them.

Backfill docs/inkless/CHANGELOG.md for increments 0.33..0.44 and link it from the
docs index.
…otes

The finalize-release job now runs gen-changelog.py --summary against the freshly
created inkless-release-<N> tag and appends the curated feat/fix/config summary to
the Release body (best-effort: falls back to boilerplate notes if generation fails).
Requires fetch-depth: 0 so the generator can diff the previous tag.

Also documents the changelog/release-notes flow in RELEASES.md. Depends on the
inkless-changelog generator added in the previous commit; stacks on the release
workflow (#714) which owns inkless-publish.yml.
…tooling

Add the inkless-release-prep and inkless-upstream-sync agent skills and refresh
the inkless-sync docs/prompts. Enhance the cherry-pick flow:

- branch-consistency.sh --check: exit non-zero only on actionable-missing commits
  (matched by PR number; old below-window commits do not count), for CI gates.
- cherry-pick-to-release.sh: stop on first conflict (never auto-abort-and-continue,
  which reordered picks); restore version-owned files (gradle.properties/Makefile/
  .env) to the branch value after every pick so version bumps land without changing
  the branch version; --dry-run reports version-owned handling and no longer
  requires a clean worktree.

Branch-specific divergences are handled in history (cherry-pick + sync(revert):/
sync(align):), documented in the skill and README -- no skip-list side file.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR modernizes Inkless’ upstream-sync and release-prep workflows by moving “AI prompt” docs into first-class agent skills, and hardens the release/cherry-pick automation to be safer for CI gates and release resumption.

Changes:

  • Add two new agent skills (inkless-upstream-sync, inkless-release-prep) and update inkless-sync/ docs to route workflows through them (removing the old prompt templates).
  • Improve cherry-pick tooling to stop on first conflict (preserving dependency order), and to keep release-branch-owned version files stable across cherry-picks (even when no conflict occurs).
  • Enhance the GitHub release workflow with a resume mode and curated release-notes generation via the new inkless-changelog generator.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
inkless-sync/RELEASE-SYNC-PROMPT.md Removed legacy release-sync prompt doc (replaced by agent skill workflow).
inkless-sync/RELEASE-SYNC-GUIDE.md Updates AI-assisted guidance to point at the new upstream-sync skill.
inkless-sync/README.md Reworks “AI-assisted sync” docs to reference skills; documents “sync(revert)/sync(align)” divergence handling.
inkless-sync/MAIN-SYNC-PROMPT.md Removed legacy main-sync prompt doc (replaced by agent skill workflow).
inkless-sync/cherry-pick-to-release.sh Stops on first conflict; preserves branch-owned version files after each pick; improves dry-run behavior.
inkless-sync/branch-consistency.sh Adds --check mode for CI gating based on actionable missing commits; adjusts fetch behavior.
docs/inkless/RELEASES.md Documents resume releases and adds break-glass manual publish procedure; clarifies validation semantics.
docs/inkless/README.md Adds link to the new detailed changelog.
docs/inkless/CHANGELOG.md Introduces a detailed, per-increment changelog file (new).
AGENTS.md Updates agent documentation pointers to reference the new skills.
.github/workflows/inkless-release.yml Adds resume input; changes validation to use branch-consistency.sh --check; skips validate/tag on resume; improves publish job wiring.
.github/workflows/inkless-publish.yml Ensures full history for changelog generation and injects curated notes into GitHub Release body.
.ai-agents/skills/inkless-upstream-sync/SKILL.md New skill entry point for main/release upstream merges and status checks.
.ai-agents/skills/inkless-release-prep/SKILL.md New skill entry point for cherry-pick prep and release-branch creation guidance.
.ai-agents/skills/inkless-changelog/SKILL.md New skill docs for generating detailed changelog entries + curated release notes.
.ai-agents/skills/inkless-changelog/gen-changelog.py New generator that diffs tags + config/metric docs to produce changelog drafts and summaries.

Comment on lines +154 to +157
typ, scope, desc = parsed
# keep only inkless-relevant scopes; drop pure sync bookkeeping
if scope.startswith("sync") or scope == "sync":
continue
Comment on lines 263 to 267
- name: Validate all active branches
env:
ACTIVE_BRANCHES: ${{ needs.prepare.outputs.active_branches }}
MAIN_COMMIT: ${{ needs.prepare.outputs.main_commit }}
run: |
FAILED=0
Comment on lines +351 to +355
# --check only compares origin/main against origin/<branch>; it does not need
# the upstream (apache/kafka) remote. Skip fetch_upstream in that mode so the
# check runs in CI checkouts that only have 'origin' (no apache/upstream remote).
if [[ "$CHECK" != "true" ]]; then
fetch_upstream
Comment on lines 319 to 320
fetch_upstream
git fetch origin --prune
@jeqo
jeqo force-pushed the jeqo/changelog branch from 4db9e0b to e3f77c4 Compare July 30, 2026 20:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants