Back to Details

git-workflow-and-versioning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Workflow and Versioning

Git工作流与版本控制

Use this skill when

使用此技能的场景

Use this Skill when creating commits, preparing a branch, describing a release, updating a changelog, or deciding how to preserve a clean and reviewable history.
当你创建提交、准备分支、描述版本发布、更新变更日志，或决定如何维护清晰且便于评审的历史记录时，使用此Skill。

Operating rules

操作规则

  1. Confirm the current branch and working tree.
  2. Keep the branch scope aligned with the approved change.
  3. Group related changes into atomic commits.
  4. Write commit messages that explain behavior and intent.
  5. Review the diff and tests before committing.
  6. Use version changes that match user-visible compatibility impact.
  7. Record why a meaningful engineering rule changed.
  1. 确认当前分支和工作树状态。
  2. 保持分支范围与已批准的变更内容一致。
  3. 将相关变更归类为原子提交。
  4. 撰写能解释行为和意图的提交信息。
  5. 提交前审查代码差异和测试情况。
  6. 使用与用户可见的兼容性影响匹配的版本变更。
  7. 记录有意义的工程规则变更原因。

MUST

必须遵循的规则

  • Do not discard user changes.
  • Do not use destructive Git commands without explicit authorization.
  • Keep unrelated formatting and cleanup out of the task branch.
  • Make commits reviewable and internally coherent.
  • Ensure the changelog describes meaningful behavior and reasons.
  • 不得丢弃用户的变更内容。
  • 未经明确授权，不得使用破坏性Git命令。
  • 避免将无关的格式调整和清理操作放入任务分支。
  • 确保提交内容便于评审且内部逻辑连贯。
  • 确保变更日志描述有意义的行为和原因。

SHOULD

建议遵循的规则

  • Prefer one behavior or migration step per commit.
  • Keep generated artifacts out of source unless the project requires them.
  • Use patch, minor, and major version changes consistently.
  • Preserve a clean diff before handoff.
  • Mention verification in the commit or handoff summary.
  • 优先为每个提交设置单一行为或迁移步骤。
  • 除非项目要求，否则避免将生成的产物存入源码。
  • 持续一致地使用补丁（PATCH）、次要（MINOR）和主要（MAJOR）版本变更。
  • 移交前保持清晰的代码差异。
  • 在提交或移交总结中提及验证情况。

Versioning

版本控制规则

  • PATCH: wording, examples, ambiguity removal, or non-decision-changing corrections.
  • MINOR: new rules, references, eval cases, or capabilities that preserve the philosophy.
  • MAJOR: a change to a core engineering principle or a breaking public workflow.
Read branches-and-commits.md for history shape and history-hygiene.md for safe cleanup and release notes.
  • PATCH：措辞调整、示例补充、歧义消除，或不改变决策的修正。
  • MINOR：新增规则、参考内容、评估案例，或在保留原有理念的前提下新增功能。
  • MAJOR：核心工程原则变更，或对公开工作流造成破坏性影响的变更。
阅读branches-and-commits.md了解历史记录形态，阅读history-hygiene.md了解安全清理和发布说明相关内容。

Routing

路由指引

Use code-review-and-quality before committing a meaningful change. Use ci-cd-and-automation for pipeline and release checks. Do not use Git history operations to hide an unresolved debugging or review problem.
在提交有意义的变更前，使用代码评审与质量相关技能。使用CI/CD与自动化技能处理流水线和发布检查。请勿使用Git历史操作来掩盖未解决的调试或评审问题。

Verification

验证环节

Before handoff, show the branch, diff summary, tests, commit scope, version impact, and changelog update.
移交前，展示分支信息、代码差异摘要、测试结果、提交范围、版本影响以及变更日志更新内容。