diff --git a/.claude/skills/breaking-changes/SKILL.md b/.claude/skills/breaking-changes/SKILL.md new file mode 100644 index 0000000..47dd3b9 --- /dev/null +++ b/.claude/skills/breaking-changes/SKILL.md @@ -0,0 +1,49 @@ +--- +name: breaking-changes +description: Decide whether a change is breaking and label it. Use when labelling a PR, when a change touches public API or observable behaviour, or when the user mentions breaking changes, semver, or 1.0. +--- + +# Breaking changes + +Every PR carries exactly one release label (the `pr-labels` check enforces it). release-drafter turns the labels into +the next version. + +## Is it breaking? + +Label it `breaking` when a consumer who upgrades must change something or gets different behaviour: + +- a public type, member, parameter or overload is removed, renamed or changes signature; +- a default, an output format, an exit code or a thrown exception changes; +- a target framework is dropped, or a minimum dependency version rises enough to force consumers to upgrade. + +These are not breaking: adding API, internal changes, fixing behaviour that contradicted the documentation (label +that `bug` and say so in the PR body). + +If package validation (`EnablePackageValidation`) fails on `mise run pack`, the change is breaking at the binary +level, whatever it looks like. + +## What the label does + +| Repo version | `breaking` | `feature` / `enhancement` | everything else | +|---|---|---|---| +| 0.x | minor | minor | patch | +| 1.x and later | major | minor | patch | + +0.x never gets a major bump from a label. **Going to 1.0 is always the maintainer's manual decision**: they set the +draft's tag to `1.0.0` when publishing. Do not propose it, and do not edit the resolver on your own. + +When the maintainer has released 1.0.0, add a major resolver to `.github/release-drafter.yml` (and nothing else) in +its own PR: + +```yaml +version-resolver: + major: + labels: [breaking] + minor: + labels: [feature, enhancement] + default: patch +``` + +## In the PR body + +A `breaking` PR states what a consumer must change, in a **Breaking** line (see the pr skill). diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md new file mode 100644 index 0000000..6b9a0d6 --- /dev/null +++ b/.claude/skills/commit/SKILL.md @@ -0,0 +1,95 @@ +--- +name: commit +description: Stage relevant files and create a well-formed git commit. Use this when the user asks to commit changes, save work, or create a commit. +--- + +# Commit Skill + +Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing the commit message. + +Creates a clean, well-formed commit following this project's conventions. + +## Steps + +### 1. Check for project hooks + +If the repo has a hook runner, ensure it is installed before committing. Common patterns: + +```bash +# Husky.Net (dotnet) +if [ -f .husky/task-runner.json ] && [ ! -f .husky/_/husky.sh ]; then + dotnet tool restore && dotnet husky install +fi + +# Husky (Node) +# hooks install automatically via npm ci / npm install + +# lefthook +if [ -f lefthook.yml ] || [ -f .lefthook.yml ]; then + lefthook install +fi +``` + +Do not use `--no-verify`. + +### 2. Understand what changed + +```bash +git status +git diff +git diff --staged +git log --oneline -5 +``` + +### 3. Stage files + +Stage specific files by name — never `git add -A` or `git add .` blindly. Exclude: +- `.env` files or anything with secrets/credentials +- Large binaries not already tracked +- Unrelated changes to the task at hand + +### 4. Write the commit message + +- **First line**: Imperative mood, ≤72 chars, no trailing period. Front-load the outcome — a reader scanning `git log` sees this line only. +- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory. Follow the sentence mechanics in `writing-style.md`. +- **Trailer**: Add a `Co-Authored-By:` line that identifies the model that helped write this commit. Use whatever attribution feels accurate — the model name you know yourself to be running as, or simply `Claude` if you are uncertain. The address is always `noreply@anthropic.com`. The point is honest attribution, not a precise version string. + +Always pass the message via HEREDOC to avoid shell escaping issues: + +```bash +git commit -m "$(cat <<'EOF' +Title here + +Optional body explaining why. + +Co-Authored-By: Claude +EOF +)" +``` + +### 5. Handle hook failures + +If a git hook fails: +1. Read the error output carefully +2. Fix the underlying issue (formatting, linting, type errors — whatever the hook checks) +3. Re-stage the affected files +4. Create a **new commit** — never `git commit --amend` for a failed commit, and never use `--no-verify` + +### 6. Verify success + +```bash +git status +``` + +Confirm a clean working tree. + +### 7. Refresh the PR description if one exists + +```bash +gh pr view --json number,url,isDraft,baseRefName --jq '{number,url,isDraft,baseRefName}' 2>/dev/null +``` + +- **No PR** → done. Say nothing. +- **PR exists** → compare the current body against the current diff versus the PR's base branch. A PR description always describes the current diff against the base branch. It is never a log of the commits on the branch and never records the direction the work took. If any section (`## What`, `## Verify`, or the lead paragraph) no longer describes that diff, the description is stale. +- **Stale description** → read and follow [pr](../pr/SKILL.md)'s update path (step 7). Do not hand-edit the body inline from the commit skill. State plainly what was refreshed. +- **Still accurate** → state that the description is still accurate. No edit needed. diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md new file mode 100644 index 0000000..69c031b --- /dev/null +++ b/.claude/skills/pr/SKILL.md @@ -0,0 +1,162 @@ +--- +name: pr +description: Create a GitHub pull request with a focused why/what body. Use when the user asks to open a PR, create a pull request, or ship a branch. +--- + +# PR Skill + +Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing anything. + +Creates a GitHub PR body that a newcomer can orient from in under a minute: front-loaded outcome, grounded Why, behaviour-led What, verifiable by the reviewer. + +## Steps + +### 1. Understand the branch + +```bash +git status +git log main..HEAD --oneline +git diff main...HEAD --stat +``` + +### 2. Commit uncommitted work if needed + +If the working tree has changes that belong in this PR, read and follow [commit](../commit/SKILL.md) first. Do not commit inline. Do not skip hooks. + +### 3. Push (if needed) + +```bash +git push -u origin HEAD +``` + +### 4. Write the PR title + +- ≤70 characters, imperative mood, no trailing period +- States what changed at a human level — not a file list, not a symbol name +- No `[bug]` / `[feature]` / `[chore]` prefixes — the label carries the type + +### 5. Write the PR body + +Required structure: + +``` + + +**Prompt summary:** + +## Why + + +## What + +#### + + +## Verify + +``` + +Conditional add-ons — each is one or two sentences with a bold lead-in, no heading: + +- **Breaking** — what a consumer must change and when it bites them. +- **Out of scope** — a gap this PR deliberately leaves, so a reviewer does not raise it as a finding. +- **Risk** — shared or production state this touches. Required when the change reaches infrastructure, credentials, or shared data stores. +- **Stack** — position and links when this is one of several stacked PRs: `3 of 5, on top of [#42](https://github.com/org/repo/pull/42)`. A bare `Stack: 3/5` with no links is not enough. + +**Do not** include bullet lists of changed files. Do not summarize what the diff already states plainly. + +### 6. Apply exactly one release label + +The `pr-labels` check fails a PR without exactly one of these, and release-drafter turns them into the next version: + +| Label | Use when | Version | +|---|---|---| +| `breaking` | A consumer must change something after upgrading (see [breaking-changes](../breaking-changes/SKILL.md)) | 0.x: minor, 1.x+: major | +| `feature` | A new capability | minor | +| `enhancement` | An existing capability improved | minor | +| `bug` / `fix` | A defect in existing behaviour is fixed | patch | +| `documentation` | Docs only | patch | +| `chore` | Cleanup, refactor, internal restructure; no user-visible change | patch | +| `dependencies` | Dependency version bumps | patch | +| `ci` | Build and automation | patch | +| `changelog:skip` | Should not appear in the release notes | patch | + +### 7. Check whether a PR already exists + +```bash +gh pr view --json number,url,baseRefName --jq '{number,url,baseRefName}' 2>/dev/null +``` + +**If a PR exists — update it.** + +Rebuild the body from the cumulative diff against the PR's own base branch (not a hardcoded `main`): + +```bash +git diff origin/...HEAD --stat +git diff origin/...HEAD +``` + +Write the description of **the current diff against the base** — never a log of the commits on the branch and never an "update" or "addendum" appended to the old body. Any section of the old body that no longer matches the diff is wrong, not history. Replace it. + +- Preserve the original `**Prompt summary:**` verbatim unless the ask itself changed; extend it rather than replace it when scope was added. +- Reassess the label — added commits can shift a `chore` to a `bug`. +- Apply in one call: + +```bash +gh pr edit --title "" --body "$(cat <<'EOF' +<new body> +EOF +)" +``` + +Add or remove the label only if it changed: + +```bash +gh pr edit --add-label "<new-label>" --remove-label "<old-label>" +``` + +**If no PR exists — create it.** Proceed to step 8. + +### 8. Create the PR + +One call — title, label, and body together. No follow-up `gh pr edit`: + +```bash +gh pr create --title "<title>" --label "<label>" --body "$(cat <<'EOF' +<lead sentence(s)> + +**Prompt summary:** ... + +## Why + +... + +## What + +#### ... + +... + +## Verify + +```bash +<command> +``` +EOF +)" +``` + +### 9. Return the PR URL + +Always print the URL so the user can open it directly. diff --git a/.claude/skills/releasing/SKILL.md b/.claude/skills/releasing/SKILL.md new file mode 100644 index 0000000..2ec80dd --- /dev/null +++ b/.claude/skills/releasing/SKILL.md @@ -0,0 +1,49 @@ +--- +name: releasing +description: Release this repository. Use when the user asks to release, ship a version, publish to NuGet, or check what the next version will be. +--- + +# Release + +Releases are never cut from a pushed tag. release-drafter keeps a **draft release** up to date from the labels of +merged pull requests; **publishing that draft** creates the tag and runs `.github/workflows/ci.yml` on it, whose `release` job builds +any binary assets, packs at the tag's version (MinVer) and pushes to nuget.org with trusted publishing. +In this repository the same run's `publish-npm` job publishes `@nullean/journeys` to npm, also with trusted +publishing, and both jobs run in the `release` environment. + +## Steps + +1. Look at the draft and the version it resolved: + + ```bash + mise run release + ``` + + No draft means nothing labelled has merged since the last release, or the release-drafter workflow failed: + `gh run list --workflow release-drafter.yml --limit 3`. + +2. Check the version against the rules in [breaking-changes](../breaking-changes/SKILL.md). In 0.x a `breaking` PR + bumps the minor version. **Never** pick 1.0.0 yourself: that is the maintainer's call. + +3. Publish only when the user asked for it: + + ```bash + mise run release publish + ``` + + The maintainer often promotes the draft from the GitHub UI instead; both do the same. + +4. Follow the run and report the outcome, packages and assets included: + + ```bash + gh run watch "$(gh run list --workflow ci.yml --event release --limit 1 --json databaseId --jq '.[0].databaseId')" + gh release view <tag> + ``` + +## When it fails + +- Re-run the failed jobs (`gh run rerun <id> --failed`). The push uses `--skip-duplicate` and asset uploads use + `--clobber`, so a re-run is safe. +- `trusted publishing` errors mean nuget.org's policy no longer names this repo's `ci.yml`. Only the maintainer can + fix that on nuget.org. +- Never delete a published tag or release to retry. Fix forward with a patch release. diff --git a/.claude/skills/upgrade-deps/SKILL.md b/.claude/skills/upgrade-deps/SKILL.md new file mode 100644 index 0000000..31df9c6 --- /dev/null +++ b/.claude/skills/upgrade-deps/SKILL.md @@ -0,0 +1,32 @@ +--- +name: upgrade-deps +description: Update NuGet packages, .NET tools, the SDK or GitHub Actions. Use when the user asks to bump, upgrade or update dependencies, or to triage dependabot PRs. +--- + +# Upgrade dependencies + +Versions live in one place each: + +| What | Where | +|---|---| +| NuGet packages | `Directory.Packages.props` (Central Package Management); never put `Version=` on a `PackageReference` | +| .NET tools | `.config/dotnet-tools.json` | +| .NET SDK | `global.json` only; mise reads it from there | +| other CLI tools | `mise.toml` `[tools]` | +| GitHub Actions | pinned by commit SHA with a `# vX.Y.Z` comment; reusable workflows from `nullean/.github` likewise | + +## Steps + +1. Branch first. One concern per PR: SDK bumps, package bumps and action bumps go separately when any of them changes + behaviour. +2. Find what is outdated: `dotnet list package --outdated`, plus `dotnet tool list` against nuget.org. +3. Bump, then `mise run ci`. A new SDK also needs `mise install`. +4. Read the release notes of every major bump and say in the PR body what changed for this repo. +5. Label the PR `dependencies` unless the bump forces consumers to change something; then it is `breaking` (see + [breaking-changes](../breaking-changes/SKILL.md)). + +For dependabot PRs: check CI, read the changelog for majors, merge groups that pass. Do not rebase a dependabot PR by +hand; comment `@dependabot rebase`. + +Pin an action to the commit its release tag points at: +`gh api repos/<owner>/<action>/commits/<tag> --jq .sha`. diff --git a/.claude/skills/writing-style.md b/.claude/skills/writing-style.md new file mode 100644 index 0000000..1f873e8 --- /dev/null +++ b/.claude/skills/writing-style.md @@ -0,0 +1,134 @@ +# Writing style for commits, PRs, and issues + +Every commit message, PR body, and issue filed in this repo follows these rules. +Skills that write those artifacts read this file first. + +--- + +## Governing principles (ISO 24495-1) + +- **Relevant** — write for a reviewer who has not seen the branch. Cut whatever the diff already states plainly. +- **Findable** — the first sentence states the outcome. A newcomer reads it and knows whether the change concerns them. +- **Understandable** — plain words, short sentences, no assumed context. +- **Usable** — after reading, the reviewer can evaluate, revert, or reproduce. + +--- + +## Sentence mechanics (ASD-STE100, adapted) + +*The ASD-STE100 sentence rules apply here. Its ~900-word approved vocabulary does not — it rejects `assembler`, `idempotent`, and `reconciliation` and its clipped imperative register produces mechanical prose. Take the mechanics, drop the dictionary.* + +- Active voice. Name the actor. "A retry clears the lock", not "The lock is cleared on retry". +- One idea per sentence. Around 25 words maximum. +- Six sentences maximum per paragraph. +- Present tense for how the code behaves now; past tense only for what it used to do. +- No noun cluster longer than three words. "shallow clone lock collision guard" → "a guard against lock collisions in shallow clones". +- One term per concept, every time. Do not alternate *job* / *step* / *task* for the same thing. +- Keep articles: "The assembler runs", not "Assembler runs". +- One subordinate clause per sentence. No em-dash pile-ups. + +--- + +## Fenced blocks for anything runnable + +A command, a config snippet, a YAML fragment, an error message, or a stack trace goes in a fenced code block with a language tag — not inline, however short. + +Inline backticks *name* a thing. A fenced block holds something the reader runs, pastes, or reads as output. + +- `--no-delete` inline (naming the flag) +- Command in a block: + ```bash + my-tool deploy --no-delete preview + ``` + +Test names go in `#` comments inside the block next to the command that runs them, not in prose beside it: + +```bash +dotnet test tests/MyProject.Tests/ +# MyMethod_Scenario_Expected — the case being verified +``` + +--- + +## Backticks, used liberally + +Every identifier gets backticks, every time, including repeat mentions. This covers: + +- Types, methods, properties, fields: `MyService.Fetch`, `Cache.ClearStale` +- CLI commands and flags: `my-tool`, `--no-delete`, `--verbose` +- Env vars: `MY_APP_API_KEY` +- File and directory paths: `ci.yml`, `src/MyProject/` +- YAML keys (with trailing colon): `output:`, `items:` +- Config values, labels, package names, branch names, exit codes + +Prose that names a symbol bare is wrong even when it reads fine: + +| Wrong | Right | +|---|---| +| MyService.Fetch returned void | `MyService.Fetch` returned `void` | +| pass --no-delete | pass `--no-delete` | +| the synthetics job in ci.yml | the `synthetics` job in `ci.yml` | + +Do **not** backtick prose nouns that merely share a name with code — the assembler, the scrubber, a profile — unless you mean the literal identifier. + +--- + +## Linking to issues and pull requests + +Link liberally. Any issue, PR, or discussion named in prose gets a link — first mention and every repeat. + +**Always the full URL.** Never a bare `#3855`, and never a short form like `elastic/repo#3855`. GitHub resolves `#num` against whatever repo the current page lives in — the same body pasted into a different repo silently points at the wrong thing. + +Markdown form: `[#3855](https://github.com/elastic/docs-builder/pull/3855)`. Keep the `#num` as link text so it stays scannable in a git log or review tool that strips HTML. + +Cross-repo mentions include the org and repo in the link text: + +``` +[elastic/docs-actions#412](https://github.com/elastic/docs-actions/pull/412) +``` + +| Wrong | Right | +|---|---| +| See #42 for context | See [#42](https://github.com/org/repo/pull/42) for context | +| other-org/other-repo#7 fixed this | [other-org/other-repo#7](https://github.com/other-org/other-repo/pull/7) fixed this | +| Refs #99 | Refs [#99](https://github.com/org/repo/issues/99) | + +--- + +## Anti-mechanical rules for "What" sections + +`## What` uses `####` subheadings, not bullet points. Each subheading names the thing that changed (a file, a command, a concept). The prose under it states what changed and why it matters — two to four sentences, same plain-language rules as everywhere else. + +Lead with the behaviour change; name the symbol second when the reviewer needs it to find the code. + +| Wrong | Right | +|---|---| +| `` `Cache.ClearStale` sweeps `*.lock` files before each retry `` | A retry clears stale `*.lock` files before it runs | +| `` **`BuildService.Build`**: captures the `GenerateAll` result `` | The build result is captured and written to the output directory | + +**Banned openers** for the prose paragraph: +- "Added", "Updated", "Changed", "Refactored", "Modified" +- Any sentence that starts with a file path or a symbol name +- Any paragraph that only restates the subheading + +**Three to five `####` sections in a "What".** More than five is a signal the change should be split. + +--- + +## Before/after examples + +These are the rules in action. If a new rule does not survive this test, the rule is wrong. + +**`## What`, first bullet:** + +> ❌ `Cache.ClearStale(IFileSystem, ...)` sweeps `*.lock` files under `.git/` before each retry. Called only from the retry path — never before attempt 1, where a lock could belong to a concurrent process. + +> ✅ A retry clears stale `*.lock` files before it runs. The first attempt is never affected — a lock there can belong to a live process. + +**Opening of `## Why`:** + +> ❌ [#42](https://github.com/org/repo/pull/42) tried to fix stale pool listings by bringing back `registry.json`. That approach was rejected… + +> ✅ Scrubbing strips `prs:` from the public copies of private-repo entries. `--prs` joined only on that YAML field, so those entries dropped out with no error. + +The history of a rejected PR is not the problem this PR solves. Lead with the problem. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..d741245 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,32 @@ +version: 2 +updates: + - package-ecosystem: nuget + directory: / + schedule: + interval: weekly + cooldown: + default-days: 7 + labels: [dependencies] + groups: + nuget: + patterns: ["*"] + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + cooldown: + default-days: 7 + labels: [dependencies] + groups: + actions: + patterns: ["*"] + - package-ecosystem: npm + directory: /js/journeys + schedule: + interval: weekly + cooldown: + default-days: 7 + labels: [dependencies] + groups: + npm: + patterns: ["*"] diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml new file mode 100644 index 0000000..45a69fc --- /dev/null +++ b/.github/release-drafter.yml @@ -0,0 +1,30 @@ +# Drafts the next release from merged pull request labels. Publishing the draft releases (see workflows/release.yml). +# +# 0.x rule: `breaking` bumps the minor version, never the major. Going to 1.0 is a manual decision: edit the draft's +# tag to 1.0.0 when publishing, then move `breaking` from minor to a `major:` resolver (the breaking-changes skill). +name-template: '$RESOLVED_VERSION' +tag-template: '$RESOLVED_VERSION' +change-template: '- $TITLE by @$AUTHOR in #$NUMBER' +template: | + $CHANGES + + **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...$RESOLVED_VERSION +categories: + - title: '💥 Breaking Changes' + labels: [breaking] + - title: '✨ Features' + labels: [feature, enhancement] + - title: '🐛 Bug Fixes' + labels: [bug, fix] + - title: '📝 Documentation' + labels: [documentation] + - title: '🧰 Maintenance' + labels: [chore, dependencies] + - title: '⚙️ Automation' + labels: [ci] +exclude-labels: + - 'changelog:skip' +version-resolver: + minor: + labels: [breaking, feature, enhancement] + default: patch diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f99f73..279c0ea 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,13 +5,15 @@ on: push: branches: - main - tags: - - "*.*.*" + # Publishing the release-drafter draft creates the tag and releases: every gate below runs on the released commit + # first. nuget.org's and npm's trusted publishing name this file, so releasing stays here. + release: + types: [published] workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }} + cancel-in-progress: ${{ github.event_name != 'release' }} permissions: contents: read @@ -250,19 +252,19 @@ jobs: "$GITHUB_WORKSPACE/build/smoke-cli.sh" "$temp/tool/$cdp" "$GITHUB_WORKSPACE/build/smoke-cli.sh" dotnet dnx "Nullean.Cdp.Cli@$root" --add-source "$feed" --yes - # Publishing to nuget.org: a pushed tag (X.Y.Z or X.Y.Z-pre.N) publishes, and only once every gate above has passed. - # Pushing the tag is the release decision. A failed run can be re-run: pushing is skipped for packages already there. - # The 'release' environment only lets tags deploy, and nuget.org's trusted publishing policy names it, so no API key - # is stored. + # Publishing to nuget.org: a published release (its tag X.Y.Z or X.Y.Z-pre.N) publishes, and only once every gate + # above has passed. Publishing the release-drafter draft is the release decision; pushing a tag alone does nothing. + # A failed run can be re-run: pushing is skipped for packages already there. The 'release' environment only lets tags + # deploy, and nuget.org's trusted publishing policy names it, so no API key is stored. release: - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') + if: github.event_name == 'release' needs: [build, aot-pack, tool-pack, tool-smoke] runs-on: ubuntu-latest name: Publish to nuget.org timeout-minutes: 20 environment: release permissions: - contents: write # the GitHub release + contents: write # attach the packages to the release id-token: write # trusted publishing: exchange the workflow's OIDC token for a short-lived key steps: @@ -316,23 +318,18 @@ jobs: done push "$root" - # A GitHub release for the tag, with notes generated from the pull requests since the previous one, and the - # packages attached. After publishing, so a release always means the packages are on nuget.org. - - name: GitHub release + # The release already exists (it is the published draft); attach the packages to it. After publishing, so the + # attached packages are always the ones on nuget.org. --clobber makes a re-run safe. + - name: Attach the packages to the release shell: bash env: GH_TOKEN: ${{ github.token }} - run: | - pre="" - case "$GITHUB_REF_NAME" in *-*) pre="--prerelease" ;; esac - gh release create "$GITHUB_REF_NAME" packages/*.nupkg --repo "$GITHUB_REPOSITORY" --verify-tag $pre \ - --title "$GITHUB_REF_NAME" --generate-notes \ - --notes "Packages: https://www.nuget.org/packages?q=Nullean.Cdp" - - # The npm package is published like the NuGet ones: from a pushed tag, in the `release` environment, - # through trusted publishing (the workflow's OIDC token; no token is stored). The tag gives the version. + run: gh release upload "$GITHUB_REF_NAME" packages/*.nupkg --repo "$GITHUB_REPOSITORY" --clobber + + # The npm package is published like the NuGet ones: from a published release, in the `release` environment, + # through trusted publishing (the workflow's OIDC token; no token is stored). The release's tag gives the version. publish-npm: - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') + if: github.event_name == 'release' needs: [build, journeys-js] runs-on: ubuntu-latest name: Publish @nullean/journeys to npm diff --git a/.github/workflows/pr-labels.yml b/.github/workflows/pr-labels.yml new file mode 100644 index 0000000..cd16364 --- /dev/null +++ b/.github/workflows/pr-labels.yml @@ -0,0 +1,12 @@ +name: pr-labels + +on: + pull_request: + types: [opened, reopened, labeled, unlabeled, synchronize] + +permissions: {} + +jobs: + release-label: + uses: nullean/.github/.github/workflows/pr-labels.yml@83ef343759c443afe1964e9c33327527f8677b05 # v1.3.0 + permissions: {} diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml new file mode 100644 index 0000000..179be65 --- /dev/null +++ b/.github/workflows/release-drafter.yml @@ -0,0 +1,15 @@ +name: release-drafter + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: {} + +jobs: + draft: + uses: nullean/.github/.github/workflows/release-drafter.yml@83ef343759c443afe1964e9c33327527f8677b05 # v1.3.0 + permissions: + contents: write + pull-requests: read diff --git a/AGENTS.md b/AGENTS.md index 568de93..7db344f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,7 @@ mise run pack # build and pack the libraries (CI packs the native AO mise run ci # what CI runs on every push: build, test, pack, and the js/journeys job mise run docs # build the docs and serve them (needs docs-builder, see scripts/docs.sh) mise run check # workflow security checks (zizmor) +mise run release # show the release draft; `mise run release publish` releases ``` Without mise: @@ -32,6 +33,16 @@ a real Chrome skip with a reason when none is found; CI sets `CDP_BROWSER_REQUIR The CLI: `dotnet run --project src/Nullean.Cdp.Cli -- run <journey> --base-url <url or folder>`. `build/smoke-cli.sh <command that runs cdp>` smoke-tests a built or installed tool against the fixture site. +## Releasing + +release-drafter keeps a draft release current from the labels of merged pull requests; every pull request carries +exactly one release label (`pr-labels.yml` enforces it). **Publishing the draft** releases: it creates the tag and runs +`ci.yml` on it, whose `release` and `publish-npm` jobs push the NuGet packages and `@nullean/journeys` with trusted +publishing once every other job has passed, then attach the packages to the release. Pushing a tag on its own does +nothing. In 0.x a `breaking` label bumps the minor version; 1.0 is the maintainer's call. See the +[releasing](.claude/skills/releasing/SKILL.md) and [breaking-changes](.claude/skills/breaking-changes/SKILL.md) +skills, and `mise run release` for the current draft. + ## Rules - No dependencies beyond the BCL in `Nullean.Cdp`. Libraries set `IsAotCompatible`: JSON through `Utf8JsonReader` and diff --git a/DECISIONS.md b/DECISIONS.md index 90fe9cb..6465c3c 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -494,18 +494,20 @@ and where data can go is what holds. ## Releasing -As nullean/entities and nullean/curb do it: push a tag (`0.1.0`; MinVer takes the version from it). The `release` -job runs for a pushed tag, needs every other job including the tool smoke tests, checks that every package carries +As every nullean repository does it: release-drafter keeps a draft release current from the labels of merged pull +requests (`.github/release-drafter.yml`; in 0.x `breaking` bumps the minor version), and **publishing the draft** is +the release decision. Publishing creates the tag (`0.1.0`; MinVer takes the version from it) and fires +`release: published` on `ci.yml`, which runs every job on the released commit. Pushing a tag on its own releases +nothing. The `release` job needs every other job including the tool smoke tests, checks that every package carries the tag's version, and publishes through nuget.org trusted publishing (`NuGet/login` with the organisation's -`NUGET_USER`; no API key is stored). Pushing the tag is the release decision, so tag only what is meant to ship; a -failed run is fixed and re-run (the pushes skip what is already there). It was a manual run on the tag, as in -nullean/snapshots, until the repositories were aligned. The `release` environment only lets tags deploy. The root -tool package is pushed last, after the per-RID and `any` packages it points at. Once the packages are on nuget.org the job creates the GitHub release -for the tag (`gh release create --generate-notes`, notes from the pull requests since the previous tag, the -packages attached, a `-` version marked as a prerelease); the job needs `contents: write` for it. Versions stay 0.x -until the owner says otherwise. - -`@nullean/journeys` (js/journeys) goes out in the same tag run, as the `publish-npm` job: same `release` environment, +`NUGET_USER`; no API key is stored). The policy names `ci.yml`, which is why releasing stays in it rather than in a +workflow of its own. A failed run is fixed and re-run (the pushes skip what is already there). The `release` +environment only lets tags deploy; a published release's ref is its tag. The root tool package is pushed last, after +the per-RID and `any` packages it points at. Once the packages are on nuget.org the job attaches them to the release +(`gh release upload --clobber`, so a re-run is safe); the notes are the draft's. The job needs `contents: write` for +it. Versions stay 0.x until the owner says otherwise. + +`@nullean/journeys` (js/journeys) goes out in the same release run, as the `publish-npm` job: same `release` environment, no stored token, npm trusted publishing (`id-token: write`; npm 11.5.1 or later, checked; provenance is automatic for a public repository). The tag is the version (`npm pkg set version`; package.json keeps a placeholder), a `-` version publishes under the `next` dist-tag, and a version already on npm is skipped so a re-run is safe. The trusted publisher diff --git a/mise.toml b/mise.toml index ed43e19..439226b 100644 --- a/mise.toml +++ b/mise.toml @@ -60,3 +60,23 @@ run = [ ''', "cd js/journeys && npm ci && npm run typecheck && npm run build && npm pack --dry-run && npm test && npm run test:live", ] + +[tasks.release] +description = "Open the release-drafter draft; `mise run release publish` publishes it, which releases" +run = ''' +#!/usr/bin/env bash +set -euo pipefail +tag=$(gh release list --json tagName,isDraft --jq '[.[] | select(.isDraft)][0].tagName') +if [ -z "$tag" ]; then + echo "no draft release; merge a labelled pull request to main first" >&2 + exit 1 +fi +if [ "${1:-}" = "publish" ]; then + gh release edit "$tag" --draft=false + echo "published $tag; the release workflow is now packing and pushing it" +else + gh release view "$tag" + echo + echo "publish with: mise run release publish (or promote the draft on github.com)" +fi +'''