PR Changeset Skill

This skill creates the changeset file that tells the release pipeline what changed and how to version it. Every change to a package needs one — even small fixes — because changesets are how versions get bumped and changelogs get generated automatically.

Versioning Rules

Patch (bug fixes only)

• Use for: Bug fixes, typos, documentation fixes, minor refactors that don't change behavior
• Format: Maximum 2 lines
• Example:

  Fix validation error in text field when value is null
  

Minor (feature improvements)

• Use for: New features, enhancements, non-breaking API changes

• Format: Explain the new feature and any steps required to implement it

• Example:

  Add support for custom field validation functions
  
  You can now pass a custom validation function to field configs:
  
  fields: {
    email: text({
      validation: {
        custom: async (value) => {
          if (!value.endsWith('@company.com')) {
            throw new Error('Must use company email')
          }
        }
      }
    })
  }
  

Major (breaking changes)

• Use for: Breaking API changes, removed features, changed behavior

• ONLY when user explicitly requests a major version bump

• Format: Detailed explanation of breaking changes and migration steps

• Example:

  BREAKING: Remove deprecated `useAuth` hook
  
  The `useAuth` hook has been removed. Use `useSession` instead:
  
  // Before
  const { user } = useAuth()
  
  // After
  const { data: session } = useSession()
  const user = session?.user
  

Instructions

Step 1: Identify Changed Packages

1. Run git status or git diff to see which packages were modified
2. List all packages that have changes in packages/*/src/ or packages/*/package.json

Step 2: Determine Version Bump Type

For each changed package, ask yourself:

• Is this a bug fix? → Use patch
• Is this a new feature or enhancement? → Use minor
• Is this a breaking change? → Only use major if user explicitly requested it, otherwise ask user

Step 3: Create Changeset File

Changesets are stored in .changeset/ directory with random names. Use this format:

File name: .changeset/[random-words].md

• Generate random filename like: brave-lions-smile.md, quiet-trees-dance.md
• Use 3 random dictionary words separated by hyphens
• Must end with .md

File format:

---
'@opensaas/package-name': patch
---

Brief description of the change

For multiple packages:

---
'@opensaas/stack-core': minor
'@opensaas/stack-ui': patch
---

Description of changes affecting both packages

Step 4: Write the Changeset Description

For patch versions (bug fixes):

• Maximum 2 lines
• State what was fixed
• Be concise and clear

For minor versions (features):

• Explain what the feature does
• Provide code examples showing how to use it
• Include any configuration or setup steps
• Show before/after if applicable

For major versions (breaking changes):

• Clearly mark as BREAKING
• Explain what changed and why
• Provide migration guide with before/after code examples
• List any removed or changed APIs

Template

Use this template when creating changeset files:

Patch Template

---
'@opensaas/stack-[package]': patch
---

[One line describing the bug fix]

Minor Template

---
'@opensaas/stack-[package]': minor
---

[Feature description]

[Usage example with code]

Major Template

---
'@opensaas/stack-[package]': major
---

BREAKING: [What changed]

[Detailed explanation of the breaking change]

Migration guide:
// Before
[old code]

// After
[new code]

[Any additional steps required]

Examples

Example 1: Patch (Bug Fix)

File: .changeset/calm-eagles-rest.md

---
'@opensaas/stack-core': patch
---

Fix validation error in text field when value is null

Example 2: Minor (New Feature)

File: .changeset/brave-lions-smile.md

---
'@opensaas/stack-ui': minor
---

Add dark mode support to AdminUI component

You can now enable dark mode by passing the `theme` prop:

<AdminUI
  context={context}
  config={config}
  theme="dark"
/>

Or use system preference:

<AdminUI
  context={context}
  config={config}
  theme="system"
/>

Example 3: Multiple Packages (Minor)

File: .changeset/quiet-trees-dance.md

---
'@opensaas/stack-core': minor
'@opensaas/stack-auth': minor
---

Add support for custom session fields in access control

You can now access custom session fields in access control functions:

// In authConfig
authConfig({
sessionFields: ['userId', 'email', 'role', 'tenantId']
})

// In access control
access: {
operation: {
query: ({ session }) => {
return { tenantId: session.tenantId }
}
}
}

Example 4: Major (Breaking Change) - Only if explicitly requested

File: .changeset/ancient-stars-fall.md

---
'@opensaas/stack-core': major
---

BREAKING: Remove `getContext()` synchronous variant

The synchronous `getContext()` function has been removed. All context creation is now async.

Migration guide:

// Before
const context = getContext({ userId })

// After
const context = await getContext({ userId })

Make sure to add `async` to any functions that call `getContext()`:

// Before
function myAction() {
const context = getContext({ userId })
}

// After
async function myAction() {
const context = await getContext({ userId })
}

Common Mistakes to Avoid

1. Don't use major unless explicitly requested

   • Even significant features should be minor if they don't break existing code
   • Ask user first if you think a major bump is needed

2. Don't make patch descriptions too long

   • Keep it to 2 lines maximum
   • Just state what was fixed

3. Don't forget to include code examples for minor changes

   • Users need to understand how to use new features
   • Show concrete examples, not just descriptions

4. Don't create changesets for examples or non-package changes

   • Only create changesets for files in packages/*
   • Changes to examples/* don't need changesets

5. Don't use vague descriptions

   • Bad: "Fix bug"
   • Good: "Fix validation error in text field when value is null"

6. Don't forget to list all affected packages

   • If your change affects multiple packages, list them all
   • Use the same version bump type for related changes

Workflow

When working on a PR:

1. Make your code changes
2. Before committing, use this skill to create a changeset
3. Verify the changeset file was created in .changeset/
4. Commit both your changes AND the changeset file
5. Push to the PR branch

Troubleshooting

Q: Should I create one changeset per package or one for all changes? A: Create one changeset that lists all affected packages. Only create multiple changesets if you have unrelated changes.

Q: What if I'm not sure if it's patch or minor? A: Ask yourself: "Does this add new functionality or just fix existing functionality?" New = minor, fix = patch.

Q: What if the change is both a feature and a bug fix? A: Use minor (the higher version bump). Mention both aspects in the description.

Q: Do I need a changeset for documentation changes in packages? A: Yes, if the docs are in packages/*/src/ or affect the package. Use patch. Changes to example documentation don't need changesets.

Important Notes

• The changeset CLI doesn't work in this environment, so you must manually create the .changeset/*.md files
• Version bumping and publishing happens automatically in CI via changesets GitHub Action
• Every PR that changes package code MUST include a changeset file
• The monorepo uses pnpm workspaces - make sure package names match package.json