feat: 添加现代化版本管理和自动发布系统
This commit is contained in:
sean
8
.changeset/README.md
Normal file
8
.changeset/README.md
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
# Changesets
|
||||||
|
|
||||||
|
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
|
||||||
|
with multi-package repos, or single-package repos to help you version and publish your code. You can
|
||||||
|
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
|
||||||
|
|
||||||
|
We have a quick list of common questions to get you started engaging with this project in
|
||||||
|
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
|
||||||
19
.changeset/config.json
Normal file
19
.changeset/config.json
Normal file
@ -0,0 +1,19 @@
|
|||||||
|
{
|
||||||
|
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
|
||||||
|
"changelog": [
|
||||||
|
"@changesets/changelog-github",
|
||||||
|
{
|
||||||
|
"repo": "Deepractice/PromptX"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"commit": false,
|
||||||
|
"fixed": [],
|
||||||
|
"linked": [],
|
||||||
|
"access": "public",
|
||||||
|
"baseBranch": "develop",
|
||||||
|
"updateInternalDependencies": "patch",
|
||||||
|
"ignore": [],
|
||||||
|
"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
|
||||||
|
"onlyUpdatePeerDependentsWhenOutOfRange": true
|
||||||
|
}
|
||||||
|
}
|
||||||
28
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
28
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
@ -0,0 +1,28 @@
|
|||||||
|
## 变更说明
|
||||||
|
|
||||||
|
请简要描述此PR的主要变更：
|
||||||
|
|
||||||
|
## 变更类型
|
||||||
|
|
||||||
|
- [ ] 🐛 Bug修复 (patch)
|
||||||
|
- [ ] ✨ 新功能 (minor)
|
||||||
|
- [ ] 💥 破坏性变更 (major)
|
||||||
|
- [ ] 📝 文档更新
|
||||||
|
- [ ] 🎨 代码风格调整
|
||||||
|
- [ ] ♻️ 代码重构
|
||||||
|
- [ ] 🧪 测试相关
|
||||||
|
|
||||||
|
## Changeset检查
|
||||||
|
|
||||||
|
- [ ] 我已经运行 `pnpm changeset` 添加了变更日志
|
||||||
|
- [ ] 或者这个PR不需要发布新版本（文档、测试、构建配置等）
|
||||||
|
|
||||||
|
## 测试
|
||||||
|
|
||||||
|
- [ ] 所有现有测试通过
|
||||||
|
- [ ] 添加了新的测试（如适用）
|
||||||
|
- [ ] 手动测试了相关功能
|
||||||
|
|
||||||
|
## 其他注意事项
|
||||||
|
|
||||||
|
请提及任何需要特别注意的地方或影响范围：
|
||||||
83
.github/workflows/ci.yml
vendored
Normal file
83
.github/workflows/ci.yml
vendored
Normal file
@ -0,0 +1,83 @@
|
|||||||
|
name: CI
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [main, develop]
|
||||||
|
pull_request:
|
||||||
|
branches: [main, develop]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
test:
|
||||||
|
name: Test & Lint
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
node-version: [18.x, 20.x]
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup pnpm
|
||||||
|
uses: pnpm/action-setup@v2
|
||||||
|
with:
|
||||||
|
version: latest
|
||||||
|
|
||||||
|
- name: Setup Node.js ${{ matrix.node-version }}
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: ${{ matrix.node-version }}
|
||||||
|
cache: 'pnpm'
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
|
- name: Run linter
|
||||||
|
run: pnpm run lint
|
||||||
|
|
||||||
|
- name: Run unit tests
|
||||||
|
run: pnpm run test:unit
|
||||||
|
|
||||||
|
- name: Run integration tests
|
||||||
|
run: pnpm run test:integration
|
||||||
|
|
||||||
|
- name: Generate test coverage
|
||||||
|
run: pnpm run test:coverage
|
||||||
|
|
||||||
|
- name: Upload coverage to Codecov
|
||||||
|
uses: codecov/codecov-action@v3
|
||||||
|
with:
|
||||||
|
file: ./coverage/lcov.info
|
||||||
|
fail_ci_if_error: false
|
||||||
|
|
||||||
|
build:
|
||||||
|
name: Build Package
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: test
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup pnpm
|
||||||
|
uses: pnpm/action-setup@v2
|
||||||
|
with:
|
||||||
|
version: latest
|
||||||
|
|
||||||
|
- name: Setup Node.js
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: '20.x'
|
||||||
|
cache: 'pnpm'
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
|
- name: Build package
|
||||||
|
run: pnpm run build
|
||||||
|
|
||||||
|
- name: Test CLI commands
|
||||||
|
run: |
|
||||||
|
node src/bin/promptx.js hello
|
||||||
|
node src/bin/promptx.js --help
|
||||||
51
.github/workflows/release.yml
vendored
Normal file
51
.github/workflows/release.yml
vendored
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
name: Release
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- main
|
||||||
|
|
||||||
|
concurrency: ${{ github.workflow }}-${{ github.ref }}
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
release:
|
||||||
|
name: Release
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
# This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: Setup pnpm
|
||||||
|
uses: pnpm/action-setup@v2
|
||||||
|
with:
|
||||||
|
version: latest
|
||||||
|
|
||||||
|
- name: Setup Node.js
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: '20.x'
|
||||||
|
cache: 'pnpm'
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
|
- name: Run tests
|
||||||
|
run: pnpm run test:ci
|
||||||
|
|
||||||
|
- name: Build package
|
||||||
|
run: pnpm run build
|
||||||
|
|
||||||
|
- name: Create Release Pull Request or Publish to npm
|
||||||
|
id: changesets
|
||||||
|
uses: changesets/action@v1
|
||||||
|
with:
|
||||||
|
# This expects you to have a script called release which does a build for your packages and calls changeset publish
|
||||||
|
publish: pnpm changeset publish
|
||||||
|
title: 'chore: release package'
|
||||||
|
commit: 'chore: release package'
|
||||||
|
env:
|
||||||
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||||
|
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||||
88
.github/workflows/snapshot.yml
vendored
Normal file
88
.github/workflows/snapshot.yml
vendored
Normal file
@ -0,0 +1,88 @@
|
|||||||
|
name: Snapshot Release
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- develop
|
||||||
|
|
||||||
|
concurrency: ${{ github.workflow }}-${{ github.ref }}
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
snapshot:
|
||||||
|
name: Snapshot Release
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: Setup pnpm
|
||||||
|
uses: pnpm/action-setup@v2
|
||||||
|
with:
|
||||||
|
version: latest
|
||||||
|
|
||||||
|
- name: Setup Node.js
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: '20.x'
|
||||||
|
cache: 'pnpm'
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
run: pnpm install --frozen-lockfile
|
||||||
|
|
||||||
|
- name: Run tests
|
||||||
|
run: pnpm run test:ci
|
||||||
|
|
||||||
|
- name: Build package
|
||||||
|
run: pnpm run build
|
||||||
|
|
||||||
|
- name: Release snapshot version
|
||||||
|
run: |
|
||||||
|
# 确保在正确的分支
|
||||||
|
git checkout develop
|
||||||
|
|
||||||
|
# 创建snapshot版本
|
||||||
|
pnpm changeset version --snapshot snapshot
|
||||||
|
|
||||||
|
# 发布snapshot版本到npm
|
||||||
|
pnpm changeset publish --tag snapshot
|
||||||
|
env:
|
||||||
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||||
|
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||||
|
|
||||||
|
- name: Comment on related PRs
|
||||||
|
if: success()
|
||||||
|
uses: actions/github-script@v7
|
||||||
|
with:
|
||||||
|
script: |
|
||||||
|
const { execSync } = require('child_process');
|
||||||
|
|
||||||
|
// 获取当前版本号
|
||||||
|
const packageJson = require('./package.json');
|
||||||
|
const version = packageJson.version;
|
||||||
|
|
||||||
|
// 查找相关的PR
|
||||||
|
const { data: prs } = await github.rest.pulls.list({
|
||||||
|
owner: context.repo.owner,
|
||||||
|
repo: context.repo.repo,
|
||||||
|
state: 'open',
|
||||||
|
base: 'develop'
|
||||||
|
});
|
||||||
|
|
||||||
|
const comment = `🚀 **Snapshot版本已发布!**
|
||||||
|
|
||||||
|
📦 版本号: \`${version}\`
|
||||||
|
🔗 安装命令: \`npm install -g dpml-prompt@snapshot\`
|
||||||
|
|
||||||
|
你可以使用这个snapshot版本测试最新功能。`;
|
||||||
|
|
||||||
|
// 为每个相关PR添加评论
|
||||||
|
for (const pr of prs) {
|
||||||
|
await github.rest.issues.createComment({
|
||||||
|
owner: context.repo.owner,
|
||||||
|
repo: context.repo.repo,
|
||||||
|
issue_number: pr.number,
|
||||||
|
body: comment
|
||||||
|
});
|
||||||
|
}
|
||||||
24
README.md
24
README.md
@ -158,6 +158,30 @@ PromptX是开源项目，欢迎贡献：
|
|||||||
- ⚡ **执行模式**：优化AI行为模式
|
- ⚡ **执行模式**：优化AI行为模式
|
||||||
- 📚 **知识库**：丰富领域知识体系
|
- 📚 **知识库**：丰富领域知识体系
|
||||||
|
|
||||||
|
### 贡献指南
|
||||||
|
|
||||||
|
- 📋 [贡献流程](CONTRIBUTING.md) - 详细的贡献指南
|
||||||
|
- 🌿 [分支策略](docs/BRANCHING.md) - 分支管理和发布流程
|
||||||
|
- 🚀 [发布流程](docs/RELEASE.md) - 版本管理和发布文档
|
||||||
|
|
||||||
|
### 快速开始贡献
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Fork并克隆项目
|
||||||
|
git clone https://github.com/YOUR_USERNAME/PromptX.git
|
||||||
|
|
||||||
|
# 2. 切换到develop分支
|
||||||
|
git checkout develop
|
||||||
|
|
||||||
|
# 3. 创建功能分支
|
||||||
|
git checkout -b feature/your-feature
|
||||||
|
|
||||||
|
# 4. 开发功能并添加changeset
|
||||||
|
pnpm changeset
|
||||||
|
|
||||||
|
# 5. 提交PR到develop分支
|
||||||
|
```
|
||||||
|
|
||||||
扫码加入技术交流群：
|
扫码加入技术交流群：
|
||||||
|
|
||||||
<img src="assets/qrcode.jpg" alt="技术交流群" width="200">
|
<img src="assets/qrcode.jpg" alt="技术交流群" width="200">
|
||||||
|
|||||||
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)
|
||||||
13
package.json
13
package.json
@ -28,7 +28,16 @@
|
|||||||
"format": "prettier --write src/",
|
"format": "prettier --write src/",
|
||||||
"format:check": "prettier --check src/",
|
"format:check": "prettier --check src/",
|
||||||
"validate": "npm run lint && npm run test:ci",
|
"validate": "npm run lint && npm run test:ci",
|
||||||
"precommit": "npm run lint && npm run test:unit"
|
"precommit": "npm run lint && npm run test:unit",
|
||||||
|
"changeset": "changeset",
|
||||||
|
"changeset:version": "changeset version",
|
||||||
|
"changeset:publish": "changeset publish",
|
||||||
|
"changeset:status": "changeset status",
|
||||||
|
"release": "pnpm run build && pnpm changeset publish",
|
||||||
|
"release:snapshot": "pnpm changeset version --snapshot snapshot && pnpm changeset publish --tag snapshot",
|
||||||
|
"version:patch": "pnpm changeset add --type patch",
|
||||||
|
"version:minor": "pnpm changeset add --type minor",
|
||||||
|
"version:major": "pnpm changeset add --type major"
|
||||||
},
|
},
|
||||||
"files": [
|
"files": [
|
||||||
"src/",
|
"src/",
|
||||||
@ -58,6 +67,8 @@
|
|||||||
"yaml": "^2.3.0"
|
"yaml": "^2.3.0"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
|
"@changesets/changelog-github": "^0.5.1",
|
||||||
|
"@changesets/cli": "^2.29.4",
|
||||||
"@types/jest": "^29.5.0",
|
"@types/jest": "^29.5.0",
|
||||||
"eslint": "^8.42.0",
|
"eslint": "^8.42.0",
|
||||||
"eslint-config-standard": "^17.1.0",
|
"eslint-config-standard": "^17.1.0",
|
||||||
|
|||||||
Reference in New Issue
Block a user