diff --git a/.tech-specs/tasks/01-delete-deprecated-packages.md b/.tech-specs/tasks/01-delete-deprecated-packages.md index 5f8c71762..95ef18a43 100644 --- a/.tech-specs/tasks/01-delete-deprecated-packages.md +++ b/.tech-specs/tasks/01-delete-deprecated-packages.md @@ -4,20 +4,13 @@ ## 목적 -Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체된 패키지 3개를 삭제한다. +Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체된 패키지 2개를 삭제한다. -## 삭제 대상 - -### 1. `@stackflow/compat-await-push` +> `@stackflow/compat-await-push`는 삭제 계획에서 제외됨 (ENvironmentSet 반대, PR #695) -- **경로:** `extensions/compat-await-push/` -- **이유:** Old API의 `await push()` 패턴 호환 레이어. Future API에서는 사용하지 않음 -- **작업:** - - `extensions/compat-await-push/` 디렉토리 전체 삭제 - - 루트 `package.json` 워크스페이스 설정에서 제거 (해당하는 경우) - - 다른 패키지의 dependency/peerDependency에서 참조 제거 +## 삭제 대상 -### 2. `@stackflow/plugin-preload` +### 1. `@stackflow/plugin-preload` - **경로:** `extensions/plugin-preload/` - **이유:** Future API의 `usePrepare()` 훅으로 대체 @@ -28,7 +21,7 @@ Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체 - 플러그인 문서 삭제: `docs/pages/api-references/plugins/plugin-preload.{en,ko}.mdx` - `docs/pages/api-references/plugins/_meta.{en,ko}.json`에서 항목 제거 -### 3. `@stackflow/plugin-map-initial-activity` +### 2. `@stackflow/plugin-map-initial-activity` - **경로:** `extensions/plugin-map-initial-activity/` - **이유:** Future API의 `config.initialActivity`로 대체 diff --git a/.tech-specs/tasks/06a-fix-docs-code-examples.md b/.tech-specs/tasks/06a-fix-docs-code-examples.md new file mode 100644 index 000000000..54ed601dd --- /dev/null +++ b/.tech-specs/tasks/06a-fix-docs-code-examples.md @@ -0,0 +1,187 @@ +# PR 6a: 문서 코드 예제 수정 + +> 선행 PR: PR 3, PR 4 (API 승격 완료 후) +> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129) + +## 목적 + +PR #695에서 ENvironmentSet이 지적한 문서 코드 예제 오류를 수정한다. (삭제/rename은 PR 6b로, structured-activity 문서 개선은 PR 6c로 분리.) + +## 작업 + +### 1. `stackflow()` 반환값에서 `useFlow` destructuring 제거 + +실제 `StackflowOutput` 타입 (`integrations/react/src/stackflow.tsx:46-50`): + +```ts +export type StackflowOutput = { + Stack: StackComponentType; + actions: Actions; + stepActions: StepActions; +}; +``` + +`useFlow`는 반환값에 포함되지 않으며, `@stackflow/react`에서 독립 훅으로 직접 import해야 한다. + +**수정 파일:** + +| 파일 | 라인 | +|------|------| +| `docs/pages/docs/get-started/installation.en.mdx` | L40, L70 | +| `docs/pages/docs/get-started/installation.ko.mdx` | L40, L71 | +| `docs/pages/docs/get-started/activity.en.mdx` | L81 | +| `docs/pages/docs/get-started/activity.ko.mdx` | L84 | +| `docs/pages/docs/advanced/history-sync.en.mdx` | L43 | +| `docs/pages/docs/advanced/history-sync.ko.mdx` | L43 | +| `docs/pages/docs/migration-v2.en.mdx` | L52 ("After") | +| `docs/pages/docs/migration-v2.ko.mdx` | L52 ("변경 후") | + +**수정 방향:** +```diff +- const { Stack, useFlow } = stackflow(...) ++ const { Stack } = stackflow(...) ++ import { useFlow } from "@stackflow/react"; +``` + +### 2. `ActivityComponentType` v1 → v2 타입 패턴 변경 + +v2 `ActivityComponentType`은 params 객체 타입 대신 activity 이름 string literal을 받는다. 기존 params 객체 방식은 `ActivityComponentTypeByParams`로 rename. + +**수정 파일:** +- `docs/pages/docs/get-started/navigating-activities.en.mdx` L141-145 +- `docs/pages/docs/get-started/navigating-activities.ko.mdx` L143-147 + +**수정 방향:** +```diff +- type ArticleParams = { title: string; }; +- const Article: ActivityComponentType = ({ params }) => { ++ declare module "@stackflow/config" { ++ interface Register { ++ Article: { title: string }; ++ } ++ } ++ const Article: ActivityComponentType<"Article"> = ({ params }) => { +``` + +### 3. `ActivityLoaderArgs` import 경로 오류 + +`ActivityLoaderArgs`는 `@stackflow/config`에서만 export된다 (`config/src/index.ts:4`). `@stackflow/react`에서는 내부 사용만 하며 re-export하지 않는다. + +**수정 파일:** + +| 파일 | 라인 | +|------|------| +| `docs/pages/docs/advanced/loader-api.en.mdx` | L6 | +| `docs/pages/docs/advanced/loader-api.ko.mdx` | L6 | +| `docs/pages/docs/advanced/preloading.en.mdx` | L12 | +| `docs/pages/docs/advanced/preloading.ko.mdx` | L12 | + +> `loader-api.{en,ko}.mdx`는 PR 6b에서 삭제 예정. PR 6b와 머지 시점 조율 필요. + +**수정 방향:** +```diff +- import { ActivityLoaderArgs, useLoaderData } from "@stackflow/react"; ++ import type { ActivityLoaderArgs } from "@stackflow/config"; ++ import { useLoaderData } from "@stackflow/react"; +``` + +### 4. `@stackflow/link` API 레퍼런스 수정 + +#### 4-a. `animate` 기본값 설명 오류 + +현재 문서 (`link.en.mdx:45`, `link.ko.mdx:45`): +> "If not provided, it defaults to no animation." + +실제 동작 (`extensions/link/src/Link.tsx:89-99`): `animate`를 생략하면 빈 옵션 `{}`가 전달되어 push/replace의 기본 동작(**애니메이션 ON**)이 적용된다. 설명을 "기본 애니메이션 적용"으로 수정. + +#### 4-b. 존재하지 않는 `urlPatternOptions` prop 제거 + +실제 `LinkProps` (`Link.tsx:24-31`): +```ts +export interface LinkProps extends AnchorProps { + ref?: React.RefObject; + activityName: K; + activityParams: InferActivityParams; + animate?: boolean; + replace?: boolean; +} +``` + +`urlPatternOptions`는 `config.historySync`에서 내부적으로 사용될 뿐 사용자 prop이 아니다. + +**수정 파일:** +- `docs/pages/api-references/plugins/link.en.mdx` L47 — prop 문서 제거 +- `docs/pages/api-references/plugins/link.ko.mdx` L47 — prop 문서 제거 + +#### 4-c. Link ref 타입 오류 + +문서에는 `React.ForwardedRef`로 기재되어 있으나 실제는 `React.RefObject`. + +**수정 파일:** +- `docs/pages/api-references/plugins/link.en.mdx` L48 +- `docs/pages/api-references/plugins/link.ko.mdx` L48 + +### 5. `plugin-history-sync` 문서 v2 업데이트 + +현재 v1 API 패턴을 그대로 사용 중: +- `const { Stack, useFlow } = stackflow({ activities: { ... } })` +- `routes` 옵션 (v2에서는 config에 선언) + +v2 config-first 패턴으로 전면 업데이트. + +**수정 파일:** +- `docs/pages/api-references/plugins/plugin-history-sync.en.mdx` +- `docs/pages/api-references/plugins/plugin-history-sync.ko.mdx` + +### 6. `migration-v2` 문서 개선 + +#### 6-a. 5단계 "Before" 예시 확장 + +현재: +```ts +import { useFlow } from "./stackflow"; +``` + +`./stackflow`라는 파일 경로가 묵시적이어서 이해가 어렵다. `stackflow()` 팩토리에서 `useFlow`를 destructuring하여 export하는 **전체 맥락**을 보여주도록 확장. + +#### 6-b. API 대응표에서 `./stackflow` → `stackflow()` 팩토리 표현으로 변경 + +현재: +``` +| `useFlow()` from `./stackflow` | `useFlow()` from `@stackflow/react` | +``` + +파일 경로 대신 `stackflow()` 팩토리라는 표현으로 수정. + +**수정 파일:** +- `docs/pages/docs/migration-v2.en.mdx` +- `docs/pages/docs/migration-v2.ko.mdx` + +### 7. `write-plugin` 문서 수정 + +#### 7-a. 오타 + +`write-plugin.ko.mdx:262`: `G현재 스택의 상태를 가져올 수 있어요` → `현재 스택의 상태를 가져올 수 있어요` + +#### 7-b. 존재하지 않는 lifecycle hook 이름 수정 + +`initialPushedEvent`는 존재하지 않는 훅. 올바른 이름은 `overrideInitialEvents`. + +**수정 파일:** +- `docs/pages/docs/advanced/write-plugin.en.mdx` L261, L272 +- `docs/pages/docs/advanced/write-plugin.ko.mdx` L269, L280 + +## 확인 사항 + +- [ ] 수정된 모든 파일에서 `useFlow`가 `@stackflow/react`에서 직접 import +- [ ] `stackflow()` destructuring에 `useFlow` 미포함 +- [ ] `ActivityComponentType` → `ActivityComponentType<"ActivityName">` +- [ ] `ActivityLoaderArgs` import 경로가 `@stackflow/config`로 수정 +- [ ] `animate` 기본값 설명 정정 +- [ ] `urlPatternOptions` prop 문서 제거 +- [ ] Link ref 타입 `React.RefObject`로 수정 +- [ ] `plugin-history-sync` 문서 v2 패턴 +- [ ] `migration-v2` Before 예시/대응표 수정 +- [ ] `write-plugin` 오타/lifecycle hook 이름 수정 +- [ ] EN/KO 양쪽 동기화 +- [ ] 문서 사이트 로컬 빌드 정상 diff --git a/.tech-specs/tasks/06b-restructure-docs.md b/.tech-specs/tasks/06b-restructure-docs.md new file mode 100644 index 000000000..54cfe6f6d --- /dev/null +++ b/.tech-specs/tasks/06b-restructure-docs.md @@ -0,0 +1,60 @@ +# PR 6b: 문서 구조 변경 (삭제/rename/네비게이션) + +> 선행 PR: PR 3, PR 4 +> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129 추가 리뷰) + +## 목적 + +ENvironmentSet이 지적한 중복/불필요 문서를 정리하고, 네비게이션 라벨을 수정한다. + +## 작업 + +### 1. `resolving-circular-reference` 문서 삭제 + +v2에서는 `useFlow`를 `@stackflow/react`에서 직접 import하므로 순환참조 문제가 발생하지 않는다. 또한 문서에서 참조하는 `useActions`는 v2에 존재하지 않는 API이다. + +**삭제:** +- `docs/pages/docs/advanced/resolving-circular-reference.en.mdx` +- `docs/pages/docs/advanced/resolving-circular-reference.ko.mdx` + +**반영:** +- `docs/pages/docs/advanced/_meta.en.json`에서 항목 제거 +- `docs/pages/docs/advanced/_meta.ko.json`에서 항목 제거 + +### 2. `loader-api` 문서 삭제 + `preloading`을 "Loader API"로 rename + +`loader-api`와 `preloading` 문서 내용이 중복된다. `loader-api` 삭제 후 `preloading`의 제목을 "Loader API"로 변경한다. + +**삭제:** +- `docs/pages/docs/advanced/loader-api.en.mdx` +- `docs/pages/docs/advanced/loader-api.ko.mdx` + +**변경:** +- `docs/pages/docs/advanced/preloading.en.mdx` — 제목 → "Loader API" +- `docs/pages/docs/advanced/preloading.ko.mdx` — 제목 → "Loader API" + +**반영:** +- `docs/pages/docs/advanced/_meta.en.json` — `loader-api` 제거, `preloading` 라벨 → "Loader API" +- `docs/pages/docs/advanced/_meta.ko.json` — 동일 + +> 파일명(`preloading.mdx`)까지 변경할지, 라우팅 리다이렉트가 필요한지는 PR에서 별도 결정. + +### 3. `@stackflow/config` 네비게이션 이름 변경 (ko) + +**수정 파일:** +- `docs/pages/api-references/_meta.ko.json` + +**변경:** +```diff +- "@stackflow/config": "@stackflow/config" ++ "@stackflow/config": "설정" +``` + +## 확인 사항 + +- [ ] `resolving-circular-reference` 파일 2개 삭제 + meta 반영 +- [ ] `loader-api` 파일 2개 삭제 + meta 반영 +- [ ] `preloading` 제목 "Loader API"로 변경 (meta에도 반영) +- [ ] `@stackflow/config` 한국어 라벨 "설정" +- [ ] 삭제된 문서를 링크하는 다른 문서 없는지 확인 (있으면 링크 수정) +- [ ] 문서 사이트 로컬 빌드 정상 (404 없음) diff --git a/.tech-specs/tasks/06c-structured-activity-docs.md b/.tech-specs/tasks/06c-structured-activity-docs.md new file mode 100644 index 000000000..88c091bc4 --- /dev/null +++ b/.tech-specs/tasks/06c-structured-activity-docs.md @@ -0,0 +1,39 @@ +# PR 6c: structured-activity 문서 개선 + +> 선행 PR: PR 3 +> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129 추가 리뷰) + +## 목적 + +`structured-activity` 관련 문서의 예시와 line highlighting을 소스 실제 구조에 맞게 개선한다. + +## 작업 + +### 1. `content` 예시 단순화 + +`content` 컴포넌트가 `useActivityParams`를 쓰는 대신 매개변수로 `params`를 직접 받도록 예시 변경. (복잡한 훅 사용보다 props 패턴이 이해에 용이) + +### 2. API 섹션 제거 + +추후 전체 API를 다루는 별도 페이지가 만들어질 예정. 현재 문서의 API 섹션은 제거. + +### 3. Line highlighting 수정 (한/영 모두) + +현재 하이라이트 라인이 의미 없는 위치(빈 줄, 닫는 괄호)를 가리키고 있음. 실제 의미 있는 줄을 가리키도록 수정. + +| 섹션 | 현재 | 수정 | 이유 | +|------|------|------|------| +| Loading State (`Article.tsx`) | `{3,7}` | `{2,6}` | import와 `loading:` 줄 | +| Layout (`Article.tsx`) | `{3,4,8,9}` | `{2,7}` | import와 `layout:` 줄 | +| With Loader API (`stackflow.config.ts`) | `{8}` | `{2,9}` | `import articleLoader`와 `loader:` 줄 | + +**수정 파일:** +- `docs/pages/docs/advanced/structured-activity.en.mdx` +- `docs/pages/docs/advanced/structured-activity.ko.mdx` + +## 확인 사항 + +- [ ] `content` 예시가 매개변수로 `params`를 받는 패턴으로 단순화 +- [ ] API 섹션 제거 +- [ ] 3개 섹션의 line highlighting이 실제 의미 있는 줄을 가리킴 +- [ ] EN/KO 양쪽 동기화 diff --git a/.tech-specs/tasks/07a-fix-changesets.md b/.tech-specs/tasks/07a-fix-changesets.md new file mode 100644 index 000000000..3944d1139 --- /dev/null +++ b/.tech-specs/tasks/07a-fix-changesets.md @@ -0,0 +1,89 @@ +# PR 7a: Changeset 수정 및 누락 Breaking Changes 추가 + +> 선행 PR: PR 1~6 완료 후 +> PR #695 ENvironmentSet 리뷰 반영 (FEP-2130) + +## 목적 + +PR #695에서 ENvironmentSet이 지적한 changeset 오류를 수정하고, 기록되지 않은 breaking changes를 추가한다. + +## 작업 + +### 1. Changeset 파일 분리 + +현재 `nine-rabbits-jam.md` 하나에 4개 패키지가 묶여 있어, 동일한 본문이 모든 패키지 CHANGELOG에 들어간다. + +**분리 방안:** + +``` +.changeset/ + react-v2-breaking.md # @stackflow/react: major + link-v2-breaking.md # @stackflow/link: major + ecosystem-major-bump.md # @stackflow/config: major, @stackflow/core: major + # 본문: "Major version bump for ecosystem alignment" +``` + +### 2. 하위 플러그인 패키지 changeset 추가 + peer dep 업데이트 + +PR에서 import 변경이 있었으나 changeset이 누락된 패키지: + +| 패키지 | 변경 내용 | bump | +|--------|----------|------| +| `plugin-basic-ui` | `@stackflow/react/future` → `@stackflow/react` import 변경 | patch | +| `plugin-blocker` | 동일 | patch | +| `plugin-history-sync` | `useActions` → `useFlow` 변경 | patch | +| `plugin-lifecycle` | 동일 | patch | + +위 패키지들의 `package.json` peer dependency 업데이트: + +```diff +- "@stackflow/react": "^1.x" ++ "@stackflow/react": "^2.0.0" +``` + +### 3. `@stackflow/link` bump를 patch로 변경 + +> 인라인 코멘트: `extensions/link/package.json:48` +> "major bump가 아니라 patch bump 해야겠어요. history-sync-plugin이 stackflow 2.0 대응하기 위해서 peer deps 업데이트한 게 patch라서요." + +현재 major bump로 기록되어 있으나, `@stackflow/link`의 변경이 v2 대응 peer deps 업데이트 수준이라면 **patch**가 맞음. `link-v2-breaking.md` changeset bump 레벨을 major → patch로 조정. + +> 단, 실제 link 패키지의 변경 범위(API 제거/rename 포함 여부)를 다시 확인 후 결정. Breaking API 변경이 실제로 포함되어 있다면 ENvironmentSet과 재협의 필요. + +### 4. `@stackflow/compat-await-push` 삭제 항목 제거 + +ENvironmentSet 반대로 삭제 계획에서 제외 (별도 PR로 복구, `08-restore-compat-await-push.md` 참조). +changeset 본문의 "Removed packages" 섹션에서 `@stackflow/compat-await-push` 항목 제거. + +### 5. 누락된 Breaking Changes 추가 + +#### `@stackflow/react` + +| # | 항목 | 변경 내용 | +|---|------|----------| +| 1 | 훅 제거 | `useActiveEffect`, `useEnterDoneEffect`, `useStep` 기존 stable export에서 제거 | +| 2 | `stackflow()` 반환값 | `activities` 필드 제거 | +| 3 | `stackflow().actions` 축소 | `getStack()`, `dispatchEvent()` 제거 — 새 `Actions` 타입은 `push`, `replace`, `pop`만 노출 | +| 4 | step actions 구조 변경 | `stackflow().actions.stepPush` → `stackflow().stepActions.pushStep` (이름 변경만 언급되어 있고 접근 경로 변경은 미기록) | +| 5 | `useActivityParams` 제네릭 | `useActivityParams<{ key: string }>()` → `useActivityParams<"ActivityName">()` | +| 6 | `ActivityComponentType` 제네릭 | `ActivityComponentType` → `ActivityComponentType<"ActivityName">`. 기존 방식은 `ActivityComponentTypeByParams`로 rename | +| 7 | `stackflow()` 입력 타입 | `StackflowOptions` (`{ activities, transitionDuration }`) → `StackflowInput` (`{ config, components }`) | +| 8 | `stackflow()` 출력 타입 | `StackflowOutput` → `StackflowOutput` — 제네릭 제거, `activities`/`useFlow`/`useStepFlow`/`addActivity`/`addPlugin` 필드 제거, `stepActions` 필드 추가 | + +#### `@stackflow/link` + +| # | 항목 | 변경 내용 | +|---|------|----------| +| 9 | `LinkProps.urlPatternOptions` prop 제거 | +| 10 | `forwardRef` 미사용 | ref 타입: `React.ForwardedRef` → `React.RefObject` | + +## 확인 사항 + +- [ ] changeset 파일이 패키지별로 분리됨 +- [ ] 각 changeset 본문이 해당 패키지 관련 내용만 포함 +- [ ] 플러그인 패키지 4개의 changeset 추가됨 +- [ ] 플러그인 패키지 4개의 peer dep 범위 업데이트됨 +- [ ] `@stackflow/link` bump 레벨 재검토 (major vs patch) +- [ ] `@stackflow/compat-await-push` "Removed" 항목 제거 +- [ ] 누락된 breaking changes 10건이 `@stackflow/react`/`@stackflow/link` changeset에 기록 +- [ ] `yarn changeset` dry-run 정상 diff --git a/.tech-specs/tasks/08-restore-compat-await-push.md b/.tech-specs/tasks/08-restore-compat-await-push.md new file mode 100644 index 000000000..3dae43303 --- /dev/null +++ b/.tech-specs/tasks/08-restore-compat-await-push.md @@ -0,0 +1,65 @@ +# PR 8: `@stackflow/compat-await-push` 복구 + +> 선행 PR: 없음 (가능한 한 빨리 진행) +> PR #695 ENvironmentSet 리뷰 반영 (FEP-2125) + +## 목적 + +ENvironmentSet의 반대로 `@stackflow/compat-await-push` 삭제 계획을 철회하고, v2 릴리스에서도 해당 패키지를 유지한다. + +## 배경 + +ENvironmentSet의 반대 사유: + +1. **대체 API 부재** — `receive(push(...))` 패턴(다른 Activity에서 데이터를 돌려받는 패턴)을 대체하는 API가 v2에 없음 +2. **v2 호환성 문제 없음** — Stackflow 내부 API를 import하지 않는 순수 유틸리티(`resolveMap` 기반 Promise 패턴)이므로 v1/v2 독립적으로 동작 +3. **활발한 사용** — 조직 내 9개 활성 프로젝트가 의존 중 + +## 작업 + +### 1. 디렉토리 복구 + +`extensions/compat-await-push/`가 이미 삭제된 경우 git history에서 복구: + +```bash +# 삭제된 커밋 이전 버전에서 복구 +git checkout -- extensions/compat-await-push/ +``` + +복구 후 확인: +- `package.json` — v2 워크스페이스 설정과 일관된 버전 +- peer dependency 범위가 v2와 호환되는지 확인 (필요 시 `^2.0.0` 허용) + +### 2. 워크스페이스 등록 확인 + +- 루트 `package.json` workspaces에 `extensions/compat-await-push` 포함 +- `yarn install` 후 빌드 가능 여부 확인 + +### 3. `extensions/link/README.md` 업데이트 (관련 작업) + +> ENvironmentSet 지적: `extensions/link/README.md` L7, L9-10, L20에서 삭제된 `@stackflow/plugin-preload`를 여전히 의존성으로 안내 중. + +- `@stackflow/plugin-preload` 관련 설명 제거 +- v2 사용법(=`usePrepare()` 등)으로 업데이트 + +### 4. 관련 PR 수정 + +- `01-delete-deprecated-packages.md`에서 `compat-await-push` 제외 (이미 반영됨) +- `07a-fix-changesets.md`에서 "Removed packages" 항목 제거 (이미 반영됨) +- 기존 PR #695의 "npm deprecate" 섹션에서 `@stackflow/compat-await-push` 제거 + +### 5. v2 호환성 검증 + +- `@stackflow/compat-await-push`가 v2 `@stackflow/react`/`@stackflow/core`와 함께 작동하는지 확인 +- peer dependency 업데이트만으로 v2 호환이 되는지, 소스 수정이 필요한지 판단 +- 필요 시 patch/minor bump로 changeset 추가 + +## 확인 사항 + +- [ ] `extensions/compat-await-push/` 디렉토리 복구됨 +- [ ] `yarn install` + `yarn build` 정상 통과 +- [ ] `yarn typecheck` 통과 +- [ ] v2 패키지와 함께 사용 시 런타임 정상 동작 확인 +- [ ] `extensions/link/README.md`에서 `plugin-preload` 의존성 안내 제거됨 +- [ ] `01-delete-deprecated-packages.md`, `07a-fix-changesets.md`, PR #695 본문에서 일관되게 반영됨 +- [ ] 필요 시 v2 peer dep 업데이트 changeset 추가 diff --git a/.tech-specs/tasks/09-v1-docs-archiving.md b/.tech-specs/tasks/09-v1-docs-archiving.md new file mode 100644 index 000000000..6f5aa4761 --- /dev/null +++ b/.tech-specs/tasks/09-v1-docs-archiving.md @@ -0,0 +1,38 @@ +# PR 9 (제안): v1 문서 아카이빙 / 버전 셀렉터 + +> 선행 PR: PR 6a~6c (문서 업데이트 완료 후) +> PR #695 ENvironmentSet 제안 (신규 이슈) +> **우선순위: 선택적** — v2 릴리스 이후 별도 논의 후 진행 가능 + +## 목적 + +v1 → v2 마이그레이션으로 기존 문서가 삭제/교체되고 있어, v1을 사용 중인 사용자가 과거 API 문서를 참조할 방법이 없다. +[React Router](https://reactrouter.com/home)처럼 버전별 문서를 열람할 수 있는 구조를 지원해 마이그레이션 부담을 줄인다. + +## 옵션 + +### 옵션 A. 버전 셀렉터 (권장) + +문서 사이트 상단에 v1/v2 셀렉터 추가. Next.js 라우팅 + Nextra 구조에서 버전별 페이지 트리 분리. + +### 옵션 B. 경로 아카이빙 + +v1 문서를 `/v1/...` 경로에 그대로 보존. v2는 기존 경로(`/docs/...`)에 유지. + +### 옵션 C. 별도 브랜치 배포 + +`v1-docs` 브랜치에서 v1 문서 사이트 별도 배포 (예: v1.stackflow.so). Cloudflare 배포 라우팅 조정 필요. + +## 작업 (옵션 확정 후 세부화) + +- [ ] 옵션 선택 및 범위 확정 +- [ ] Nextra 버전 라우팅 설계 +- [ ] v1 문서 스냅샷 보존 (v1 릴리스 시점 기준) +- [ ] 네비게이션 UI에 버전 셀렉터 추가 +- [ ] 구버전 안내 배너 추가 (v1 페이지 상단) + +## 확인 사항 + +- [ ] v1/v2 양쪽 문서가 동시에 접근 가능 +- [ ] 검색/SEO가 버전별로 분리됨 +- [ ] 기존 외부 링크(v1 경로)가 깨지지 않음 (리다이렉트 또는 경로 유지)