Skip to content

Commit a3fe54c

Browse files
Seungwoo321claude
Seungwoo321
and
claude
committed
docs: add comprehensive release strategy documentation
각 패키지의 독립적 배포 프로세스를 시각화한 릴리즈 전략 문서 추가 - Mermaid 다이어그램으로 전체 플로우 시각화 - Changesets 기반 독립적 패키지 버전 관리 - Beta/Production 릴리즈 프로세스 - Fault tolerance 및 보안 고려사항 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 13f3256 commit a3fe54c

File tree

1 file changed

+254
-0
lines changed

1 file changed

+254
-0
lines changed

‎RELEASE_STRATEGY.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# Release Strategy
2+
3+
## Overview
4+
5+
This document outlines the release strategy for the vue3-pivottable monorepo, which uses Changesets for version management and supports independent package releases.
6+
7+
## Architecture
8+
9+
```mermaid
10+
graph TB
11+
subgraph "Development Flow"
12+
A[Developer creates feature branch] --> B[Make changes]
13+
B --> C[Run 'pnpm changeset add']
14+
C --> D[Create PR to develop]
15+
D --> E[Code Review]
16+
E --> F[Merge to develop]
17+
end
18+
19+
subgraph "Pre-release Flow (Beta)"
20+
F --> G[Push to develop branch]
21+
G --> H[GitHub Actions triggered]
22+
H --> I[Build all packages]
23+
I --> J[Publish with beta tag]
24+
end
25+
26+
subgraph "Production Release Flow"
27+
F --> K[Create PR: develop → main]
28+
K --> L[Merge to main]
29+
L --> M[GitHub Actions triggered]
30+
M --> N[Create release/vX.X.X branch]
31+
N --> O[Run changeset version]
32+
O --> P[Build packages]
33+
P --> Q[Publish to npm]
34+
end
35+
```
36+
37+
## Package Structure
38+
39+
Our monorepo contains three independently versioned packages:
40+
41+
```mermaid
42+
graph TD
43+
A[vue3-pivottable monorepo] --> B[vue3-pivottable<br/>Main package]
44+
A --> C[@vue-pivottable/plotly-renderer<br/>Plotly visualization]
45+
A --> D[@vue-pivottable/lazy-table-renderer<br/>Virtual scrolling table]
46+
47+
B --> E[NPM_TOKEN]
48+
C --> F[NPM_TOKEN_SUMIN]
49+
D --> F
50+
```
51+
52+
## Release Process
53+
54+
### 1. Development Phase
55+
56+
```mermaid
57+
sequenceDiagram
58+
participant Dev as Developer
59+
participant CS as Changesets
60+
participant GH as GitHub
61+
62+
Dev->>Dev: Make code changes
63+
Dev->>CS: pnpm changeset add
64+
CS->>CS: Create .changeset/xxx.md
65+
Dev->>GH: Create Pull Request
66+
Note over GH: PR includes changeset file
67+
GH->>GH: Code Review
68+
GH->>Dev: Merge to develop
69+
```
70+
71+
### 2. Beta Release (Automated)
72+
73+
```mermaid
74+
sequenceDiagram
75+
participant GH as GitHub
76+
participant GA as GitHub Actions
77+
participant NPM as npm Registry
78+
79+
GH->>GA: Push to develop
80+
GA->>GA: Check for changesets
81+
GA->>GA: Build packages
82+
GA->>NPM: Publish vue3-pivottable@beta
83+
GA->>NPM: Publish @vue-pivottable/plotly-renderer@beta
84+
GA->>NPM: Publish @vue-pivottable/lazy-table-renderer@beta
85+
```
86+
87+
### 3. Production Release (Automated)
88+
89+
```mermaid
90+
sequenceDiagram
91+
participant Main as main branch
92+
participant GA as GitHub Actions
93+
participant Rel as release/vX.X.X
94+
participant NPM as npm Registry
95+
96+
Main->>GA: Push to main
97+
GA->>GA: Check changesets exist
98+
GA->>Rel: Create release branch
99+
GA->>GA: Run changeset version
100+
GA->>GA: Commit version bumps
101+
GA->>GA: Build all packages
102+
GA->>NPM: Publish each package
103+
GA->>Main: Merge back to main
104+
```
105+
106+
## Independent Package Releases
107+
108+
Each package can be released independently based on its changesets:
109+
110+
```mermaid
111+
graph LR
112+
subgraph "Changeset Detection"
113+
A[.changeset/xxx.md] --> B{Which package?}
114+
B -->|vue3-pivottable| C[Version main package]
115+
B -->|@vue-pivottable/plotly-renderer| D[Version plotly-renderer]
116+
B -->|@vue-pivottable/lazy-table-renderer| E[Version lazy-table-renderer]
117+
end
118+
119+
subgraph "Release Execution"
120+
C --> F[Build & Publish main]
121+
D --> G[Build & Publish plotly]
122+
E --> H[Build & Publish lazy-table]
123+
end
124+
```
125+
126+
## Version Management
127+
128+
### Changeset Configuration
129+
130+
```json
131+
{
132+
"linked": [], // No linked packages
133+
"fixed": [], // No fixed versioning
134+
"access": "public",
135+
"baseBranch": "main"
136+
}
137+
```
138+
139+
This configuration ensures:
140+
- Each package maintains its own version
141+
- Packages can be released independently
142+
- No forced version synchronization
143+
144+
### Version Bump Rules
145+
146+
| Change Type | Version Bump | Example |
147+
|------------|--------------|---------|
148+
| patch | 1.0.0 → 1.0.1 | Bug fixes |
149+
| minor | 1.0.0 → 1.1.0 | New features |
150+
| major | 1.0.0 → 2.0.0 | Breaking changes |
151+
152+
## Fault Tolerance
153+
154+
The release script (`scripts/release-packages.js`) implements fault tolerance:
155+
156+
```mermaid
157+
graph TD
158+
A[Start Release] --> B[Package 1: vue3-pivottable]
159+
B -->|Success| C[Package 2: plotly-renderer]
160+
B -->|Failure| C
161+
C -->|Success| D[Package 3: lazy-table-renderer]
162+
C -->|Failure| D
163+
D --> E[Generate Report]
164+
E --> F{All Success?}
165+
F -->|Yes| G[Exit 0]
166+
F -->|No| H[Exit 1]
167+
```
168+
169+
## Pre-release Workflow
170+
171+
Beta releases follow this naming convention:
172+
173+
```mermaid
174+
graph LR
175+
A[Current: 1.0.0] --> B[First beta: 1.0.1-beta.0]
176+
B --> C[Next beta: 1.0.1-beta.1]
177+
C --> D[Final release: 1.0.1]
178+
```
179+
180+
## GitHub Actions Workflows
181+
182+
### Release Workflow (`.github/workflows/release.yml`)
183+
- Triggered on: Push to `main`
184+
- Creates release branches
185+
- Publishes to npm with latest tag
186+
187+
### Pre-release Workflow (`.github/workflows/release-develop.yml`)
188+
- Triggered on: Push to `develop`
189+
- Publishes to npm with beta tag
190+
- No version commits to develop
191+
192+
## Security Considerations
193+
194+
### npm Tokens
195+
- `NPM_TOKEN`: Used for main package
196+
- `NPM_TOKEN_SUMIN`: Used for scoped packages
197+
- Tokens stored as GitHub Secrets
198+
199+
### Branch Protection
200+
- `main` branch: Protected with "Restrict pushes that create matching branches"
201+
- `release/*` branches: Exempt from restrictions
202+
- No GitHub App token required
203+
204+
## Rollback Strategy
205+
206+
In case of issues:
207+
208+
1. **Revert on npm**: Use `npm unpublish` within 72 hours
209+
2. **Git revert**: Create revert PR to main
210+
3. **Hotfix**: Create changeset with patch bump
211+
212+
## Best Practices
213+
214+
1. **Always create changesets** for changes that affect published packages
215+
2. **Use conventional commit messages** for clarity
216+
3. **Test thoroughly** before merging to main
217+
4. **Monitor** npm publish results in GitHub Actions
218+
219+
## Commands Reference
220+
221+
| Command | Description |
222+
|---------|-------------|
223+
| `pnpm changeset add` | Create a new changeset |
224+
| `pnpm changeset version` | Update versions based on changesets |
225+
| `pnpm changeset publish` | Publish packages to npm |
226+
| `pnpm build:all` | Build all packages |
227+
| `pnpm release:packages` | Run custom release script |
228+
229+
## Troubleshooting
230+
231+
### Common Issues
232+
233+
1. **Build failures**: Check package dependencies
234+
2. **Publish failures**: Verify npm tokens
235+
3. **Version conflicts**: Ensure changesets are properly configured
236+
237+
### Debug Commands
238+
239+
```bash
240+
# Check pending changesets
241+
ls .changeset/*.md | grep -v README.md
242+
243+
# Verify package versions
244+
pnpm list --depth=0
245+
246+
# Test build locally
247+
pnpm build:all
248+
```
249+
250+
## References
251+
252+
- [Changesets Documentation](https://github.com/changesets/changesets)
253+
- [npm Publishing Guide](https://docs.npmjs.com/cli/v8/commands/npm-publish)
254+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)

0 commit comments

Comments
 (0)