Changesets

This repository uses Changesets to version packages and keep changelogs up to date.

Important

Changeset content becomes the release notes presented to consumers. Write summaries as if they will be read by end users of your packages.

TL;DR

• Create a changeset for consumer-affecting changes: New APIs, bug fixes, breaking changes → patch/minor/major
• Skip for internal-only work: Refactors, tests, tooling → no changeset unless repo-wide impact
• ALL markdown changes need changesets: Any changes to .md files → create changeset for @equinor/fusion-framework-docs (docs are linked/referenced)
• One package per changeset preferred: Group only identical changes across packages
• Directory: .changeset/ (singular) with package-prefixed filename
• Use pnpm changeset for guided creation; bot validates on PRs
• Summary: What changed, why it matters, migration notes if breaking

When to create a changeset

Decision Tree:

1. Are you on a feature/fix branch? → Check .changeset/ for existing changesets first
2. Is this a workspace root change? (monorepo config, tooling, CI) → Skip changeset entirely
3. Are you changing any .md files? → Create changeset for @equinor/fusion-framework-docs
4. All other package changes → Create changeset (patch/minor/major)
   • Even internal refactoring requires a changeset for proper versioning
   • Internal changes use patch with clear "internal only" notes

Version bump guidance:

• patch: Backward-compatible bug fixes, internal changes, or minimal updates
• minor: Backward-compatible new features or enhancements
• major: Breaking changes requiring consumer updates

Special cases:

• Workspace root only (cannot be released): Skip changeset entirely
• Multi-package identical changes (e.g., same dependency bump): Group in one changeset

Directory and file naming

• Directory: .changeset/ (singular, not .changesets/)
• Naming convention: {package-name}_{short-description}.md
  • Prefix with package name (exclude @equinor/ scope)
  • Use kebab-case for multi-word descriptions
  • Keep total filename under 50 characters
  • Examples:
    • framework_add-invalidate-flag.md
    • react-module_http-client-fix.md
    • query_cache-improvements.md

Frontmatter format

Each file must start with YAML frontmatter listing affected packages and the bump type:

---
"@equinor/fusion-framework": patch
---

Short, clear summary of the change and its impact.

Multi-package changes are allowed. Prefer one package per changeset, unless the change and the message are identical across packages (e.g., bumping the same dependency version in several packages). In that case, group them in one changeset by listing all packages in the frontmatter.

Choosing the version type

• major: breaking API or behavior changes
• minor: new, backward-compatible functionality
• patch: backward-compatible bug fixes or internal-only changes

Writing effective summaries

Changeset summaries become the release notes that consumers read. Structure each summary to answer:

1. What changed - Brief description of the modification
2. Why it changed - Rationale and benefits
3. How to migrate (if applicable) - For breaking changes or major updates

Guidelines:

• Be specific and consumer-focused - write as if consumers will read this directly
• Keep under 3-4 lines for readability
• Include code examples only for complex new features
• Reference issues: Fixes https://github.com/equinor/fusion-framework/issues/123, Closes https://github.com/equinor/fusion-framework/issues/123
• Credit contributors: Thanks @username for the report

Migration notes for breaking changes:

• One-line migration instruction
• Include before/after code snippets if complex
• Link to migration guide if extensive

Best Practices

• Single package per changeset: Keep changes focused and releases manageable
• Scope narrowly: Multiple small changesets > one large changeset for better traceability
• Update during review: Modify changesets if PR scope changes
• Check existing files: Always scan .changeset/ on feature branches first
• Group identical changes: Only combine packages with identical changes/messages

Quality Assurance Checklist

Before committing a changeset:

• Correct directory (.changeset/) and naming convention followed
• Version bump type appropriate (patch/minor/major)
• Summary clear, concise, and consumer-focused
• Only affected packages listed in frontmatter
• Breaking changes include migration notes
• Internal changes clearly marked (or skipped entirely)
• Multi-package grouping justified (identical changes only)
• Related issues referenced and contributors credited

Examples

New feature (minor):

---
"@equinor/fusion-query": minor
---

Add optional `invalidate` argument to `Query.query` for pre-execution cache invalidation.

```typescript
// Before
await query('data');

// After
await query('data', { invalidate: true });
```

Fixes: https://github.com/equinor/fusion-framework/issues/123 — thanks @username for the suggestion

Bug fix (patch):

---
"@equinor/fusion-framework-react": patch
---

Fix useFramework hook memory leak when component unmounts during async operations.

Prevents stale closure access in cleanup functions.

Breaking change (major):

---
"@equinor/fusion-framework": major
---

Remove deprecated `createApp` function in favor of `initializeFramework`.

**Migration:** Replace `createApp(config)` with `initializeFramework(config)`.

Multi-package dependency bump:

---
"@equinor/fusion-framework": patch
"@equinor/fusion-framework-react": patch
"@equinor/fusion-framework-module-http": patch
---

Bump `axios` to 1.6.0 across packages to address security advisory; no public API changes.

Internal refactor (patch):

---
"@equinor/fusion-framework": patch
---

Internal: refactor module loading to simplify dependency graph; no public API changes.

Git context for changeset generation

Priority order for determining changes:

1. Staged changes - Analyze only staged files if present
2. Unstaged changes - Analyze unstaged files if no staged changes
3. Branch comparison - Compare against origin/${BRANCH} if remote tracking exists
4. Fallback - Compare against origin/main if no remote branch found

Useful commands:

# Check for staged changes
git diff --cached --name-only

# Check for unstaged changes
git diff --name-only

# Check current branch and remote tracking
git branch -vv

# Compare against remote branch
git diff --name-only origin/${BRANCH}...HEAD

CLI workflow

Use the guided changeset creation:

pnpm changeset

The Changesets bot validates on PRs and can help create changesets from the GitHub UI.

AI Agent Guidelines

When automating changeset creation:

• Analyze git state in priority order: staged → unstaged → branch diff
• Create changesets for ALL package changes (internal refactoring still needs versioning)
• Prefer single package per changeset unless changes are identical
• Use package name (without scope) as filename prefix
• Follow the decision tree: workspace root → skip, package changes → create
• Mark internal changes clearly with "Internal:" prefix in summary
• Include migration notes for breaking changes

Reviewer checklist

• Correct directory (.changeset/) and naming convention followed
• Appropriate version type (patch/minor/major) based on impact
• Summary clear, concise, and consumer-focused
• Only affected packages listed in frontmatter
• Breaking changes include migration notes
• Internal changes clearly marked with "Internal:" prefix
• Multi-package grouping justified (identical changes only)
• Related issues referenced and contributors credited

Common mistakes to avoid

• ❌ Using .changesets/ instead of .changeset/
• ❌ Grouping unrelated changes in one changeset
• ❌ Missing affected packages in frontmatter
• ❌ Vague summaries or incorrect version bump types
• ❌ Skipping changesets for package changes (even internal ones)
• ❌ Skipping changesets for consumer-impacting changes
• ❌ Grouping packages with different changes/messages
• ❌ Omitting migration notes for breaking changes
• ❌ Not checking existing changesets on feature branches
• ❌ Incorrect filename prefixes or overly long names