Skip to content

[codex] clarify changeset release tracking #1148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 3 commits into from
Jun 1, 2026
Merged

[codex] clarify changeset release tracking #1148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7d5d0f7
clarify changeset release tracking
TabishB Jun 1, 2026
4046728
Merge branch 'main' into codex/release-tracking-guidance
TabishB Jun 1, 2026
e46c659
Merge branch 'main' into codex/release-tracking-guidance
TabishB Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions .changeset/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,12 @@ Follow the prompts to select version bump type and describe your changes.

## Workflow

1. **Add a changeset** — Run `pnpm changeset` locally before or after your PR
2. **Version PR** — CI opens/updates a "Version Packages" PR when changesets merge to main
3. **Release** — Merging the Version PR triggers npm publish and GitHub Release
1. **Choose the release path**: Maintainers decide whether a PR follows the normal release cadence or gets dedicated release tracking.
2. **Add dedicated release tracking**: When a maintainer asks for a changeset, run `pnpm changeset` locally before or after your PR.
3. **Version PR**: CI opens/updates a "Version Packages" PR when changesets merge to main.
4. **Release**: Merging the Version PR triggers npm publish and GitHub Release.

> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI.
> **Note:** The default path is the normal release cadence. Add a changeset when a maintainer or release owner wants dedicated release notes and version tracking for the PR. Versioning (`changeset version`) and publishing happen automatically in CI.

## Template

Expand Down Expand Up @@ -54,22 +55,23 @@ Include only the sections relevant to your change.

| Type | When to use | Example |
|------|-------------|---------|
| `patch` | Bug fixes, small improvements | Fixed crash when config missing |
| `patch` | Release-tracked bug fixes, small improvements | Fixed crash when config missing |
| `minor` | New features, non-breaking additions | Added `--verbose` flag |
| `major` | Breaking changes, removed features | Renamed `init` to `setup` |

## When to Create a Changeset

**Create one for:**
- New features or commands
- Bug fixes that affect users
**Use dedicated release tracking for:**
- New features or commands selected for release
- Notable bug fixes or hotfixes requested by a maintainer/release owner
- Breaking changes or deprecations
- Performance improvements users would notice
- Performance improvements users would notice and that are planned for release

**Skip for:**
**Use the normal release cadence for:**
- Routine bug fixes that fit the normal release cadence
- Documentation-only changes
- Test additions/fixes
- Internal refactoring with no user impact
- Internal refactoring that preserves user behavior
- CI/tooling changes

## Writing Good Descriptions
Expand Down
34 changes: 27 additions & 7 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ jobs:
run: git checkout -- flake.nix || true

validate-changesets:
name: Validate Changesets
name: Validate Release Tracking

@coderabbitai coderabbitai Bot Jun 1, 2026

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.

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check branch protection rules for the main branch

gh api repos/{owner}/{repo}/branches/main/protection \
  --jq '.required_status_checks.contexts[]' 2>/dev/null || echo "Unable to fetch branch protection rules. Please verify manually in repository settings."

Repository: Fission-AI/OpenSpec

Length of output: 318

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE=".github/workflows/ci.yml"
echo "== File head =="
head -n 40 "$FILE" || true

echo "== Jobs around validate-changesets / required-checks-pr =="
# Show region around the referenced line numbers (if file is long enough)
sed -n '200,340p' "$FILE" || true

echo "== Exact job keys present =="
rg -n "^  [a-zA-Z0-9_-]+:" "$FILE" || true

echo "== validate-changesets job block =="
# Try to locate the job key and print until next top-level job key
python3 - <<'PY'
import re, itertools, pathlib
p = pathlib.Path(".github/workflows/ci.yml")
lines = p.read_text().splitlines()
key_pat = re.compile(r'^\s{2}([a-zA-Z0-9_-]+):\s*$')
target = "validate-changesets"
idxs = [i for i,l in enumerate(lines) if key_pat.match(l) and key_pat.match(l).group(1)==target]
if not idxs:
    print("No job key named validate-changesets found (will fall back to searching for name: Validate Release Tracking).")
    sys_exit=False
else:
    i=idxs[0]
    # print until next job key at indent 2
    for j in range(i, len(lines)):
        if j!=i and key_pat.match(lines[j]) and key_pat.match(lines[j]).group(1)!=target:
            break
        print(f"{j+1}:{lines[j]}")
PY

echo "== required-checks-pr job block =="
python3 - <<'PY'
import re, pathlib
p = pathlib.Path(".github/workflows/ci.yml")
lines = p.read_text().splitlines()
key_pat = re.compile(r'^\s{2}([a-zA-Z0-9_-]+):\s*$')
target = "required-checks-pr"
idxs = [i for i,l in enumerate(lines) if key_pat.match(l) and key_pat.match(l).group(1)==target]
if not idxs:
    print("No job key named required-checks-pr found.")
else:
    i=idxs[0]
    for j in range(i, len(lines)):
        if j!=i and key_pat.match(lines[j]) and key_pat.match(lines[j]).group(1)!=target:
            break
        print(f"{j+1}:{lines[j]}")
PY

echo "== Match for Validate Release Tracking =="
rg -n "Validate Release Tracking" "$FILE" || true

echo "== Check for needs references to validate-changesets =="
rg -n "needs:.*validate-changesets|validate-changesets" "$FILE" || true

Repository: Fission-AI/OpenSpec

Length of output: 9758

Validate Release Tracking doesn’t block merges via required-checks-pr

In .github/workflows/ci.yml, required-checks-pr only depends on test_pr, lint, and nix-flake-validate (needs: [test_pr, lint, nix-flake-validate]), so failures in validate-changesets / “Validate Release Tracking” won’t cause required-checks-pr to fail. This means PRs can merge even when changeset validation fails (if branch protection only requires required-checks-pr). Also, the GitHub branch-protection API check failed with 403 (“Resource not accessible by integration”), so the exact required checks can’t be confirmed here.

Fix by either:

  • Adding validate-changesets to required-checks-pr.needs and failing when needs.validate-changesets.result != success, or
  • Marking “Validate Release Tracking” as a required status check in branch protection.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml at line 245, The required-checks-pr job currently
only needs [test_pr, lint, nix-flake-validate] so failures in
validate-changesets (“Validate Release Tracking”) don't block merges; update the
required-checks-pr job in .github/workflows/ci.yml to include
validate-changesets in its needs array and add a step that checks
needs.validate-changesets.result != 'success' and fails (or exits non-zero) when
it's not successful so the job fails when validate-changesets fails; reference
the job names required-checks-pr and validate-changesets when making the change.

runs-on: ubuntu-latest
if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
steps:
Expand All @@ -251,27 +251,47 @@ jobs:
with:
fetch-depth: 0

- name: Determine release tracking
id: changed-changesets
run: |
changed_changesets="$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD -- '.changeset/*.md' ':!.changeset/README.md')"
if [[ -n "$changed_changesets" ]]; then
echo "has_changesets=true" >> "$GITHUB_OUTPUT"
{
echo "files<<EOF"
echo "$changed_changesets"
echo "EOF"
} >> "$GITHUB_OUTPUT"
else
echo "has_changesets=false" >> "$GITHUB_OUTPUT"
echo "This PR follows the normal release cadence; continuing with standard validation"
fi

- name: Setup pnpm
if: steps.changed-changesets.outputs.has_changesets == 'true'
uses: pnpm/action-setup@v4
with:
version: 9

- name: Setup Node.js
if: steps.changed-changesets.outputs.has_changesets == 'true'
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'

- name: Install dependencies
if: steps.changed-changesets.outputs.has_changesets == 'true'
run: pnpm install --frozen-lockfile

- name: Validate changesets
- name: Validate release-tracked changesets
if: steps.changed-changesets.outputs.has_changesets == 'true'
env:
CHANGESET_FILES: ${{ steps.changed-changesets.outputs.files }}
run: |
if command -v changeset &> /dev/null; then
pnpm exec changeset status --since=origin/main
else
echo "Changesets not configured, skipping validation"
fi
echo "Validating changed changesets:"
printf '%s\n' "$CHANGESET_FILES"
pnpm exec changeset status --since=origin/main

required-checks-pr:
name: All checks passed
Expand Down
Loading