diff --git a/.changeset/README.md b/.changeset/README.md new file mode 100644 index 0000000..e5b6d8d --- /dev/null +++ b/.changeset/README.md @@ -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) diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 0000000..6e10e8b --- /dev/null +++ b/.changeset/config.json @@ -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 + } +} diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ca68ea8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,28 @@ +## 变更说明 + +请简要描述此PR的主要变更: + +## 变更类型 + +- [ ] 🐛 Bug修复 (patch) +- [ ] ✨ 新功能 (minor) +- [ ] 💥 破坏性变更 (major) +- [ ] 📝 文档更新 +- [ ] 🎨 代码风格调整 +- [ ] ♻️ 代码重构 +- [ ] 🧪 测试相关 + +## Changeset检查 + +- [ ] 我已经运行 `pnpm changeset` 添加了变更日志 +- [ ] 或者这个PR不需要发布新版本(文档、测试、构建配置等) + +## 测试 + +- [ ] 所有现有测试通过 +- [ ] 添加了新的测试(如适用) +- [ ] 手动测试了相关功能 + +## 其他注意事项 + +请提及任何需要特别注意的地方或影响范围: \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..713a4b6 --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..0f621ab --- /dev/null +++ b/.github/workflows/release.yml @@ -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 }} \ No newline at end of file diff --git a/.github/workflows/snapshot.yml b/.github/workflows/snapshot.yml new file mode 100644 index 0000000..28024ae --- /dev/null +++ b/.github/workflows/snapshot.yml @@ -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 + }); + } \ No newline at end of file diff --git a/README.md b/README.md index 84d490f..cfd3654 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,30 @@ PromptX是开源项目,欢迎贡献: - ⚡ **执行模式**:优化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分支 +``` + 扫码加入技术交流群: 技术交流群 diff --git a/docs/BRANCHING.md b/docs/BRANCHING.md new file mode 100644 index 0000000..6b0c199 --- /dev/null +++ b/docs/BRANCHING.md @@ -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/) \ No newline at end of file diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000..bb281e3 --- /dev/null +++ b/docs/RELEASE.md @@ -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) \ No newline at end of file diff --git a/package.json b/package.json index ac75a88..a2bd9bf 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,16 @@ "format": "prettier --write src/", "format:check": "prettier --check src/", "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": [ "src/", @@ -58,6 +67,8 @@ "yaml": "^2.3.0" }, "devDependencies": { + "@changesets/changelog-github": "^0.5.1", + "@changesets/cli": "^2.29.4", "@types/jest": "^29.5.0", "eslint": "^8.42.0", "eslint-config-standard": "^17.1.0",