changeset

Changeset

bun changesetUsing the detected changed packages as candidates, confirm the bump for each package with the user, and after confirmation, .changeset/*.md writes the file.

SEED는 From 2.0, strict semveris followed (breaking changes only in major). The bump decision uses references/version-matrix.md's propagation matrix as the single criterion — the key is how a change in one package propagates to packages that depend on it.

Execution procedure

Phase 1: Detect changed packages (candidate list)

bun changeset Use the CLI to get the candidate list of changed (= release-target) packages. This CLI is interactive, so if you just run it, it waits for input and hangs, therefore run it in the background, then terminate it and capture only the output.

( bun changeset </dev/null >/tmp/changeset-detect.txt 2>&1 ) &
p=$!; sleep 4; kill "$p" 2>/dev/null; wait "$p" 2>/dev/null
# ANSI/커서 제어문자 제거 후 'changed packages' 섹션의 패키지명만 추출
perl -pe 's/\e\[[0-9;?]*[a-zA-Z]//g' /tmp/changeset-detect.txt \
  | sed -n '/changed packages/,/unchanged packages/p' \
  | grep -oE '@[a-z-]+/[a-z0-9-]+' | sort -u

1. The extracted changed packages를 candidate list. Inclusion and bump are confirmed per package in Phase 2.
   • bun changeset은 private packages are already excluded, so there is no need to filter them out separately.
   • packages/archive/*does not bump the version. Modifying the file is fine, but do not include it in the changeset. Since there are non-private ones, they appear in the CLI candidates, so they must be filtered out here. @seed-design/react-themingis in the archive, and the trap is that it looks active when you only see the name.
   • If the grep result looks empty or truncated, /tmp/changeset-detect.txtread directly and changed packages visually check the block (long lists may appear truncated to fit the terminal width).
2. Read the already existing .changeset/*.md file to check whether there is a package already covered.
   • If there is an already covered package, notify the user and check whether an additional changeset is needed.

[!NOTE] The CLI list is based on .changeset/config.json의 baseBranch(usually dev), so if the current branch is stackedon top of commits not merged into dev, packages from lower commits may be pulled in and inflated. Since the user can filter this out in Phase 2 with 안함(제외), it is fine to keep the candidates broad here.

Phase 2: Confirm bump per package (AskUserQuestion)

For the candidate's each package check the actual changes (git diff <패키지_경로> or commit log), references/version-matrix.mddetermine the recommended bump using the propagation matrix, then confirm the bump for each package with the user via AskUserQuestion.

1. Propagation candidate expansion: bumping one package also adds packages that depend on it to the candidates together according to "Step 2. Propagation" in the matrix. css consumers are not just react one, but 7개다 (react·stackflow·tailwind3-plugin·tailwind4-theme·vite-plugin·rsbuild-plugin·webpack-plugin) — which one applies is determined by the "actually used" decision table in the matrix. When headless goes up, react(consumed as a dependency), and when react is major, figma(major sorting). bun changesetDependents not caught by stacked etc. are also added directly here.
2. One question per package. Options are major / minor / patch / 안함(제외) 4개.
   • Place the recommended type analyzed by the model as the **first option and add to the label (추천)**. The basis for the judgment (which row of the matrix) is written in the option description.
   • 안함(제외)is the option to exclude that package from the changeset. Use it for unrelated packages dragged in by stacked or for packages that don't need a changeset.
3. AskUserQuestion allows up to 4 questions per call, so if there are 5 or more candidates, split them into groups of 4 and call it multiple times.
4. 안함Exclude packages answered with , and take the rest as the confirmed list.
   • Caution (2.0): Changes that break the public surface (renaming/deleting public prop/API, recipe, slot, variant, token, public data attr names, extending headless breaking, etc.) are **major**. Do not answer with minor as in 1.x.
   • Caution (visual changes): **Intentional color value changes or redesigns are also major**. Even if the name stays the same, the consumer's screen changes, and minor is automatically installed within the ^ range, so it is not protected. Conversely, fixing values that were wrong(insufficient contrast, spec mismatch) is patch. The only criterion is "Was it originally wrong / Was it right but being changed?"
   • Internal wiring (styling-only data-*, typographyexcluding vars/component/*) moving/deleting is non-public and thus not breaking (patch/minor). If the judgment is confusing, check with references/version-matrix.md.

Phase 3: Writing the message

1. references/patterns.mdand refer to the message patterns.
2. Based on the changes in the confirmed list, design system consumer (developer) Write a Korean message from the perspective.
   • Focus on changes visible to users, not internal refactoring.
   • Follow the structure per type (patch: 1 line + bullets, minor: title + description + code example, major: title + description + migration).
   • (BREAKING CHANGE: {마이그레이션 액션}) The prefix is only for major Attach it to the first line. Do not attach it to minor/patch.
   • Snippet changes are determined by "Will existing code break if not reinstalled?" — if it doesn't break, minor(no prefix), if it breaks, major. (references/patterns.md's "snippet change classification")
3. If there are multiple independent changes, it is recommended to separate them into separate changeset files. However, packages that rise together due to propagation (css+react, etc.) are grouped into one file.

Phase 4: Message confirmation

1. The bump was confirmed in Phase 2, so here message previewShow and confirm:

## Changeset 초안

### 포함 패키지 (Phase 2 확정)
| 패키지 | 변경 타입 |
|--------|----------|
| @seed-design/react | patch |

### 메시지 미리보기
(changeset 파일 전체 내용을 코드블록으로)

1. Ask the user to confirm/modify the message. If there is a modification request, apply it and show it again.

Phase 5: peer floor manual bump check

1. If the confirmed list includes **css or headless's minor**, check with the "actually used" determination table whether the peer/dep floor of dependents that newly consume it needs to be raised. references/version-matrix.mdFor a css minor, scan all 7 consumers — especially Adding new tokens tailwind3-plugin·tailwind4-themealways triggers (because token names are mapped directly).
   • .changeset/config.json의 onlyUpdatePeerDependentsWhenOutOfRangeis enabled, so if the floor is in the new version range 안the changeset does not automatically raise the dependent. If it isn't raised, the react@new + css@old combination is allowed, causing runtime silent failure.
   • If needed, in the dependent's package.jsondirectly modify the relevant floor to ^N.M.0and include it in the same PR (not a package installation but a version policy edit, so direct modification is justified). The ceiling (<N+1) is not touched.
   • major bumps are automatically propagated by the changeset, so this step to only applies to minor propagation .
2. If a floor fix is needed, tell the user which package.jsonwill be changed and how, then proceed.

Phase 6: File creation

1. Once the user approves, create the file with the Write tool in the .changeset/ directory.
2. For the filename, use a random three-word combination in English lowercase 형용사-명사-동사.md format.
   • Check that it does not conflict with existing .changeset/*.md filenames.

---

Cautions

• The changeset message is user-facing text that goes verbatim into the CHANGELOG. Describe user impact, not internal implementation details.
• The package name in the frontmatter must be wrapped in double quotes (").
• bump는 내 The public surfaceis determined by what changed. Do not raise it just because a dependency was raised (references/version-matrix.md's "the criterion is my public surface").
• .changeset/config.json의 linkedPackages tied to are automatically aligned to the same version at release, so the changeset only needs to include the packages that actually changed.

Reference files

• references/version-matrix.md — inter-package version propagation matrix + bump decision criteria (refer first)
• references/patterns.md — message writing pattern guide