|
4 | 4 |
|
5 | 5 | ## 목적 |
6 | 6 |
|
7 | | -모든 파괴적 변경에 대한 Changeset을 생성하고, v2.0.0 릴리스를 준비한다. |
| 7 | +모든 파괴적 변경에 대한 Changeset을 **패키지별로 분리해 생성**하고, 영향받는 하위 플러그인 패키지의 peer dependency 를 v2 범위로 업데이트하며, v2.0.0 릴리스를 준비한다. |
8 | 8 |
|
9 | 9 | ## 작업 |
10 | 10 |
|
11 | | -### 1. Changeset 생성 |
| 11 | +### 1. Changeset 파일 분리 |
12 | 12 |
|
13 | | -Major bump 대상 패키지: |
14 | | -- `@stackflow/react` — API 전면 변경 |
15 | | -- `@stackflow/link` — API 전면 변경 |
16 | | -- `@stackflow/core` — 메이저 버전 동기화 (변경 없지만 2.0 생태계 통일) |
17 | | -- `@stackflow/config` — 메이저 버전 동기화 |
| 13 | +#### 배경 |
18 | 14 |
|
19 | | -> **Note:** `@stackflow/compat-await-push`는 이번 마이그레이션에서 삭제하지 않으므로 deprecate 대상이 아니다. |
| 15 | +현재 PR 에는 `.changeset/nine-rabbits-jam.md` 한 파일에 `@stackflow/react`, `@stackflow/link`, `@stackflow/config`, `@stackflow/core` 4개 패키지가 **같은 frontmatter 에 묶여** 있다. |
20 | 16 |
|
21 | | -### 2. npm deprecate 대상 |
| 17 | +Changesets 툴은 frontmatter 에 나열된 모든 패키지에 **동일한 본문 전체**를 CHANGELOG 로 주입한다. 이대로 릴리스하면: |
| 18 | + |
| 19 | +- `@stackflow/core` CHANGELOG 에 `@stackflow/react` breaking changes 전체가 주입됨 (core 는 사실상 변경 없음) |
| 20 | +- `@stackflow/link` CHANGELOG 에도 `@stackflow/react` 내용이 그대로 복사됨 |
| 21 | +- 사용자가 각 패키지 CHANGELOG 만 보고 어떤 변경이 본인 패키지에 해당하는지 판단하기 어려움 |
| 22 | + |
| 23 | +#### 분리 방침 |
| 24 | + |
| 25 | +패키지별로 changeset 을 분리한다. 최소 3개 파일로 쪼개는 것을 권장: |
| 26 | + |
| 27 | +| Changeset 파일 | 대상 패키지 | 본문 | |
| 28 | +|---|---|---| |
| 29 | +| `.changeset/react-v2.md` | `@stackflow/react: major` | react 관련 BC 전체 (아래 § 4 참조) | |
| 30 | +| `.changeset/link-v2.md` | `@stackflow/link: major` | link 관련 BC 전체 | |
| 31 | +| `.changeset/core-config-v2.md` | `@stackflow/core: major`, `@stackflow/config: major` | "Major version bump for 2.0 ecosystem alignment. No API changes in this package." | |
| 32 | + |
| 33 | +> 필요 시 `@stackflow/config` 도 별도 파일로 분리해도 되며, core/config 가 함께 동일 내용을 공유하는 경우에만 묶는다. |
| 34 | +
|
| 35 | +#### 기존 파일 처리 |
| 36 | + |
| 37 | +- `.changeset/nine-rabbits-jam.md` 는 삭제 |
| 38 | +- 본문에서 `@stackflow/compat-await-push` 관련 "Removed packages" 문구는 전부 제거 (유지 결정 반영) |
| 39 | + |
| 40 | +### 2. 하위 플러그인 패키지 Changeset 및 peer dependency 업데이트 |
| 41 | + |
| 42 | +#### 누락된 changeset |
| 43 | + |
| 44 | +아래 패키지들은 이 마이그레이션 과정에서 `@stackflow/react` 의 import 를 실제로 변경(`useActions` → `useFlow`, `@stackflow/react/future` → `@stackflow/react` 등) 했음에도 changeset 에 포함되어 있지 않다. |
| 45 | + |
| 46 | +- `@stackflow/plugin-basic-ui` |
| 47 | +- `@stackflow/plugin-blocker` |
| 48 | +- `@stackflow/plugin-history-sync` |
| 49 | +- `@stackflow/plugin-lifecycle` |
| 50 | +- (추가 대상: `@stackflow/plugin-renderer-basic`, `@stackflow/plugin-renderer-web`, `@stackflow/plugin-devtools`, `@stackflow/plugin-sentry`, `@stackflow/plugin-stack-depth-change`, `@stackflow/plugin-google-analytics-4`, `@stackflow/react-ui-core` 등 — 실제 diff 확인 후 결정) |
| 51 | + |
| 52 | +각 패키지에 **최소 patch bump** changeset 을 추가하고, 본문에 "Updated for `@stackflow/react` v2 compatibility (import paths, hook migrations)." 같은 한 줄 요약을 남긴다. |
| 53 | + |
| 54 | +> Bump 규모 판단 기준: 외부 API 가 바뀌면 minor/major, 내부 구현만 바뀌면 patch. 대부분의 플러그인은 patch 로 충분하나, `plugin-history-sync` 처럼 사용자 API 가 config-first 로 바뀌었다면 major 또는 minor 를 고려한다. |
| 55 | +
|
| 56 | +#### peer dependency 범위 업데이트 |
| 57 | + |
| 58 | +위 플러그인 패키지들의 `peerDependencies` 가 대부분 `"@stackflow/react": "^1.x"` 로 선언되어 있다. `@stackflow/react` v2 가 릴리스되면 peer dep 이 불충족되어 사용자 프로젝트에서 설치 경고/에러가 발생한다. |
| 59 | + |
| 60 | +각 플러그인 `package.json` 의 `peerDependencies` 를 v2 범위로 업데이트: |
| 61 | + |
| 62 | +```jsonc |
| 63 | +// Before |
| 64 | +"peerDependencies": { |
| 65 | + "@stackflow/react": "^1.0.0" |
| 66 | +} |
| 67 | + |
| 68 | +// After — 하나의 major 만 지원하는 경우 |
| 69 | +"peerDependencies": { |
| 70 | + "@stackflow/react": "^2.0.0" |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +> `@stackflow/core`, `@stackflow/config` 에 대한 peer dep 도 동일하게 확인해 v2 범위로 올린다. |
| 75 | +
|
| 76 | +### 3. `@stackflow/compat-await-push` 관련 Changeset 본문 정리 |
| 77 | + |
| 78 | +- changeset 본문 "Removed packages" 섹션에서 `@stackflow/compat-await-push` 항목 제거 |
| 79 | +- `@stackflow/compat-await-push` 에 대한 changeset 도 **생성하지 않음** (deprecate 대상이 아니고 버전 bump 도 이번에는 하지 않음 — 추후 독립 트랙에서 처리) |
| 80 | + |
| 81 | +### 4. CHANGELOG 주요 항목 (패키지별) |
| 82 | + |
| 83 | +#### `@stackflow/react` — Major |
| 84 | + |
| 85 | +**Signature / Entry point** |
| 86 | +- **BREAKING:** `stackflow()` 입력 시그니처 변경 — `StackflowOptions<T extends BaseActivities>` → `StackflowInput<T, R>` (`{ activities, transitionDuration }` → `{ config, components }`) |
| 87 | +- **BREAKING:** `stackflow()` 출력 시그니처 변경 — `StackflowOutput<T>` → `StackflowOutput` (제네릭 파라미터 제거) |
| 88 | + - 제거된 반환 필드: `activities`, `useFlow`, `useStepFlow`, `addActivity`, `addPlugin` |
| 89 | + - 추가된 반환 필드: `stepActions` |
| 90 | + - 최종 구조: `{ Stack, actions, stepActions }` |
| 91 | +- **BREAKING:** `./stable`, `./future` 하위 경로 export 제거 — 기본 경로로 통합 |
| 92 | + |
| 93 | +**Hooks / Actions** |
| 94 | +- **BREAKING:** `useActions`, `useStepActions` 제거 → `useFlow`, `useStepFlow` 사용 (훅 import 경로는 `@stackflow/react`) |
| 95 | +- **BREAKING:** `useActiveEffect`, `useEnterDoneEffect`, `useStep` 훅 제거 |
| 96 | +- **BREAKING:** `stackflow().actions` 에서 `getStack()`, `dispatchEvent()` 제거 — 새 `Actions` 타입은 `push`, `replace`, `pop` 만 노출 |
| 97 | +- **BREAKING:** step actions 를 `stepActions` 객체로 분리 — 접근 경로가 `stackflow().actions.stepPush` → `stackflow().stepActions.pushStep` 등으로 변경 (이름 변경 + 구조 변경) |
| 98 | + |
| 99 | +**Type generics** |
| 100 | +- **BREAKING:** `useActivityParams` 제네릭 인터페이스 변경 — 기존 `useActivityParams<{ key: string | undefined }>()` (params 객체 타입 직접 전달) → 신규 `useActivityParams<"ActivityName">()` (activity 이름 문자열 리터럴 전달, `@stackflow/config` Register 에서 타입 추론) |
| 101 | +- **BREAKING:** `ActivityComponentType` 제네릭 인터페이스 변경 — 기존 `ActivityComponentType<{ title: string }>` → 신규 `ActivityComponentType<"ArticleActivity">`. 기존 params 객체 타입 기반 API 는 `ActivityComponentTypeByParams` 로 rename |
| 102 | + |
| 103 | +**New** |
| 104 | +- **NEW:** `useLoaderData`, `useConfig`, `usePrepare`, `lazy`, `structuredActivityComponent` 기본 제공 |
| 105 | + |
| 106 | +#### `@stackflow/link` — Major |
| 107 | + |
| 108 | +- **BREAKING:** `createLinkComponent` factory 제거 — `Link` 컴포넌트를 직접 import (`import { Link } from "@stackflow/link"`) |
| 109 | +- **BREAKING:** `./stable`, `./future` 하위 경로 export 제거 — 기본 경로로 통합 |
| 110 | +- **BREAKING:** `LinkProps.urlPatternOptions` prop 제거 — 기존 stable Link 에서 제공하던 prop 이 새 Link 에서 사라짐 (해당 옵션은 `config.historySync` 에서만 설정) |
| 111 | +- **BREAKING:** `Link` 가 `forwardRef` 를 사용하지 않음 — ref 타입이 `React.ForwardedRef<HTMLAnchorElement>` → `React.RefObject<HTMLAnchorElement>` 로 변경 |
| 112 | + |
| 113 | +#### `@stackflow/core`, `@stackflow/config` — Major |
| 114 | + |
| 115 | +- "Major version bump for 2.0 ecosystem alignment. No API changes in this package." |
| 116 | + |
| 117 | +#### 기타 플러그인 패키지 (patch/minor, 영향 범위별) |
| 118 | + |
| 119 | +- "Updated for `@stackflow/react` v2 compatibility (import paths, hook migrations)." |
| 120 | +- `plugin-history-sync` 는 사용자 API (`routes` → config-first) 변경이 있을 경우 minor/major 로 상향 고려 |
| 121 | + |
| 122 | +#### Removed packages |
| 123 | + |
| 124 | +- **REMOVED:** `@stackflow/plugin-preload` — `usePrepare()` hook 으로 대체 |
| 125 | +- **REMOVED:** `@stackflow/plugin-map-initial-activity` — `config.initialActivity` 로 대체 |
| 126 | + |
| 127 | +> **Note:** `@stackflow/compat-await-push` 는 이번 마이그레이션에서 삭제하지 않으므로 changeset / CHANGELOG / deprecate 대상이 아니다. |
| 128 | +
|
| 129 | +### 5. npm deprecate 대상 |
22 | 130 |
|
23 | 131 | 릴리스 후 실행: |
24 | 132 | ```bash |
25 | 133 | npm deprecate @stackflow/plugin-preload "Removed in Stackflow 2.0. Use usePrepare() from @stackflow/react instead." |
26 | 134 | npm deprecate @stackflow/plugin-map-initial-activity "Removed in Stackflow 2.0. Use config.initialActivity instead." |
27 | 135 | ``` |
28 | 136 |
|
29 | | -### 3. CHANGELOG 주요 항목 |
30 | | - |
31 | | -- **BREAKING:** `@stackflow/react` — `stackflow()` 시그니처 변경 (`{ activities }` → `{ config, components }`) |
32 | | -- **BREAKING:** `@stackflow/react` — `useActions`, `useStepActions` 제거 → `useFlow`, `useStepFlow` 사용 |
33 | | -- **BREAKING:** `@stackflow/react` — `./stable`, `./future` 하위 경로 제거 |
34 | | -- **BREAKING:** `@stackflow/link` — `createLinkComponent` 제거, `Link` 직접 import |
35 | | -- **BREAKING:** `@stackflow/link` — `./stable`, `./future` 하위 경로 제거 |
36 | | -- **REMOVED:** `@stackflow/plugin-preload` 패키지 삭제 |
37 | | -- **REMOVED:** `@stackflow/plugin-map-initial-activity` 패키지 삭제 |
38 | | -- **NEW:** `useLoaderData`, `useConfig`, `usePrepare`, `lazy`, `structuredActivityComponent` 기본 제공 |
39 | | - |
40 | 137 | ## 확인 사항 |
41 | 138 |
|
42 | 139 | - [ ] `yarn changeset` 정상 실행 |
43 | | -- [ ] 모든 breaking change가 changeset에 기록됨 |
| 140 | +- [ ] Changeset 파일이 패키지별로 분리되어 있음 (한 파일에 여러 패키지의 서로 다른 본문이 섞이지 않음) |
| 141 | +- [ ] `@stackflow/compat-await-push` 관련 Removed 문구가 어떤 changeset 에도 없음 |
| 142 | +- [ ] 하위 플러그인 패키지(`plugin-basic-ui`, `plugin-blocker`, `plugin-history-sync`, `plugin-lifecycle` 등) 의 changeset 과 peer dep 범위(`@stackflow/react ^2.0.0`) 가 모두 업데이트됨 |
| 143 | +- [ ] CHANGELOG 주요 항목에 아래 9건의 추가 BC 가 모두 기록됨 |
| 144 | + - react: (1) `useActiveEffect`/`useEnterDoneEffect`/`useStep` 제거, (2) `stackflow().activities` 제거, (3) `actions.getStack/dispatchEvent` 제거, (4) `stepActions` 분리 |
| 145 | + - link: (5) `urlPatternOptions` 제거, (6) `forwardRef` 미사용 (ref 타입 변경) |
| 146 | + - react types: (7) `useActivityParams` 제네릭 변경, (8) `ActivityComponentType` 제네릭 변경, (9) `stackflow()` 입출력 타입 변경 |
| 147 | +- [ ] 모든 breaking change 가 올바른 패키지의 changeset 에만 기록됨 (교차 오염 없음) |
44 | 148 | - [ ] `yarn release` dry-run 정상 |
0 commit comments