feat: 添加现代化版本管理和自动发布系统
This commit is contained in:
sean
243
docs/BRANCHING.md
Normal file
243
docs/BRANCHING.md
Normal file
@ -0,0 +1,243 @@
|
||||
# PromptX 分支管理策略
|
||||
|
||||
## 分支模型
|
||||
|
||||
PromptX采用**简化版Git Flow**分支策略，包含三种类型分支：
|
||||
|
||||
```
|
||||
main ──●──●──●──●──●──● (正式版本: v0.1.0, v0.2.0)
|
||||
↑ ↑ ↑
|
||||
develop ──●──●──●──●──●──●──● (snapshot: 0.1.0-snapshot.1)
|
||||
↑ ↑ ↑ ↑ ↑
|
||||
feature/xxx ●──●──●
|
||||
feature/yyy ●──●──●
|
||||
```
|
||||
|
||||
## 分支说明
|
||||
|
||||
### 🚀 main分支
|
||||
- **用途**: 生产就绪的稳定代码
|
||||
- **保护**: 只能通过PR合并，需要代码审查
|
||||
- **发布**: 自动发布正式版本到npm
|
||||
- **版本**: `v0.1.0`, `v0.2.0`, `v1.0.0`
|
||||
|
||||
### 🔄 develop分支
|
||||
- **用途**: 日常开发集成分支
|
||||
- **保护**: 可直接推送，但建议通过PR
|
||||
- **发布**: 自动发布snapshot版本到npm
|
||||
- **版本**: `0.1.0-snapshot.1`, `0.1.0-snapshot.2`
|
||||
|
||||
### 🌟 feature分支
|
||||
- **用途**: 功能开发和Bug修复
|
||||
- **命名**: `feature/功能名` 或 `fix/bug名`
|
||||
- **合并**: 合并到develop分支
|
||||
- **生命周期**: 功能完成后删除
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 1. 功能开发
|
||||
|
||||
```bash
|
||||
# 从develop创建功能分支
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b feature/new-awesome-feature
|
||||
|
||||
# 开发功能
|
||||
# ... 编码 ...
|
||||
|
||||
# 提交代码
|
||||
git add .
|
||||
git commit -m "feat: add awesome feature"
|
||||
|
||||
# 推送分支
|
||||
git push origin feature/new-awesome-feature
|
||||
```
|
||||
|
||||
### 2. 创建PR到develop
|
||||
|
||||
- 在GitHub上创建PR: `feature/new-awesome-feature` → `develop`
|
||||
- 填写PR模板，添加changeset
|
||||
- 等待代码审查和CI通过
|
||||
- 合并后自动发布snapshot版本
|
||||
|
||||
### 3. 发布正式版本
|
||||
|
||||
```bash
|
||||
# 从develop创建PR到main
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 在GitHub上创建PR: develop → main
|
||||
# 合并后自动发布正式版本
|
||||
```
|
||||
|
||||
## 版本发布策略
|
||||
|
||||
### Snapshot版本（develop分支）
|
||||
|
||||
- **触发条件**: 推送到develop分支
|
||||
- **版本格式**: `0.1.0-snapshot.1`
|
||||
- **npm标签**: `@snapshot`
|
||||
- **用途**: 测试和验证新功能
|
||||
|
||||
```bash
|
||||
# 安装snapshot版本
|
||||
npm install -g dpml-prompt@snapshot
|
||||
```
|
||||
|
||||
### 正式版本（main分支）
|
||||
|
||||
- **触发条件**: 推送到main分支
|
||||
- **版本格式**: `0.1.0`, `0.2.0`, `1.0.0`
|
||||
- **npm标签**: `@latest`
|
||||
- **用途**: 生产环境使用
|
||||
|
||||
```bash
|
||||
# 安装正式版本
|
||||
npm install -g dpml-prompt@latest
|
||||
```
|
||||
|
||||
## 分支保护规则
|
||||
|
||||
### main分支
|
||||
- ✅ 需要PR审查
|
||||
- ✅ 需要CI通过
|
||||
- ✅ 需要最新代码
|
||||
- ❌ 禁止直接推送
|
||||
- ❌ 禁止强制推送
|
||||
|
||||
### develop分支
|
||||
- ✅ 需要CI通过
|
||||
- ⚠️ 建议通过PR（可直接推送）
|
||||
- ❌ 禁止强制推送
|
||||
|
||||
## Changeset管理
|
||||
|
||||
### 添加Changeset
|
||||
|
||||
```bash
|
||||
# 功能开发时添加changeset
|
||||
pnpm changeset
|
||||
|
||||
# 选择变更类型
|
||||
# - patch: Bug修复
|
||||
# - minor: 新功能
|
||||
# - major: 破坏性变更
|
||||
```
|
||||
|
||||
### Changeset类型对应
|
||||
|
||||
| 变更类型 | Changeset | 版本影响 | 示例 |
|
||||
|---------|-----------|----------|------|
|
||||
| 🐛 Bug修复 | patch | 0.1.0 → 0.1.1 | 修复CLI参数解析错误 |
|
||||
| ✨ 新功能 | minor | 0.1.0 → 0.2.0 | 添加新的remember命令 |
|
||||
| 💥 破坏性变更 | major | 0.1.0 → 1.0.0 | 改变CLI命令结构 |
|
||||
|
||||
## 实际操作示例
|
||||
|
||||
### 开发新功能
|
||||
|
||||
```bash
|
||||
# 1. 创建功能分支
|
||||
git checkout develop
|
||||
git checkout -b feature/memory-search
|
||||
|
||||
# 2. 开发功能
|
||||
# ... 编码 ...
|
||||
|
||||
# 3. 添加changeset
|
||||
pnpm changeset
|
||||
# 选择: minor
|
||||
# 描述: "添加记忆搜索功能"
|
||||
|
||||
# 4. 提交并推送
|
||||
git add .
|
||||
git commit -m "feat: add memory search functionality"
|
||||
git push origin feature/memory-search
|
||||
|
||||
# 5. 创建PR到develop
|
||||
# 合并后自动发布snapshot版本
|
||||
```
|
||||
|
||||
### 发布正式版本
|
||||
|
||||
```bash
|
||||
# 1. 确保develop分支稳定
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 2. 运行完整测试
|
||||
pnpm test:ci
|
||||
|
||||
# 3. 创建PR: develop → main
|
||||
# 在GitHub UI中操作
|
||||
|
||||
# 4. 合并PR后自动发布正式版本
|
||||
```
|
||||
|
||||
## 紧急修复流程
|
||||
|
||||
对于需要紧急修复的bug：
|
||||
|
||||
```bash
|
||||
# 1. 从main创建hotfix分支
|
||||
git checkout main
|
||||
git checkout -b hotfix/critical-bug
|
||||
|
||||
# 2. 修复bug
|
||||
# ... 编码 ...
|
||||
|
||||
# 3. 添加changeset
|
||||
pnpm changeset
|
||||
# 选择: patch
|
||||
|
||||
# 4. 同时合并到main和develop
|
||||
# 创建PR到main: hotfix → main
|
||||
# 创建PR到develop: hotfix → develop
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### ✅ 推荐做法
|
||||
- 功能开发从develop分支创建
|
||||
- 每个功能分支专注单一功能
|
||||
- 提交前运行测试和lint
|
||||
- 写清晰的提交信息
|
||||
- 及时添加changeset
|
||||
|
||||
### ❌ 避免做法
|
||||
- 直接在main分支开发
|
||||
- 长期存在的功能分支
|
||||
- 跳过changeset添加
|
||||
- 强制推送到保护分支
|
||||
- 合并未经测试的代码
|
||||
|
||||
## 工具和自动化
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
- **CI**: 每次PR都运行测试
|
||||
- **Snapshot发布**: develop分支自动发布
|
||||
- **正式发布**: main分支自动发布
|
||||
- **PR检查**: 自动检查changeset
|
||||
|
||||
### 本地工具
|
||||
|
||||
```bash
|
||||
# 安装git hooks
|
||||
pnpm prepare
|
||||
|
||||
# 运行完整验证
|
||||
pnpm validate
|
||||
|
||||
# 查看changeset状态
|
||||
pnpm changeset:status
|
||||
```
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Git Flow工作流](https://nvie.com/posts/a-successful-git-branching-model/)
|
||||
- [GitHub Flow](https://guides.github.com/introduction/flow/)
|
||||
- [Changesets文档](https://github.com/changesets/changesets)
|
||||
- [语义化版本控制](https://semver.org/lang/zh-CN/)
|
||||
178
docs/RELEASE.md
Normal file
178
docs/RELEASE.md
Normal file
@ -0,0 +1,178 @@
|
||||
# PromptX 发布流程
|
||||
|
||||
本文档描述了PromptX项目的版本管理和发布流程。
|
||||
|
||||
## 版本管理策略
|
||||
|
||||
我们采用[Changesets](https://github.com/changesets/changesets)进行版本管理，遵循[语义化版本控制](https://semver.org/lang/zh-CN/)。
|
||||
|
||||
### 版本类型
|
||||
|
||||
- **Patch (0.0.X)**: Bug修复，向后兼容
|
||||
- **Minor (0.X.0)**: 新功能，向后兼容
|
||||
- **Major (X.0.0)**: 破坏性变更，不向后兼容
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 1. 功能开发
|
||||
|
||||
```bash
|
||||
# 创建功能分支
|
||||
git checkout -b feature/new-feature
|
||||
# 开发功能
|
||||
# 提交代码
|
||||
git commit -m "feat: add new feature"
|
||||
```
|
||||
|
||||
### 2. 添加Changeset
|
||||
|
||||
在提交PR之前，为需要发布的变更添加changeset：
|
||||
|
||||
```bash
|
||||
# 添加changeset
|
||||
pnpm changeset
|
||||
|
||||
# 或者使用快捷命令
|
||||
pnpm run version:patch # Bug修复
|
||||
pnpm run version:minor # 新功能
|
||||
pnpm run version:major # 破坏性变更
|
||||
```
|
||||
|
||||
这会创建一个`.changeset/*.md`文件，描述变更内容。
|
||||
|
||||
### 3. 提交PR
|
||||
|
||||
创建Pull Request，确保：
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 代码通过lint检查
|
||||
- [ ] 已添加changeset（如需要发布）
|
||||
- [ ] 更新了相关文档
|
||||
|
||||
## 发布流程
|
||||
|
||||
### 自动发布（推荐）
|
||||
|
||||
我们的CI/CD会自动处理发布：
|
||||
|
||||
1. **合并到main分支**后，GitHub Actions会：
|
||||
- 运行所有测试
|
||||
- 检查是否有pending changesets
|
||||
- 如果有，创建发布PR
|
||||
- 如果没有，发布snapshot版本
|
||||
|
||||
2. **合并发布PR**后：
|
||||
- 自动更新版本号
|
||||
- 生成CHANGELOG.md
|
||||
- 发布到npm
|
||||
- 创建GitHub Release
|
||||
|
||||
### 手动发布
|
||||
|
||||
如需手动发布：
|
||||
|
||||
```bash
|
||||
# 1. 确保在main分支且代码最新
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 2. 运行测试
|
||||
pnpm test:ci
|
||||
|
||||
# 3. 构建项目
|
||||
pnpm build
|
||||
|
||||
# 4. 更新版本并发布
|
||||
pnpm changeset version # 更新版本号
|
||||
pnpm changeset publish # 发布到npm
|
||||
```
|
||||
|
||||
### Snapshot发布
|
||||
|
||||
对于测试版本，可以发布snapshot：
|
||||
|
||||
```bash
|
||||
# 发布snapshot版本
|
||||
pnpm run release:snapshot
|
||||
```
|
||||
|
||||
这会创建类似`0.0.2-snapshot.1`的版本号。
|
||||
|
||||
## 发布检查清单
|
||||
|
||||
发布前请确认：
|
||||
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 代码已通过review
|
||||
- [ ] 文档已更新
|
||||
- [ ] CHANGELOG.md准确反映变更
|
||||
- [ ] 版本号符合语义化版本控制
|
||||
- [ ] 重要变更已在README中标注
|
||||
|
||||
## NPM包管理
|
||||
|
||||
### 配置NPM Token
|
||||
|
||||
在GitHub仓库设置中添加secrets：
|
||||
|
||||
1. `NPM_TOKEN`: NPM发布token
|
||||
2. `GITHUB_TOKEN`: GitHub Actions自动提供
|
||||
|
||||
### 包信息
|
||||
|
||||
- **包名**: `dpml-prompt`
|
||||
- **作用域**: 公开包
|
||||
- **注册表**: `https://registry.npmjs.org/`
|
||||
|
||||
### 安装方式
|
||||
|
||||
```bash
|
||||
# 稳定版本
|
||||
npm install -g dpml-prompt
|
||||
|
||||
# 测试版本
|
||||
npm install -g dpml-prompt@snapshot
|
||||
|
||||
# 指定版本
|
||||
npm install -g dpml-prompt@0.0.2
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **发布失败**
|
||||
```bash
|
||||
# 检查changeset状态
|
||||
pnpm changeset status
|
||||
|
||||
# 检查npm token
|
||||
npm whoami
|
||||
```
|
||||
|
||||
2. **版本冲突**
|
||||
```bash
|
||||
# 重置changeset
|
||||
rm -rf .changeset/*.md
|
||||
pnpm changeset
|
||||
```
|
||||
|
||||
3. **构建失败**
|
||||
```bash
|
||||
# 清理并重新安装
|
||||
rm -rf node_modules pnpm-lock.yaml
|
||||
pnpm install
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 联系支持
|
||||
|
||||
如遇到发布问题，请：
|
||||
1. 检查GitHub Actions日志
|
||||
2. 查看[Issues](https://github.com/Deepractice/PromptX/issues)
|
||||
3. 联系维护者：sean@deepracticex.com
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Changesets文档](https://github.com/changesets/changesets)
|
||||
- [语义化版本控制](https://semver.org/lang/zh-CN/)
|
||||
- [NPM发布指南](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages)
|
||||
Reference in New Issue
Block a user