Release Process

November 11, 2025 · View on GitHub

How pgflow automatically releases packages to npm and JSR via CI.

TL;DR - The Two-PR Process

  1. 📝 Developer creates changeset + merges feature PR
  2. 🤖 CI creates "Version Packages" PR (updates versions & changelogs)
  3. ✅ Maintainer merges the Version Packages PR
  4. 🚀 CI publishes to npm + JSR automatically

All releases happen through GitHub Actions - no manual publishing.

Step-by-Step Process

1. Making Changes

When making changes to any package:

pnpm changeset  # Create changeset file

This will:

  • Ask which packages changed
  • Ask for version bump type (major/minor/patch)
  • Ask for changelog description

Then commit the .changeset/*.md file with the code changes.

2. Automatic Version PR

After feature PRs with changesets are merged to main:

🤖 CI automatically creates "Version Packages" PR containing:

  • Updated version numbers in all package.json files
  • Updated CHANGELOG.md files
  • Synced jsr.json versions (via update-jsr-json-version.sh)

Note

All pgflow packages use "fixed" versioning - they share the same version number.

3. Automatic Publishing

When the Version Packages PR is merged:

🚀 CI runs the release workflow (.github/workflows/release.yml):

# 1. Build all packages
pnpm nx run-many -t build

# 2. Publish to npm (all packages except edge-worker)
pnpm publish --recursive --filter=!./pkgs/edge-worker

# 3. Publish edge-worker to JSR
cd ./pkgs/edge-worker && jsr publish --allow-slow-types

# 4. Create and push git tags
pnpm changeset tag && git push --follow-tags
📦 Why npm first, then JSR?

edge-worker imports npm packages via npm:@pgflow/core@0.5.0. If JSR published first, it would reference non-existent npm versions.

Configuration Details

⚙️ Fixed Versioning Setup

.changeset/config.json:

{
  "fixed": [["@pgflow/*", "pgflow"]]
}

All pgflow packages share the same version and release together.

🔄 Version Syncing (npm → JSR)

update-jsr-json-version.sh automatically:

  • Copies version from package.json → jsr.json
  • Updates import versions: "@pgflow/core": "npm:@pgflow/core@0.5.0"

This keeps JSR packages in sync with npm versions.

Release Types

TypeVersion ExampleWhen to UseSee
Regular0.5.0Stable releasesThis doc
Snapshot0.0.0-fix-auth-...PR testingSNAPSHOT_RELEASES.md

CI Requirements

Important

Release workflow needs these GitHub secrets:

  • NPM_TOKEN - npm publishing
  • GITHUB_TOKEN - PR creation (auto-provided)
  • OIDC permissions - JSR publishing

Quick Reference

📝 Adding a Feature 
# 1. Make changes
# 2. Create changeset
pnpm changeset
# 3. Commit & push
# 4. Merge PR
# 5. Wait for Version PR → merge it
🐛 Fixing a Bug 
# 1. Fix bug
# 2. Create changeset (usually patch)
pnpm changeset
# 3. Commit & push
# 4. Merge PR
# 5. Wait for Version PR → merge it
🧪 Testing Before Release

Use snapshot releases - see SNAPSHOT_RELEASES.md

Troubleshooting

🛑 "No changesets found"

Run pnpm changeset before pushing. CI requires changesets for package changes.

🛑 Version mismatch npm/JSR
  • Check update-jsr-json-version.sh ran in Version PR
  • package.json and jsr.json versions must match
🛑 JSR publish fails
  • Already uses --allow-slow-types
  • Check JSR dashboard for specific errors
  • Ensure OIDC permissions are configured