178 lines
3.4 KiB
Markdown
178 lines
3.4 KiB
Markdown
# 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) |