agentleFS
mesherymeshery/schemas/.agents/skills/cut-release/SKILL.md

cut-release

Skill85 starsChanged 31 days agoApache-2.0View on GitHub

Cut (publish) a release of meshery/schemas by publishing the current Release Drafter draft with the gh CLI. Use this whenever the user asks to "cut a release", "publish the release", "ship a release", "release schemas", "do a release", "release the latest merge", or wants the recently merged PR to go out. Handles waiting for the Release Drafter workflow to fold the just-merged PR into the draft notes, then flipping the draft to published so the publish-schemas workflow publishes the @meshery/schemas npm package, notifies dependents, and publishes the OpenAPI docs. The version tag is already set by Release Drafter and auto-increments after each release, so this skill never creates or bumps a tag.

35 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use verify-ui, write-prd and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ThisIsSadeghiSkill

    verify-ui

    Verify UI implementation against Stitch design via a token audit (HTML ↔ Code, with X-component default-render checks) and an X-components compliance check.

    Also in 3 projects that use this

  • RhyGSkill

    write-prd

    Also in 3 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 35 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you publish too early, the just-merged PR is missing from the notes.

    line 50
  2. Very specific:

    If the run for the current origin/master SHA is still in_progress (or absent because the push just landed), wait for it before publishing:

    line 61
  3. Distinctive:

    new: commit on top of the merge.

    line 73
  4. Very specific:

    If origin/master moved after the run finished, the run pushed a generated-artifacts commit: repeat step 1 (Release Drafter, then Generate …

    line 82
  5. Distinctive:

    Verify the merged PR the user is releasing shows up under one of the category headings.

    line 99
  6. Distinctive:

    If more than one draft is ever returned, stop and ask the user which to publish rather than guessing - publishing the wrong one ships an …

    line 103
  7. Distinctive:

    Never hand-author the tag or notes: If you find yourself computing a version number or writing changelog entries, something is wrong - …

    line 152
  8. Very specific:

    One draft only: If gh release list shows zero drafts, no drafter run has occurred since the last release.

    line 154

“Common” is measured: kept by at least 6 in 10 of the 35 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Cut a meshery/schemas release

Publishing a release here is intentionally a one-action step: flip the existing Release Drafter draft from draft to published. Everything downstream is automated by GitHub Actions - most importantly, publishing the release is what publishes the @meshery/schemas npm package.

How releasing works in this repo

  • .github/workflows/release-drafter.yml runs on every push to master. As PRs merge, it maintains a single draft GitHub Release whose tag auto-increments (the patch version bumps after each publish). There is always exactly one draft waiting to be published.
  • Publishing that draft (the release published event) triggers .github/workflows/publish-schemas.yml, which:
    • waits for any in-flight generate-artifacts-from-schemas.yml run to settle so it publishes generated artifacts rather than stale sources,
    • stamps the release version into schemas/base_cloud.yml and schemas/base_meshery.yml and commits it back to master,
    • publishes the @meshery/schemas package to npm (via publish-npm-package.yml, using OIDC trusted publishing with provenance),
    • notifies extension-partner dependents (notify-dependents.yml), and
    • publishes the OpenAPI docs (publish-openapi-docs.yml).

So the tag is already chosen and the notes are already drafted. Your job is only to make sure the just-merged PR is reflected in the draft, then publish it. Do not create a tag, do not bump a version, do not write release notes by hand, and do not npm publish by hand - Release Drafter owns the tag/notes and the release event owns the npm publish.

Steps

1. Confirm the Release Drafter run for the latest master commit has finished

The draft only includes a PR after the drafter workflow run for that merge commit completes. If you publish too early, the just-merged PR is missing from the notes.

# Latest master commit that should be in the release
git fetch origin master --quiet && git rev-parse origin/master

# Most recent Release Drafter runs (headSha should match origin/master, status "completed")
gh run list --workflow="release-drafter.yml" --branch master --limit 3 \
  --json databaseId,status,conclusion,headSha,createdAt

If the run for the current origin/master SHA is still in_progress (or absent because the push just landed), wait for it before publishing:

gh run watch <databaseId> --exit-status

A conclusion of success for the run whose headSha matches origin/master means the draft is up to date. If the latest run failed, stop and surface that - do not publish stale notes.

Then wait for generated artifacts. generate-artifacts-from-schemas.yml also runs on every push to master and commits regenerated Go/TypeScript (Generate build artifacts from schemas) as a new commit on top of the merge. The tag must land on that commit, not the merge commit.

gh run list --workflow="generate-artifacts-from-schemas.yml" --branch master --limit 3 \
  --json databaseId,status,conclusion,headSha,createdAt
gh run watch <databaseId> --exit-status   # if the run for origin/master is still in progress
git fetch origin master --quiet && git rev-parse origin/master

If origin/master moved after the run finished, the run pushed a generated-artifacts commit: repeat step 1 (Release Drafter, then Generate Artifacts) for the new head until origin/master stops moving. The head is settled when its Generate Artifacts run concluded success or skipped, or no run exists because the commit only touched paths-ignore files. A failure means the generated artifacts are missing - stop and surface it.

2. Identify and inspect the draft

# Tag of the current draft (there is normally exactly one)
gh release list --limit 25 --json tagName,isDraft --jq '.[] | select(.isDraft) | .tagName'

# Read the draft notes and confirm the recently merged PR appears in them
gh release view <draftTag> --json tagName,name,isDraft,body --jq \
  '{tag: .tagName, name: .name, isDraft: .isDraft, body: .body}'

Verify the merged PR the user is releasing shows up under one of the category headings. If it does not, the drafter run from step 1 has not yet indexed it - re-check step 1 rather than publishing without it.

If more than one draft is ever returned, stop and ask the user which to publish rather than guessing - publishing the wrong one ships an unintended version to npm.

Confirm the draft will tag the settled head from step 1. Its tag is created at publish time from targetCommitish; if that is a branch name (master) it resolves to the head you just settled, but if it is a SHA other than origin/master, retarget it:

gh release view <draftTag> --json targetCommitish --jq .targetCommitish
gh release edit <draftTag> --target "$(git rev-parse origin/master)"   # only if it differs

3. Publish the draft

Flipping --draft=false publishes it and fires the published event that drives the npm publish, dependent notifications, and OpenAPI-docs publish. Mark it --latest so it carries the "Latest" badge.

gh release edit <draftTag> --draft=false --latest

4. Confirm it published

gh release view <draftTag> --json tagName,isDraft,isLatest,publishedAt --jq \
  '{tag: .tagName, isDraft: .isDraft, isLatest: .isLatest, publishedAt: .publishedAt}'

# Optionally watch the release fan-out (npm publish + notify + docs)
gh run list --workflow="publish-schemas.yml" --limit 3 \
  --json databaseId,status,conclusion,headBranch,createdAt

isDraft: false and a non-null publishedAt confirm the release is out. Report the published version to the user and note that the publish-schemas workflow has been triggered by the release event and will publish @meshery/schemas to npm, notify dependents, and publish the OpenAPI docs.

What to watch for

  • Don't publish ahead of the drafter run. The most common failure is publishing before the Release Drafter workflow has folded the merged PR into the notes, shipping a release whose notes omit the very change being released. Step 1 exists to prevent exactly this.
  • Don't publish ahead of Generate Artifacts. The tag pins the Go module: tagging the merge commit before the Generate build artifacts from schemas commit lands ships a Go module that lacks the newest generated types, even though the npm package is complete (publish-schemas waits for that run before building it). v1.3.60 and v1.3.63 shipped this gap and needed a corrective release.
  • The release is the npm publish. There is no separate "publish to npm" button - publishing the draft is what pushes @meshery/schemas to the registry. Treat the publish as production.
  • Never hand-author the tag or notes. If you find yourself computing a version number or writing changelog entries, something is wrong - Release Drafter already did both.
  • One draft only. If gh release list shows zero drafts, no drafter run has occurred since the last release; if it shows more than one, ask the user which to publish.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.