drevops/vortex/create-vortex-tooling-release-notes

Create Vortex Tooling Release Notes

Generate consumer-facing release notes for the drevops/vortex-tooling Composer package.

drevops/vortex-tooling is a read-only mirror of the .vortex/tooling/ directory in the drevops/vortex monorepo. A publishing workflow copies that directory to the mirror repository on every push to main, so the mirror's git history is mostly noise: it contains one commit per monorepo commit, including empty commits for monorepo commits that did not touch the tooling at all. Tooling releases are manually gated and almost never align with Vortex template releases, so "what changed since the last tooling release" cannot be read off a Vortex tag. This skill reconstructs that set reliably from the monorepo and turns it into release notes.

When to use

• A new drevops/vortex-tooling release is about to be cut and needs notes.
• An existing tooling release has empty or missing notes that need

backfilling.

• You want to see what tooling changes have accumulated since the last

release.

Run it from inside a drevops/vortex monorepo clone with git and the GitHub CLI (gh) available and authenticated. It produces notes only; it does not tag, publish, or otherwise modify the drevops/vortex-tooling repository.

How the reconciliation works

Every commit published to drevops/vortex-tooling records its origin in the commit body as Source: drevops/vortex@<SHA>. Each release tag therefore points back to an exact monorepo commit. That is the anchor: given the previous tooling release tag, resolve it to its source SHA, then list the monorepo commits from that SHA to now that actually changed shipped tooling files.

Only part of .vortex/tooling/ ships to consumers. tests/, playground/, and the dotfiles are export-ignored from the Composer archive; src/, composer.json, README.md, and LICENSE are what consumers receive. Filtering the log to the shipped paths is what removes both the empty mirror commits and every unrelated monorepo commit in one step.

Inputs

The skill takes a lower bound and an optional upper bound that define the range. Each bound is a tooling release tag or a monorepo commit SHA.

Two common shapes:

• Next release (the usual case): give only the lower bound, or nothing.

The range is "previous tag to HEAD" and you choose the new version in Step 4.

• Backfill an already-published release: give both bounds as tags, for

example 1.1.0 and 1.2.0. The range is "1.1.0 to 1.2.0", and the new version is simply the upper tag - nothing to choose.

Process

Step 1: Resolve the range bounds to monorepo source SHAs

Resolve the lower bound to FROM_SHA and the upper bound to TO_SHA. The rule is the same for each bound:

• A tag (including the latest release tag when no lower bound was

given - find it with gh release list -R drevops/vortex-tooling --limit 1): read its source SHA from the mirror commit body.

``bash gh api repos/drevops/vortex-tooling/commits/1.2.0 --jq '.commit.message' ``

Parse the Source: drevops/vortex@<SHA> line from the output; that <SHA> is the bound.

• A commit SHA: use it directly.
• No upper bound given: TO_SHA is HEAD.

Confirm each resolved SHA exists locally:

git cat-file -t <SHA>

If git cat-file fails, the local clone is behind; run git fetch origin and retry, and stop with a clear message if it still cannot be found.

Step 2: Build the tooling-only changelog

List the monorepo commits between FROM_SHA and TO_SHA that changed a shipped tooling file, newest first:

git log <FROM_SHA>..<TO_SHA> --no-merges --pretty=format:'%H%x09%s' -- .vortex/tooling/ ':(exclude).vortex/tooling/tests' ':(exclude).vortex/tooling/playground' ':(exclude).vortex/tooling/.gitattributes' ':(exclude).vortex/tooling/.gitignore'

The path filter is the heart of the skill: it keeps only commits that touched files consumers actually receive, automatically discarding the empty mirror commits and every non-tooling monorepo commit.

If the command returns nothing, there is nothing to release. Tell the user "No tooling changes shipped since <lower-bound>; no release needed" and stop. Do not write an empty notes file.

Each output line is a commit: a full SHA, a tab, then the subject. The subject already carries the entry shape these notes use - an optional [#ISSUE] prefix and a trailing (#PR) reference, for example:

f8e1361b…	[#2643] Hardened the host-side database-download tooling scripts. (#2648)

Step 3: Enrich each entry from its pull request

For each commit, you need enough context to write an accurate paragraph. The pull requests and issues live in `drevops/vortex`, never in `drevops/vortex-tooling` (the mirror has none). Follow this order and stop as soon as you have enough:

1. Use the subject if it is already specific enough. Skip the fetch

entirely in that case.

1. Fetch the pull request named by the trailing (#NNN):

``bash gh pr view 2648 --repo drevops/vortex --json title,body,labels,author ``

Use author.login for the @author attribution.

1. Fetch the linked issue named by a [#NNN] prefix when the pull

request body is still ambiguous:

``bash gh issue view 2643 --repo drevops/vortex --json title,body ``

1. Inspect the change itself only when the descriptions are

uninformative. The actual diff is in the monorepo, so read it locally rather than over the API:

``bash git show <SHA> -- .vortex/tooling/src ``

Read only enough to understand intent. New or renamed VORTEX_* environment variables, changed defaults, and added or removed scripts are the signals that matter most.

Batch independent gh calls in parallel - issue several Bash tool calls in a single message, targeting 8-10 at a time, so a release with many entries resolves in a few waves rather than one call at a time. Pull request bodies often contain auto-generated review-bot sections; skim past them and rely on the human-written summary.

If gh is unavailable or auth fails, fall back to writing conservative paragraphs from the commit subjects alone, and tell the user which entries lack deep context so they can review them.

Step 4: Determine the version

PREVIOUS_VERSION is the lower-bound tag (or the latest release tag when a bare commit was given).

• Backfill (the upper bound is an existing tag): NEW_VERSION is that

upper tag - nothing to choose.

• Next release (the upper bound is HEAD or a bare commit): suggest

NEW_VERSION from the nature of the changes, then confirm it with the user before writing. The version only labels the notes; no tag is created.

• Major (e.g. 2.0.0): a shipped script was removed or renamed; an

environment variable consumers set was removed or renamed; a default behaviour changed in a way that breaks existing usage; the PHP requirement in composer.json was raised in a breaking way.

• Minor (e.g. 1.3.0): a new script or a new opt-in capability, flag,

or environment variable was added; new behaviour that existing projects are unaffected by.

• Patch (e.g. 1.2.1): a bug fix, a hardening or robustness change, an

internal refactor with no contract change, or documentation fixes.

Step 5: Write and display the notes

Write the file to .artifacts/release-notes-tooling-<NEW_VERSION>.md (for example release-notes-tooling-1.2.1.md) using the structure and rules below, then display its full contents to the user in a fenced markdown code block for review.

Output structure

## What's new since PREVIOUS_VERSION
 
### Breaking changes
 
-**[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph: what used to work, the new behaviour, and the exact migration step consumers must take.
 
### Highlights
 
-**[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph: why this matters to someone running the scripts - the capability it unlocks or the pain it removes.
 
### All changes
 
-**[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph (1-3 sentences) explaining what the change does and why it is valuable.
 
**Full Changelog**: https://github.com/drevops/vortex-tooling/compare/PREVIOUS_VERSION...NEW_VERSION

Formatting rules

Sections

• Breaking changes: include only if at least one entry is breaking; omit

the heading entirely otherwise. An entry is breaking when consumers upgrading may have to change their own setup, or when observable behaviour changes automatically on upgrade. The tooling's public surface is the script contract: script names under src/, the environment variables they read, their arguments, their observable side effects, and the composer.json platform requirement. An opt-out flag makes a breaking change recoverable, not non-breaking - still list it and explain the escape hatch in the migration step.

• Highlights: pick the 5-7 most consumer-relevant entries, favouring new

scripts and new capabilities over internal hardening, refactors, and doc fixes. Omit the heading if the release is too small to have meaningful highlights. Every highlight must also appear under All changes - it is a curated view, not a separate set.

• All changes: list every entry from Step 2, newest first, preserving

the commit subject text verbatim. Do not reword, reorder, merge, or drop entries.

Entries