npm - @zjex/git-workflow - Versions diffs - 0.4.0 → 0.4.2 - Mend

@zjex/git-workflow 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.md +488 -12
package/README.md +8 -10
package/ROADMAP.md +1 -1
package/dist/index.js +124 -22
package/docs/.vitepress/config.ts +111 -100
package/docs/guide/api.md +607 -0
package/docs/guide/contributing.md +441 -0
package/docs/guide/development.md +295 -0
package/docs/guide/team-collaboration.md +538 -0
package/docs/guide/testing.md +461 -0
package/package.json +3 -3
package/scripts/generate-changelog-manual.js +135 -0
package/src/commands/stash.ts +176 -7
package/tests/stash.test.ts +161 -89
package/CODE_DOCUMENTATION.md +0 -169
package/TESTING.md +0 -436
package/TEST_COVERAGE_SUMMARY.md +0 -264

package/docs/guide/contributing.md ADDED Viewed

@@ -0,0 +1,441 @@
+# 贡献指南
+感谢你考虑为 git-workflow 做出贡献！本指南将帮助你了解如何参与项目开发。
+## 行为准则
+我们致力于为所有人提供友好、安全和包容的环境。参与本项目即表示你同意遵守以下准则：
+- 使用友好和包容的语言
+- 尊重不同的观点和经验
+- 优雅地接受建设性批评
+- 关注对社区最有利的事情
+- 对其他社区成员表示同理心
+## 如何贡献
+### 报告 Bug
+如果你发现了 bug，请：
+1. 检查 [Issues](https://github.com/iamzjt-front-end/git-workflow/issues) 确认问题未被报告
+2. 创建新 Issue，包含：
+   - 清晰的标题和描述
+   - 重现步骤
+   - 预期行为和实际行为
+   - 环境信息（OS、Node.js 版本等）
+   - 相关的错误信息或截图
+**Bug 报告模板：**
+```markdown
+## 问题描述
+简要描述遇到的问题
+## 重现步骤
+1. 运行命令 `gw xxx`
+2. 选择选项 xxx
+3. 看到错误 xxx
+## 预期行为
+应该显示 xxx
+## 实际行为
+显示了 xxx 错误
+## 环境信息
+- OS: macOS 14.0
+- Node.js: v20.0.0
+- git-workflow: v0.4.0
+## 错误信息
+```
+错误堆栈或截图
+```
+```
+### 提出新功能
+如果你有新功能的想法：
+1. 先创建 Issue 讨论功能的必要性和设计
+2. 等待维护者反馈
+3. 获得批准后再开始开发
+**功能请求模板：**
+```markdown
+## 功能描述
+简要描述想要的功能
+## 使用场景
+为什么需要这个功能？它解决什么问题？
+## 建议的实现
+如何实现这个功能？
+## 替代方案
+是否考虑过其他方案？
+```
+### 提交代码
+#### 1. Fork 仓库
+点击 GitHub 页面右上角的 "Fork" 按钮。
+#### 2. 克隆你的 Fork
+```bash
+git clone https://github.com/YOUR_USERNAME/git-workflow.git
+cd git-workflow
+```
+#### 3. 添加上游仓库
+```bash
+git remote add upstream https://github.com/iamzjt-front-end/git-workflow.git
+```
+#### 4. 创建分支
+```bash
+# 使用 gw 创建规范分支
+gw f
+# 输入 Story ID（可选）和描述
+# 或手动创建
+git checkout -b feature/20260116-PROJ-123-your-feature
+```
+#### 5. 开发功能
+- 编写代码
+- 添加测试
+- 更新文档
+- 确保代码通过 lint 和测试
+```bash
+# 运行测试
+npm test
+# 检查类型
+npm run build
+```
+#### 6. 提交代码
+使用规范的提交信息：
+```bash
+# 使用 gw 提交（推荐）
+gw c
+# 或手动提交
+git add .
+git commit -m "feat: add new feature"
+```
+提交信息格式：
+```
+<type>(<scope>): <subject>
+<body>
+<footer>
+```
+类型（type）：
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码格式（不影响功能）
+- `refactor`: 重构
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+- `perf`: 性能优化
+示例：
+```
+feat(commit): 添加 AI 提交消息生成功能
+- 集成 OpenAI API
+- 支持自定义提示词
+- 添加错误处理
+Closes #123
+```
+#### 7. 推送到你的 Fork
+```bash
+git push origin feature/20260116-PROJ-123-your-feature
+```
+#### 8. 创建 Pull Request
+1. 访问你的 Fork 页面
+2. 点击 "New Pull Request"
+3. 填写 PR 描述：
+   - 说明改动内容
+   - 关联相关 Issue
+   - 添加截图（如果适用）
+4. 等待 review
+**PR 模板：**
+```markdown
+## 改动说明
+简要描述这个 PR 做了什么
+## 关联 Issue
+Closes #123
+## 改动类型
+- [ ] Bug 修复
+- [ ] 新功能
+- [ ] 文档更新
+- [ ] 代码重构
+- [ ] 性能优化
+- [ ] 测试相关
+## 测试
+- [ ] 添加了新的测试
+- [ ] 所有测试通过
+- [ ] 手动测试通过
+## 截图（如果适用）
+添加截图展示改动效果
+## Checklist
+- [ ] 代码遵循项目规范
+- [ ] 添加了必要的测试
+- [ ] 更新了相关文档
+- [ ] 提交信息符合规范
+```
+## 开发规范
+### 代码风格
+- 使用 TypeScript 严格模式
+- 遵循 ESLint 规则
+- 使用 2 空格缩进
+- 使用单引号
+- 添加必要的注释
+### 命名规范
+```typescript
+// 文件名：kebab-case
+// ai-service.ts, commit-format.ts
+// 函数名：camelCase
+function getBranchName() {}
+async function generateCommitMessage() {}
+// 类型/接口：PascalCase
+interface CommitConfig {}
+type BranchType = "feature" | "hotfix";
+// 常量：UPPER_SNAKE_CASE
+const DEFAULT_CONFIG = {};
+const MAX_RETRIES = 3;
+// 私有函数：以 _ 开头
+function _internalHelper() {}
+```
+### 函数设计
+```typescript
+// ✅ 好的函数设计
+/**
+ * 生成规范的分支名
+ * @param type - 分支类型
+ * @param storyId - Story ID（可选）
+ * @param description - 分支描述
+ * @returns 格式化的分支名
+ */
+function generateBranchName(
+  type: BranchType,
+  storyId: string,
+  description: string
+): string {
+  // 实现
+}
+// ❌ 不好的函数设计
+function doStuff(a: any, b: any): any {
+  // 实现
+}
+```
+### 错误处理
+```typescript
+// ✅ 好的错误处理
+try {
+  const result = await apiCall();
+  return result;
+} catch (error) {
+  if (error instanceof NetworkError) {
+    console.error("网络错误:", error.message);
+  } else {
+    console.error("未知错误:", error);
+  }
+  throw error;
+}
+// ❌ 不好的错误处理
+try {
+  const result = await apiCall();
+  return result;
+} catch (error) {
+  // 忽略错误
+}
+```
+### 测试要求
+每个新功能都必须包含测试：
+```typescript
+describe("新功能", () => {
+  it("应该正确处理正常情况", () => {
+    // 测试正常流程
+  });
+  it("应该处理边界情况", () => {
+    // 测试边界条件
+  });
+  it("应该处理错误情况", () => {
+    // 测试错误处理
+  });
+});
+```
+### 文档要求
+- 为新功能添加文档
+- 更新 README（如果需要）
+- 添加代码注释
+- 更新 CHANGELOG
+## Review 流程
+### 提交 PR 后
+1. 自动运行 CI 测试
+2. 维护者 review 代码
+3. 根据反馈修改代码
+4. 再次 review
+5. 合并到 main 分支
+### Review 标准
+代码会从以下方面进行 review：
+- ✅ 功能是否正确实现
+- ✅ 代码质量和可读性
+- ✅ 测试覆盖率
+- ✅ 文档完整性
+- ✅ 性能影响
+- ✅ 安全性考虑
+### 常见 Review 意见
+**代码质量：**
+```typescript
+// ❌ 需要改进
+function process(data: any) {
+  const result = data.map((x) => x * 2);
+  return result;
+}
+// ✅ 改进后
+/**
+ * 处理数据，将每个值翻倍
+ */
+function processData(numbers: number[]): number[] {
+  return numbers.map((num) => num * 2);
+}
+```
+**错误处理：**
+```typescript
+// ❌ 需要改进
+async function fetchData() {
+  const response = await fetch(url);
+  return response.json();
+}
+// ✅ 改进后
+async function fetchData(): Promise<Data> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return await response.json();
+  } catch (error) {
+    console.error("获取数据失败:", error);
+    throw error;
+  }
+}
+```
+## 发布流程
+发布由维护者执行：
+1. 更新版本号
+2. 更新 CHANGELOG
+3. 创建 tag
+4. 发布到 npm
+5. 发布 GitHub Release
+## 获取帮助
+如果你在贡献过程中遇到问题：
+- 📖 查看 [开发指南](./development.md)
+- 🧪 查看 [测试指南](./testing.md)
+- 💬 在 Issue 中提问
+- 💡 参与 [Discussions](https://github.com/iamzjt-front-end/git-workflow/discussions)
+## 贡献者
+感谢所有贡献者！
+<a href="https://github.com/iamzjt-front-end/git-workflow/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=iamzjt-front-end/git-workflow" />
+</a>
+## 许可证
+通过贡献代码，你同意你的贡献将在 [MIT License](https://github.com/iamzjt-front-end/git-workflow/blob/main/LICENSE) 下发布。

package/docs/guide/development.md ADDED Viewed

@@ -0,0 +1,295 @@
+# 开发指南
+本指南将帮助你快速搭建 git-workflow 的本地开发环境。
+## 环境要求
+- **Node.js**: >= 18.0.0
+- **npm**: >= 9.0.0（或使用 pnpm/yarn）
+- **Git**: >= 2.0.0
+## 快速开始
+### 1. 克隆仓库
+```bash
+git clone https://github.com/iamzjt-front-end/git-workflow.git
+cd git-workflow
+```
+### 2. 安装依赖
+```bash
+npm install
+```
+### 3. 开发模式
+```bash
+npm run dev
+```
+这会启动 TypeScript 的 watch 模式，自动编译代码变更。
+### 4. 本地测试
+在开发模式下，你可以直接运行编译后的代码：
+```bash
+# 使用 node 运行
+node dist/index.js <command>
+# 或者使用可执行权限
+./dist/index.js <command>
+# 示例
+node dist/index.js --version
+node dist/index.js f
+```
+### 5. 运行测试
+```bash
+# 运行所有测试
+npm test
+# 运行特定测试文件
+npm test -- tests/commit.test.ts
+# 监听模式（开发时使用）
+npm run test:watch
+# 查看测试覆盖率
+npm run test:coverage
+```
+### 6. 构建
+```bash
+npm run build
+```
+构建产物会输出到 `dist/` 目录。
+## 项目结构
+```
+git-workflow/
+├── src/                    # 源代码
+│   ├── commands/          # 命令实现
+│   │   ├── branch.ts     # 分支管理
+│   │   ├── commit.ts     # 提交管理
+│   │   ├── tag.ts        # 标签管理
+│   │   ├── stash.ts      # Stash 管理
+│   │   ├── release.ts    # 发布管理
+│   │   ├── log.ts        # 日志查看
+│   │   ├── update.ts     # 更新检查
+│   │   └── init.ts       # 初始化配置
+│   ├── ai-service.ts     # AI 服务
+│   ├── config.ts         # 配置管理
+│   ├── utils.ts          # 工具函数
+│   ├── update-notifier.ts # 更新通知
+│   └── index.ts          # 入口文件
+├── tests/                 # 测试文件
+├── docs/                  # VitePress 文档
+├── scripts/               # 构建和发布脚本
+└── dist/                  # 构建输出（git ignored）
+```
+## 开发工作流
+### 创建新功能
+1. 从 main 分支创建 feature 分支：
+```bash
+gw f
+# 或手动创建
+git checkout -b feature/YYYYMMDD-STORY-description
+```
+2. 开发功能并编写测试
+3. 运行测试确保通过：
+```bash
+npm test
+```
+4. 提交代码：
+```bash
+gw c
+# 或手动提交
+git add .
+git commit -m "feat: add new feature"
+```
+### 调试技巧
+#### 1. 使用 console.log
+在代码中添加 `console.log` 进行调试：
+```typescript
+console.log("Debug:", variable);
+```
+#### 2. 使用 Node.js 调试器
+在 VS Code 中创建 `.vscode/launch.json`：
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Current Test",
+      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
+      "args": ["run", "${file}"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}
+```
+#### 3. 测试特定场景
+创建临时测试文件快速验证：
+```typescript
+// test-temp.ts
+import { someFunction } from "./src/utils.js";
+console.log(someFunction("test"));
+```
+运行：
+```bash
+npx tsx test-temp.ts
+```
+## 代码规范
+### TypeScript
+- 使用严格模式（`strict: true`）
+- 为所有函数添加类型注解
+- 避免使用 `any`，使用 `unknown` 代替
+- 使用接口定义数据结构
+### 命名规范
+- **文件名**: kebab-case（如 `ai-service.ts`）
+- **函数名**: camelCase（如 `getBranchName`）
+- **类型/接口**: PascalCase（如 `CommitConfig`）
+- **常量**: UPPER_SNAKE_CASE（如 `DEFAULT_CONFIG`）
+### 提交信息
+遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+```
+<type>(<scope>): <subject>
+<body>
+<footer>
+```
+类型：
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码格式（不影响功能）
+- `refactor`: 重构
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+## 常见问题
+### Q: 如何添加新命令？
+1. 在 `src/commands/` 创建新文件
+2. 实现命令逻辑
+3. 在 `src/index.ts` 注册命令
+4. 添加测试文件
+5. 更新文档
+### Q: 如何添加新的 AI 提供商？
+1. 在 `src/ai-service.ts` 的 `generateCommitMessage` 函数中添加新的 case
+2. 实现 API 调用逻辑
+3. 更新配置类型定义
+4. 添加测试
+5. 更新 AI 配置文档
+### Q: 如何调试 Git 命令？
+使用 `execOutput` 函数查看 Git 命令输出：
+```typescript
+import { execOutput } from "./utils.js";
+const output = execOutput("git status --porcelain");
+console.log("Git output:", output);
+```
+### Q: 测试失败怎么办？
+1. 检查错误信息
+2. 运行单个测试文件定位问题
+3. 使用 `console.log` 调试
+4. 检查 mock 是否正确设置
+## 发布流程
+发布由维护者执行：
+1. 更新版本号：
+```bash
+npm run version
+```
+2. 更新 CHANGELOG
+3. 提交并推送：
+```bash
+git add .
+git commit -m "chore: release v1.x.x"
+git push
+```
+4. 创建 tag：
+```bash
+gw t
+```
+5. 发布到 npm：
+```bash
+npm publish
+```
+## 相关资源
+- [TypeScript 文档](https://www.typescriptlang.org/docs/)
+- [Vitest 文档](https://vitest.dev/)
+- [Inquirer.js 文档](https://github.com/SBoudrias/Inquirer.js)
+- [Commander.js 文档](https://github.com/tj/commander.js)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+## 获取帮助
+- 查看 [CODE_DOCUMENTATION.md](https://github.com/iamzjt-front-end/git-workflow/blob/main/CODE_DOCUMENTATION.md) 了解代码架构
+- 查看 [TESTING.md](https://github.com/iamzjt-front-end/git-workflow/blob/main/TESTING.md) 了解测试策略
+- 提交 [Issue](https://github.com/iamzjt-front-end/git-workflow/issues) 报告问题
+- 加入讨论 [Discussions](https://github.com/iamzjt-front-end/git-workflow/discussions)