universal-dev-standards 6.14.0-beta.9 → 6.14.0
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.
- package/bin/uds.js +12 -1
- package/bundled/ai/options/commit-message/traditional-chinese.ai.yaml +69 -67
- package/bundled/ai/standards/commit-message.ai.yaml +12 -2
- package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
- package/bundled/core/commit-message-guide.md +22 -19
- package/bundled/core/secret-management-standards.md +13 -1
- package/bundled/extensions/locales/zh-tw.md +19 -19
- package/bundled/hooks/validate-commit-msg.mjs +52 -9
- package/bundled/locales/zh-CN/CHANGELOG.md +2309 -1110
- package/bundled/locales/zh-CN/CLAUDE.md +987 -101
- package/bundled/locales/zh-CN/README.md +3 -3
- package/bundled/locales/zh-CN/SECURITY.md +3 -3
- package/bundled/locales/zh-CN/STANDARDS-MAPPING.md +103 -6
- package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +68 -97
- package/bundled/locales/zh-CN/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
- package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +8 -9
- package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +81 -80
- package/bundled/locales/zh-CN/adoption/checklists/minimal.md +18 -14
- package/bundled/locales/zh-CN/adoption/checklists/recommended.md +49 -46
- package/bundled/locales/zh-CN/ai/MAINTENANCE.md +44 -9
- package/bundled/locales/zh-CN/ai/options/commit-message/traditional-chinese.ai.yaml +63 -55
- package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +61 -14
- package/bundled/locales/zh-CN/core/acceptance-test-driven-development.md +2 -1
- package/bundled/locales/zh-CN/core/accessibility-standards.md +871 -62
- package/bundled/locales/zh-CN/core/adr-standards.md +155 -32
- package/bundled/locales/zh-CN/core/agent-communication-protocol.md +2 -1
- package/bundled/locales/zh-CN/core/agent-dispatch.md +68 -33
- package/bundled/locales/zh-CN/core/ai-agreement-standards.md +23 -22
- package/bundled/locales/zh-CN/core/ai-command-behavior.md +2 -1
- package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +311 -72
- package/bundled/locales/zh-CN/core/ai-instruction-standards.md +71 -49
- package/bundled/locales/zh-CN/core/ai-response-navigation.md +2 -1
- package/bundled/locales/zh-CN/core/alerting-standards.md +231 -36
- package/bundled/locales/zh-CN/core/anti-hallucination.md +116 -697
- package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +34 -33
- package/bundled/locales/zh-CN/core/api-design-standards.md +144 -58
- package/bundled/locales/zh-CN/core/behavior-driven-development.md +2 -1
- package/bundled/locales/zh-CN/core/branch-completion.md +75 -20
- package/bundled/locales/zh-CN/core/capability-declaration.md +44 -94
- package/bundled/locales/zh-CN/core/change-batching-standards.md +2 -1
- package/bundled/locales/zh-CN/core/changelog-standards.md +485 -63
- package/bundled/locales/zh-CN/core/chaos-engineering-standards.md +141 -39
- package/bundled/locales/zh-CN/core/checkin-standards.md +176 -116
- package/bundled/locales/zh-CN/core/circuit-breaker.md +43 -77
- package/bundled/locales/zh-CN/core/code-review-checklist.md +37 -23
- package/bundled/locales/zh-CN/core/commit-message-guide.md +892 -69
- package/bundled/locales/zh-CN/core/containerization-standards.md +259 -57
- package/bundled/locales/zh-CN/core/context-aware-loading.md +103 -29
- package/bundled/locales/zh-CN/core/database-standards.md +115 -114
- package/bundled/locales/zh-CN/core/deprecation-standards.md +155 -40
- package/bundled/locales/zh-CN/core/design-document-standards.md +265 -55
- package/bundled/locales/zh-CN/core/developer-memory.md +150 -60
- package/bundled/locales/zh-CN/core/documentation-lifecycle.md +20 -16
- package/bundled/locales/zh-CN/core/documentation-structure.md +1284 -127
- package/bundled/locales/zh-CN/core/documentation-writing-standards.md +649 -259
- package/bundled/locales/zh-CN/core/dual-phase-output.md +37 -70
- package/bundled/locales/zh-CN/core/environment-standards.md +251 -73
- package/bundled/locales/zh-CN/core/error-code-standards.md +501 -60
- package/bundled/locales/zh-CN/core/estimation-standards.md +174 -41
- package/bundled/locales/zh-CN/core/execution-history.md +2 -1
- package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +71 -84
- package/bundled/locales/zh-CN/core/feature-flag-standards.md +202 -57
- package/bundled/locales/zh-CN/core/forward-derivation-standards.md +613 -154
- package/bundled/locales/zh-CN/core/frontend-design-standards.md +361 -78
- package/bundled/locales/zh-CN/core/git-workflow.md +148 -262
- package/bundled/locales/zh-CN/core/git-worktree.md +59 -26
- package/bundled/locales/zh-CN/core/guides/file-placement-guide.md +132 -48
- package/bundled/locales/zh-CN/core/guides/performance-guide.md +61 -59
- package/bundled/locales/zh-CN/core/guides/security-guide.md +2 -0
- package/bundled/locales/zh-CN/core/health-check-standards.md +46 -104
- package/bundled/locales/zh-CN/core/immutability-first.md +83 -60
- package/bundled/locales/zh-CN/core/knowledge-transfer-standards.md +94 -31
- package/bundled/locales/zh-CN/core/mutation-testing.md +45 -6
- package/bundled/locales/zh-CN/core/observability-standards.md +281 -37
- package/bundled/locales/zh-CN/core/performance-standards.md +402 -42
- package/bundled/locales/zh-CN/core/pipeline-integration-standards.md +2 -1
- package/bundled/locales/zh-CN/core/postmortem-standards.md +358 -53
- package/bundled/locales/zh-CN/core/privacy-standards.md +148 -40
- package/bundled/locales/zh-CN/core/project-context-memory.md +182 -48
- package/bundled/locales/zh-CN/core/project-structure.md +550 -170
- package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +54 -114
- package/bundled/locales/zh-CN/core/refactoring-standards.md +141 -556
- package/bundled/locales/zh-CN/core/requirement-engineering.md +7 -6
- package/bundled/locales/zh-CN/core/retrospective-standards.md +215 -22
- package/bundled/locales/zh-CN/core/retry-standards.md +46 -101
- package/bundled/locales/zh-CN/core/reverse-engineering-standards.md +370 -120
- package/bundled/locales/zh-CN/core/runbook-standards.md +294 -48
- package/bundled/locales/zh-CN/core/security-decision.md +45 -70
- package/bundled/locales/zh-CN/core/security-standards.md +169 -16
- package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +105 -71
- package/bundled/locales/zh-CN/core/slo-standards.md +296 -44
- package/bundled/locales/zh-CN/core/spec-driven-development.md +37 -6
- package/bundled/locales/zh-CN/core/standard-admission-criteria.md +25 -31
- package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +49 -57
- package/bundled/locales/zh-CN/core/structured-task-definition.md +2 -1
- package/bundled/locales/zh-CN/core/supply-chain-security-standards.md +159 -32
- package/bundled/locales/zh-CN/core/systematic-debugging.md +87 -42
- package/bundled/locales/zh-CN/core/tech-debt-standards.md +202 -86
- package/bundled/locales/zh-CN/core/test-completeness-dimensions.md +262 -190
- package/bundled/locales/zh-CN/core/test-data-standards.md +252 -30
- package/bundled/locales/zh-CN/core/test-driven-development.md +21 -1022
- package/bundled/locales/zh-CN/core/test-governance.md +94 -43
- package/bundled/locales/zh-CN/core/testing-standards.md +83 -37
- package/bundled/locales/zh-CN/core/timeout-standards.md +45 -85
- package/bundled/locales/zh-CN/core/token-budget.md +44 -80
- package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +48 -36
- package/bundled/locales/zh-CN/core/verification-evidence.md +44 -22
- package/bundled/locales/zh-CN/core/versioning.md +737 -73
- package/bundled/locales/zh-CN/core/virtual-organization-standards.md +30 -29
- package/bundled/locales/zh-CN/core/workflow-enforcement.md +9 -8
- package/bundled/locales/zh-CN/core/workflow-state-protocol.md +9 -8
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +2 -1
- package/bundled/locales/zh-CN/docs/CLI-FLOW.md +2 -1
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +19 -10
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +8 -6
- package/bundled/locales/zh-CN/docs/STANDARDS-REFERENCE.md +2 -1
- package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +133 -132
- package/bundled/locales/zh-CN/docs/USER-MANUAL.md +11 -3
- package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +5 -2
- package/bundled/locales/zh-CN/docs/specs/system/memory-adoption-strategy.md +2 -0
- package/bundled/locales/zh-CN/docs/user/FAQ.md +2 -0
- package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +2 -0
- package/bundled/locales/zh-CN/docs/user/GLOSSARY.md +2 -0
- package/bundled/locales/zh-CN/docs/user/README.md +4 -2
- package/bundled/locales/zh-CN/docs/user/TROUBLESHOOTING.md +2 -0
- package/bundled/locales/zh-CN/integrations/codex/AGENTS.md +136 -2
- package/bundled/locales/zh-CN/integrations/codex/README.md +62 -10
- package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md +59 -1
- package/bundled/locales/zh-CN/integrations/gemini-cli/README.md +9 -2
- package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
- package/bundled/locales/zh-CN/integrations/github-copilot/README.md +8 -2
- package/bundled/locales/zh-CN/integrations/github-copilot/copilot-instructions.md +146 -12
- package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md +7 -1
- package/bundled/locales/zh-CN/integrations/google-antigravity/AGENTS.md +110 -3
- package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/opencode/AGENTS.md +140 -2
- package/bundled/locales/zh-CN/integrations/opencode/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md +8 -2
- package/bundled/locales/zh-CN/integrations/openspec/AGENTS.md +46 -1
- package/bundled/locales/zh-CN/integrations/openspec/README.md +7 -1
- package/bundled/locales/zh-CN/integrations/spec-kit/AGENTS.md +20 -2
- package/bundled/locales/zh-CN/integrations/spec-kit/README.md +7 -1
- package/bundled/locales/zh-CN/options/changelog/auto-generated.md +2 -0
- package/bundled/locales/zh-CN/options/changelog/keep-a-changelog.md +2 -0
- package/bundled/locales/zh-CN/options/code-review/automated-review.md +2 -0
- package/bundled/locales/zh-CN/options/code-review/pair-programming.md +2 -0
- package/bundled/locales/zh-CN/options/commit-message/bilingual.md +139 -50
- package/bundled/locales/zh-CN/options/commit-message/english.md +159 -42
- package/bundled/locales/zh-CN/options/commit-message/traditional-chinese.md +156 -75
- package/bundled/locales/zh-CN/options/documentation/api-docs.md +3 -1
- package/bundled/locales/zh-CN/options/documentation/markdown-docs.md +2 -0
- package/bundled/locales/zh-CN/options/documentation/wiki-style.md +2 -0
- package/bundled/locales/zh-CN/options/git-workflow/gitflow.md +105 -77
- package/bundled/locales/zh-CN/options/git-workflow/github-flow.md +75 -57
- package/bundled/locales/zh-CN/options/git-workflow/merge-commit.md +155 -44
- package/bundled/locales/zh-CN/options/git-workflow/rebase-ff.md +168 -53
- package/bundled/locales/zh-CN/options/git-workflow/squash-merge.md +122 -37
- package/bundled/locales/zh-CN/options/git-workflow/trunk-based.md +108 -61
- package/bundled/locales/zh-CN/options/project-structure/dotnet.md +266 -47
- package/bundled/locales/zh-CN/options/project-structure/go.md +301 -43
- package/bundled/locales/zh-CN/options/project-structure/java.md +268 -48
- package/bundled/locales/zh-CN/options/project-structure/kotlin.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/nodejs.md +168 -51
- package/bundled/locales/zh-CN/options/project-structure/php.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/python.md +210 -52
- package/bundled/locales/zh-CN/options/project-structure/ruby.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/rust.md +2 -0
- package/bundled/locales/zh-CN/options/project-structure/swift.md +2 -0
- package/bundled/locales/zh-CN/options/testing/contract-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/e2e-testing.md +227 -66
- package/bundled/locales/zh-CN/options/testing/industry-pyramid.md +2 -0
- package/bundled/locales/zh-CN/options/testing/integration-testing.md +185 -73
- package/bundled/locales/zh-CN/options/testing/istqb-framework.md +2 -0
- package/bundled/locales/zh-CN/options/testing/performance-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/security-testing.md +2 -0
- package/bundled/locales/zh-CN/options/testing/system-testing.md +270 -96
- package/bundled/locales/zh-CN/options/testing/unit-testing.md +185 -71
- package/bundled/locales/zh-CN/skills/CONTRIBUTING.template.md +43 -42
- package/bundled/locales/zh-CN/skills/INTEGRATION-GUIDE.md +2 -1
- package/bundled/locales/zh-CN/skills/README.md +2 -1
- package/bundled/locales/zh-CN/skills/_shared/README.md +2 -1
- package/bundled/locales/zh-CN/skills/adr-assistant/guide.md +240 -4
- package/bundled/locales/zh-CN/skills/agents/README.md +180 -82
- package/bundled/locales/zh-CN/skills/agents/code-architect.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/doc-writer.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/reviewer.md +4 -2
- package/bundled/locales/zh-CN/skills/agents/spec-analyst.md +3 -1
- package/bundled/locales/zh-CN/skills/agents/test-specialist.md +3 -1
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/SKILL.md +91 -81
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/anti-hallucination.md +79 -59
- package/bundled/locales/zh-CN/skills/ai-collaboration-standards/certainty-labels.md +66 -40
- package/bundled/locales/zh-CN/skills/ai-friendly-architecture/SKILL.md +23 -36
- package/bundled/locales/zh-CN/skills/ai-instruction-standards/SKILL.md +217 -137
- package/bundled/locales/zh-CN/skills/api-design-assistant/SKILL.md +13 -2
- package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
- package/bundled/locales/zh-CN/skills/atdd-assistant/atdd-workflow.md +98 -1
- package/bundled/locales/zh-CN/skills/atdd-assistant/guide.md +148 -132
- package/bundled/locales/zh-CN/skills/audit-assistant/SKILL.md +5 -2
- package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/bdd-assistant/bdd-workflow.md +2 -1
- package/bundled/locales/zh-CN/skills/bdd-assistant/gherkin-guide.md +2 -1
- package/bundled/locales/zh-CN/skills/bdd-assistant/guide.md +122 -121
- package/bundled/locales/zh-CN/skills/changelog-guide/SKILL.md +9 -2
- package/bundled/locales/zh-CN/skills/changelog-guide/guide.md +91 -88
- package/bundled/locales/zh-CN/skills/checkin-assistant/SKILL.md +12 -2
- package/bundled/locales/zh-CN/skills/checkin-assistant/guide.md +211 -210
- package/bundled/locales/zh-CN/skills/ci-cd-assistant/SKILL.md +14 -2
- package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +12 -2
- package/bundled/locales/zh-CN/skills/code-review-assistant/checkin-checklist.md +79 -78
- package/bundled/locales/zh-CN/skills/code-review-assistant/guide.md +119 -45
- package/bundled/locales/zh-CN/skills/code-review-assistant/review-checklist.md +89 -88
- package/bundled/locales/zh-CN/skills/commands/ac-coverage.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/api-design.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/atdd.md +71 -1
- package/bundled/locales/zh-CN/skills/commands/audit.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/bdd.md +160 -62
- package/bundled/locales/zh-CN/skills/commands/changelog.md +36 -1
- package/bundled/locales/zh-CN/skills/commands/check.md +53 -1
- package/bundled/locales/zh-CN/skills/commands/checkin.md +45 -1
- package/bundled/locales/zh-CN/skills/commands/ci-cd.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/code-review.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/commit.md +56 -1
- package/bundled/locales/zh-CN/skills/commands/config.md +50 -1
- package/bundled/locales/zh-CN/skills/commands/coverage.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/database.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/derive-all.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/derive-atdd.md +35 -1
- package/bundled/locales/zh-CN/skills/commands/derive-bdd.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/derive-tdd.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/derive.md +60 -4
- package/bundled/locales/zh-CN/skills/commands/dev-workflow.md +58 -8
- package/bundled/locales/zh-CN/skills/commands/discover.md +41 -1
- package/bundled/locales/zh-CN/skills/commands/docgen.md +37 -1
- package/bundled/locales/zh-CN/skills/commands/docs.md +136 -5
- package/bundled/locales/zh-CN/skills/commands/durable.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/e2e.md +85 -1
- package/bundled/locales/zh-CN/skills/commands/guide.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/incident.md +5 -4
- package/bundled/locales/zh-CN/skills/commands/init.md +57 -1
- package/bundled/locales/zh-CN/skills/commands/methodology.md +166 -77
- package/bundled/locales/zh-CN/skills/commands/metrics.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/migrate.md +5 -4
- package/bundled/locales/zh-CN/skills/commands/observability.md +48 -3
- package/bundled/locales/zh-CN/skills/commands/pr.md +4 -3
- package/bundled/locales/zh-CN/skills/commands/refactor.md +76 -38
- package/bundled/locales/zh-CN/skills/commands/release.md +82 -1
- package/bundled/locales/zh-CN/skills/commands/requirement.md +40 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-bdd.md +36 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-sdd.md +44 -1
- package/bundled/locales/zh-CN/skills/commands/reverse-tdd.md +42 -1
- package/bundled/locales/zh-CN/skills/commands/reverse.md +43 -1
- package/bundled/locales/zh-CN/skills/commands/runbook.md +50 -3
- package/bundled/locales/zh-CN/skills/commands/scan.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +50 -1
- package/bundled/locales/zh-CN/skills/commands/sdd.md +182 -1
- package/bundled/locales/zh-CN/skills/commands/security.md +3 -2
- package/bundled/locales/zh-CN/skills/commands/slo.md +51 -3
- package/bundled/locales/zh-CN/skills/commands/tdd.md +74 -5
- package/bundled/locales/zh-CN/skills/commands/update.md +70 -8
- package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +4 -4
- package/bundled/locales/zh-CN/skills/commit-standards/conventional-commits.md +45 -44
- package/bundled/locales/zh-CN/skills/commit-standards/guide.md +172 -52
- package/bundled/locales/zh-CN/skills/commit-standards/language-options.md +50 -47
- package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/contract-test-assistant/guide.md +76 -1
- package/bundled/locales/zh-CN/skills/database-assistant/SKILL.md +18 -5
- package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +4 -2
- package/bundled/locales/zh-CN/skills/dev-methodology/create-methodology.md +2 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/runtime.md +2 -0
- package/bundled/locales/zh-CN/skills/docs-generator/SKILL.md +16 -2
- package/bundled/locales/zh-CN/skills/docs-generator/guide.md +8 -7
- package/bundled/locales/zh-CN/skills/documentation-guide/SKILL.md +209 -184
- package/bundled/locales/zh-CN/skills/documentation-guide/documentation-structure.md +73 -72
- package/bundled/locales/zh-CN/skills/documentation-guide/readme-template.md +37 -36
- package/bundled/locales/zh-CN/skills/durable-execution-assistant/SKILL.md +28 -2
- package/bundled/locales/zh-CN/skills/e2e-assistant/SKILL.md +21 -6
- package/bundled/locales/zh-CN/skills/error-code-guide/SKILL.md +76 -95
- package/bundled/locales/zh-CN/skills/git-workflow-guide/SKILL.md +80 -87
- package/bundled/locales/zh-CN/skills/git-workflow-guide/branch-naming.md +44 -43
- package/bundled/locales/zh-CN/skills/git-workflow-guide/git-workflow.md +66 -65
- package/bundled/locales/zh-CN/skills/incident-response-assistant/SKILL.md +31 -13
- package/bundled/locales/zh-CN/skills/metrics-dashboard-assistant/SKILL.md +38 -2
- package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +75 -1
- package/bundled/locales/zh-CN/skills/pr-automation-assistant/SKILL.md +32 -6
- package/bundled/locales/zh-CN/skills/project-discovery/SKILL.md +8 -2
- package/bundled/locales/zh-CN/skills/project-discovery/guide.md +158 -157
- package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +49 -46
- package/bundled/locales/zh-CN/skills/project-structure-guide/language-patterns.md +8 -7
- package/bundled/locales/zh-CN/skills/refactoring-assistant/SKILL.md +22 -2
- package/bundled/locales/zh-CN/skills/refactoring-assistant/guide.md +172 -171
- package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +66 -23
- package/bundled/locales/zh-CN/skills/release-standards/changelog-format.md +42 -41
- package/bundled/locales/zh-CN/skills/release-standards/guide.md +51 -43
- package/bundled/locales/zh-CN/skills/release-standards/release-workflow.md +131 -95
- package/bundled/locales/zh-CN/skills/release-standards/semantic-versioning.md +62 -61
- package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +24 -15
- package/bundled/locales/zh-CN/skills/requirement-assistant/guide.md +88 -79
- package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-checklist.md +128 -127
- package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-writing.md +121 -120
- package/bundled/locales/zh-CN/skills/retrospective-assistant/guide.md +206 -2
- package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/reverse-engineer/bdd-extraction.md +2 -1
- package/bundled/locales/zh-CN/skills/reverse-engineer/guide.md +297 -173
- package/bundled/locales/zh-CN/skills/reverse-engineer/tdd-analysis.md +2 -1
- package/bundled/locales/zh-CN/skills/reverse-engineer/workflow.md +2 -1
- package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +9 -2
- package/bundled/locales/zh-CN/skills/security-assistant/SKILL.md +24 -6
- package/bundled/locales/zh-CN/skills/security-scan-assistant/SKILL.md +34 -10
- package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +2 -2
- package/bundled/locales/zh-CN/skills/spec-driven-dev/guide.md +38 -6
- package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +16 -3
- package/bundled/locales/zh-CN/skills/tdd-assistant/guide.md +217 -156
- package/bundled/locales/zh-CN/skills/tdd-assistant/language-examples.md +727 -82
- package/bundled/locales/zh-CN/skills/tdd-assistant/tdd-workflow.md +396 -214
- package/bundled/locales/zh-CN/skills/test-coverage-assistant/SKILL.md +14 -5
- package/bundled/locales/zh-CN/skills/test-coverage-assistant/guide.md +25 -12
- package/bundled/locales/zh-CN/skills/testing-guide/testing-pyramid.md +99 -98
- package/bundled/locales/zh-CN/skills/testing-guide/testing-theory.md +3 -1
- package/bundled/locales/zh-CN/skills/tools/cline/README.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/copilot/README.md +65 -18
- package/bundled/locales/zh-CN/skills/tools/copilot/copilot-instructions.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/cursor/README.md +2 -1
- package/bundled/locales/zh-CN/skills/tools/windsurf/README.md +2 -1
- package/bundled/locales/zh-CN/skills/workflows/README.md +4 -2
- package/bundled/locales/zh-CN/templates/reverse-spec-template.md +50 -1
- package/bundled/locales/zh-TW/CHANGELOG.md +2282 -1112
- package/bundled/locales/zh-TW/CLAUDE.md +962 -76
- package/bundled/locales/zh-TW/README.md +3 -3
- package/bundled/locales/zh-TW/SECURITY.md +3 -3
- package/bundled/locales/zh-TW/STANDARDS-MAPPING.md +103 -6
- package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +46 -93
- package/bundled/locales/zh-TW/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
- package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +3 -1
- package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +10 -9
- package/bundled/locales/zh-TW/adoption/checklists/minimal.md +6 -2
- package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -4
- package/bundled/locales/zh-TW/ai/MAINTENANCE.md +34 -14
- package/bundled/locales/zh-TW/ai/options/commit-message/traditional-chinese.ai.yaml +48 -40
- package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +56 -10
- package/bundled/locales/zh-TW/core/acceptance-test-driven-development.md +2 -1
- package/bundled/locales/zh-TW/core/accessibility-standards.md +895 -46
- package/bundled/locales/zh-TW/core/adr-standards.md +2 -1
- package/bundled/locales/zh-TW/core/agent-communication-protocol.md +2 -1
- package/bundled/locales/zh-TW/core/agent-dispatch.md +102 -33
- package/bundled/locales/zh-TW/core/ai-agreement-standards.md +58 -41
- package/bundled/locales/zh-TW/core/ai-command-behavior.md +2 -1
- package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +306 -67
- package/bundled/locales/zh-TW/core/ai-instruction-standards.md +16 -13
- package/bundled/locales/zh-TW/core/ai-response-navigation.md +3 -3
- package/bundled/locales/zh-TW/core/alerting-standards.md +257 -35
- package/bundled/locales/zh-TW/core/anti-hallucination.md +169 -40
- package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +2 -1
- package/bundled/locales/zh-TW/core/api-design-standards.md +2 -1
- package/bundled/locales/zh-TW/core/behavior-driven-development.md +3 -17
- package/bundled/locales/zh-TW/core/branch-completion.md +130 -34
- package/bundled/locales/zh-TW/core/capability-declaration.md +41 -79
- package/bundled/locales/zh-TW/core/change-batching-standards.md +2 -1
- package/bundled/locales/zh-TW/core/changelog-standards.md +14 -9
- package/bundled/locales/zh-TW/core/chaos-engineering-standards.md +138 -36
- package/bundled/locales/zh-TW/core/checkin-standards.md +84 -26
- package/bundled/locales/zh-TW/core/circuit-breaker.md +48 -87
- package/bundled/locales/zh-TW/core/code-review-checklist.md +19 -7
- package/bundled/locales/zh-TW/core/commit-message-guide.md +218 -87
- package/bundled/locales/zh-TW/core/containerization-standards.md +259 -57
- package/bundled/locales/zh-TW/core/context-aware-loading.md +121 -27
- package/bundled/locales/zh-TW/core/database-standards.md +2 -1
- package/bundled/locales/zh-TW/core/deprecation-standards.md +139 -37
- package/bundled/locales/zh-TW/core/design-document-standards.md +265 -55
- package/bundled/locales/zh-TW/core/developer-memory.md +102 -12
- package/bundled/locales/zh-TW/core/documentation-lifecycle.md +2 -1
- package/bundled/locales/zh-TW/core/documentation-structure.md +17 -8
- package/bundled/locales/zh-TW/core/dual-phase-output.md +28 -90
- package/bundled/locales/zh-TW/core/environment-standards.md +250 -72
- package/bundled/locales/zh-TW/core/error-code-standards.md +17 -6
- package/bundled/locales/zh-TW/core/estimation-standards.md +177 -44
- package/bundled/locales/zh-TW/core/execution-history.md +2 -1
- package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +59 -117
- package/bundled/locales/zh-TW/core/feature-flag-standards.md +202 -57
- package/bundled/locales/zh-TW/core/forward-derivation-standards.md +592 -133
- package/bundled/locales/zh-TW/core/frontend-design-standards.md +120 -8
- package/bundled/locales/zh-TW/core/git-workflow.md +197 -37
- package/bundled/locales/zh-TW/core/git-worktree.md +79 -49
- package/bundled/locales/zh-TW/core/guides/anti-hallucination-guide.md +234 -487
- package/bundled/locales/zh-TW/core/guides/file-placement-guide.md +86 -2
- package/bundled/locales/zh-TW/core/guides/git-workflow-guide.md +411 -464
- package/bundled/locales/zh-TW/core/guides/performance-guide.md +2 -0
- package/bundled/locales/zh-TW/core/guides/refactoring-guide.md +237 -484
- package/bundled/locales/zh-TW/core/guides/security-guide.md +2 -0
- package/bundled/locales/zh-TW/core/health-check-standards.md +46 -104
- package/bundled/locales/zh-TW/core/immutability-first.md +45 -85
- package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +2 -1
- package/bundled/locales/zh-TW/core/knowledge-transfer-standards.md +103 -40
- package/bundled/locales/zh-TW/core/observability-standards.md +284 -40
- package/bundled/locales/zh-TW/core/performance-standards.md +387 -86
- package/bundled/locales/zh-TW/core/pipeline-integration-standards.md +2 -1
- package/bundled/locales/zh-TW/core/postmortem-standards.md +367 -36
- package/bundled/locales/zh-TW/core/privacy-standards.md +153 -46
- package/bundled/locales/zh-TW/core/project-context-memory.md +210 -31
- package/bundled/locales/zh-TW/core/project-structure.md +240 -19
- package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +54 -114
- package/bundled/locales/zh-TW/core/refactoring-standards.md +153 -48
- package/bundled/locales/zh-TW/core/requirement-engineering.md +8 -37
- package/bundled/locales/zh-TW/core/retrospective-standards.md +127 -7
- package/bundled/locales/zh-TW/core/retry-standards.md +41 -105
- package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +5 -1
- package/bundled/locales/zh-TW/core/runbook-standards.md +296 -23
- package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
- package/bundled/locales/zh-TW/core/security-decision.md +43 -84
- package/bundled/locales/zh-TW/core/security-standards.md +204 -25
- package/bundled/locales/zh-TW/core/self-review-protocol.md +2 -1
- package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +103 -69
- package/bundled/locales/zh-TW/core/slo-standards.md +301 -49
- package/bundled/locales/zh-TW/core/spec-driven-development.md +36 -7
- package/bundled/locales/zh-TW/core/standard-admission-criteria.md +22 -28
- package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +40 -48
- package/bundled/locales/zh-TW/core/structured-task-definition.md +2 -1
- package/bundled/locales/zh-TW/core/supply-chain-security-standards.md +137 -10
- package/bundled/locales/zh-TW/core/systematic-debugging.md +94 -38
- package/bundled/locales/zh-TW/core/tech-debt-standards.md +170 -54
- package/bundled/locales/zh-TW/core/test-completeness-dimensions.md +101 -12
- package/bundled/locales/zh-TW/core/test-data-standards.md +245 -23
- package/bundled/locales/zh-TW/core/test-driven-development.md +4 -1
- package/bundled/locales/zh-TW/core/test-governance.md +92 -32
- package/bundled/locales/zh-TW/core/testing-standards.md +61 -14
- package/bundled/locales/zh-TW/core/timeout-standards.md +45 -85
- package/bundled/locales/zh-TW/core/token-budget.md +41 -112
- package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +28 -16
- package/bundled/locales/zh-TW/core/verification-evidence.md +2 -1
- package/bundled/locales/zh-TW/core/versioning.md +6 -2
- package/bundled/locales/zh-TW/core/virtual-organization-standards.md +42 -36
- package/bundled/locales/zh-TW/core/workflow-enforcement.md +2 -1
- package/bundled/locales/zh-TW/core/workflow-state-protocol.md +2 -1
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +2 -1
- package/bundled/locales/zh-TW/docs/CLI-FLOW.md +2 -1
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +12 -3
- package/bundled/locales/zh-TW/docs/DEV-WORKFLOW-MAPPING.md +2 -1
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +8 -6
- package/bundled/locales/zh-TW/docs/STANDARDS-REFERENCE.md +2 -1
- package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +2 -1
- package/bundled/locales/zh-TW/docs/USER-MANUAL.md +9 -1
- package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +4 -1
- package/bundled/locales/zh-TW/docs/specs/system/memory-adoption-strategy.md +2 -0
- package/bundled/locales/zh-TW/docs/user/FAQ.md +2 -0
- package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +2 -0
- package/bundled/locales/zh-TW/docs/user/GLOSSARY.md +2 -0
- package/bundled/locales/zh-TW/docs/user/README.md +2 -0
- package/bundled/locales/zh-TW/docs/user/TROUBLESHOOTING.md +2 -0
- package/bundled/locales/zh-TW/integrations/claude-code/README.md +2 -1
- package/bundled/locales/zh-TW/integrations/codex/AGENTS.md +136 -2
- package/bundled/locales/zh-TW/integrations/codex/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md +59 -1
- package/bundled/locales/zh-TW/integrations/gemini-cli/README.md +8 -1
- package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
- package/bundled/locales/zh-TW/integrations/github-copilot/README.md +9 -3
- package/bundled/locales/zh-TW/integrations/github-copilot/copilot-instructions.md +146 -12
- package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md +7 -1
- package/bundled/locales/zh-TW/integrations/google-antigravity/AGENTS.md +110 -3
- package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/opencode/AGENTS.md +140 -2
- package/bundled/locales/zh-TW/integrations/opencode/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/opencode/skills-mapping.md +8 -2
- package/bundled/locales/zh-TW/integrations/openspec/AGENTS.md +46 -1
- package/bundled/locales/zh-TW/integrations/openspec/README.md +7 -1
- package/bundled/locales/zh-TW/integrations/spec-kit/AGENTS.md +20 -2
- package/bundled/locales/zh-TW/integrations/spec-kit/README.md +7 -1
- package/bundled/locales/zh-TW/methodologies/guides/tdd-guide.md +584 -475
- package/bundled/locales/zh-TW/options/changelog/auto-generated.md +2 -0
- package/bundled/locales/zh-TW/options/changelog/keep-a-changelog.md +2 -0
- package/bundled/locales/zh-TW/options/code-review/automated-review.md +2 -0
- package/bundled/locales/zh-TW/options/code-review/pair-programming.md +2 -0
- package/bundled/locales/zh-TW/options/commit-message/bilingual.md +93 -5
- package/bundled/locales/zh-TW/options/commit-message/english.md +118 -1
- package/bundled/locales/zh-TW/options/commit-message/traditional-chinese.md +82 -1
- package/bundled/locales/zh-TW/options/documentation/api-docs.md +2 -0
- package/bundled/locales/zh-TW/options/documentation/markdown-docs.md +2 -0
- package/bundled/locales/zh-TW/options/documentation/wiki-style.md +2 -0
- package/bundled/locales/zh-TW/options/git-workflow/gitflow.md +99 -71
- package/bundled/locales/zh-TW/options/git-workflow/github-flow.md +68 -50
- package/bundled/locales/zh-TW/options/git-workflow/merge-commit.md +131 -20
- package/bundled/locales/zh-TW/options/git-workflow/rebase-ff.md +142 -27
- package/bundled/locales/zh-TW/options/git-workflow/squash-merge.md +100 -15
- package/bundled/locales/zh-TW/options/git-workflow/trunk-based.md +103 -56
- package/bundled/locales/zh-TW/options/project-structure/dotnet.md +233 -14
- package/bundled/locales/zh-TW/options/project-structure/go.md +270 -12
- package/bundled/locales/zh-TW/options/project-structure/java.md +235 -15
- package/bundled/locales/zh-TW/options/project-structure/kotlin.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/nodejs.md +136 -19
- package/bundled/locales/zh-TW/options/project-structure/php.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/python.md +177 -19
- package/bundled/locales/zh-TW/options/project-structure/ruby.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/rust.md +2 -0
- package/bundled/locales/zh-TW/options/project-structure/swift.md +2 -0
- package/bundled/locales/zh-TW/options/testing/contract-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/e2e-testing.md +182 -21
- package/bundled/locales/zh-TW/options/testing/industry-pyramid.md +2 -0
- package/bundled/locales/zh-TW/options/testing/integration-testing.md +134 -22
- package/bundled/locales/zh-TW/options/testing/istqb-framework.md +2 -0
- package/bundled/locales/zh-TW/options/testing/performance-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/security-testing.md +2 -0
- package/bundled/locales/zh-TW/options/testing/system-testing.md +175 -1
- package/bundled/locales/zh-TW/options/testing/unit-testing.md +123 -9
- package/bundled/locales/zh-TW/skills/CONTRIBUTING.template.md +3 -2
- package/bundled/locales/zh-TW/skills/INTEGRATION-GUIDE.md +2 -1
- package/bundled/locales/zh-TW/skills/README.md +2 -1
- package/bundled/locales/zh-TW/skills/_shared/README.md +2 -1
- package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md +15 -4
- package/bundled/locales/zh-TW/skills/adr-assistant/guide.md +123 -3
- package/bundled/locales/zh-TW/skills/agents/README.md +99 -1
- package/bundled/locales/zh-TW/skills/agents/code-architect.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/doc-writer.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/reviewer.md +3 -1
- package/bundled/locales/zh-TW/skills/agents/spec-analyst.md +2 -0
- package/bundled/locales/zh-TW/skills/agents/test-specialist.md +2 -0
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +48 -37
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/anti-hallucination.md +22 -2
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/certainty-labels.md +29 -3
- package/bundled/locales/zh-TW/skills/ai-friendly-architecture/SKILL.md +23 -36
- package/bundled/locales/zh-TW/skills/ai-instruction-standards/SKILL.md +12 -36
- package/bundled/locales/zh-TW/skills/api-design-assistant/SKILL.md +21 -5
- package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +40 -15
- package/bundled/locales/zh-TW/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/atdd-workflow.md +98 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/guide.md +24 -8
- package/bundled/locales/zh-TW/skills/audit-assistant/SKILL.md +8 -2
- package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +29 -6
- package/bundled/locales/zh-TW/skills/bdd-assistant/bdd-workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/bdd-assistant/gherkin-guide.md +2 -1
- package/bundled/locales/zh-TW/skills/bdd-assistant/guide.md +9 -8
- package/bundled/locales/zh-TW/skills/changelog-guide/SKILL.md +12 -3
- package/bundled/locales/zh-TW/skills/changelog-guide/guide.md +11 -7
- package/bundled/locales/zh-TW/skills/checkin-assistant/SKILL.md +19 -3
- package/bundled/locales/zh-TW/skills/checkin-assistant/guide.md +5 -3
- package/bundled/locales/zh-TW/skills/ci-cd-assistant/SKILL.md +35 -16
- package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +19 -2
- package/bundled/locales/zh-TW/skills/code-review-assistant/checkin-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/code-review-assistant/guide.md +81 -6
- package/bundled/locales/zh-TW/skills/code-review-assistant/review-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/ac-coverage.md +47 -2
- package/bundled/locales/zh-TW/skills/commands/api-design.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/atdd.md +80 -10
- package/bundled/locales/zh-TW/skills/commands/audit.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/bdd.md +114 -16
- package/bundled/locales/zh-TW/skills/commands/changelog.md +45 -9
- package/bundled/locales/zh-TW/skills/commands/check.md +74 -21
- package/bundled/locales/zh-TW/skills/commands/checkin.md +56 -11
- package/bundled/locales/zh-TW/skills/commands/ci-cd.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/code-review.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/commit.md +58 -4
- package/bundled/locales/zh-TW/skills/commands/config.md +52 -4
- package/bundled/locales/zh-TW/skills/commands/coverage.md +45 -4
- package/bundled/locales/zh-TW/skills/commands/database.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/derive-all.md +44 -2
- package/bundled/locales/zh-TW/skills/commands/derive-atdd.md +37 -2
- package/bundled/locales/zh-TW/skills/commands/derive-bdd.md +44 -3
- package/bundled/locales/zh-TW/skills/commands/derive-tdd.md +45 -3
- package/bundled/locales/zh-TW/skills/commands/derive.md +62 -5
- package/bundled/locales/zh-TW/skills/commands/dev-workflow.md +60 -9
- package/bundled/locales/zh-TW/skills/commands/discover.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/docgen.md +39 -2
- package/bundled/locales/zh-TW/skills/commands/docs.md +139 -7
- package/bundled/locales/zh-TW/skills/commands/durable.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/e2e.md +86 -3
- package/bundled/locales/zh-TW/skills/commands/guide.md +4 -2
- package/bundled/locales/zh-TW/skills/commands/incident.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/init.md +72 -15
- package/bundled/locales/zh-TW/skills/commands/methodology.md +117 -28
- package/bundled/locales/zh-TW/skills/commands/metrics.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/migrate.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/observability.md +45 -2
- package/bundled/locales/zh-TW/skills/commands/pr.md +2 -1
- package/bundled/locales/zh-TW/skills/commands/refactor.md +54 -13
- package/bundled/locales/zh-TW/skills/commands/release.md +83 -2
- package/bundled/locales/zh-TW/skills/commands/requirement.md +41 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-bdd.md +37 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-sdd.md +45 -2
- package/bundled/locales/zh-TW/skills/commands/reverse-tdd.md +43 -2
- package/bundled/locales/zh-TW/skills/commands/reverse.md +44 -2
- package/bundled/locales/zh-TW/skills/commands/runbook.md +47 -2
- package/bundled/locales/zh-TW/skills/commands/scan.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/sdd-retro.md +52 -3
- package/bundled/locales/zh-TW/skills/commands/sdd.md +209 -28
- package/bundled/locales/zh-TW/skills/commands/security.md +3 -2
- package/bundled/locales/zh-TW/skills/commands/slo.md +48 -2
- package/bundled/locales/zh-TW/skills/commands/tdd.md +71 -2
- package/bundled/locales/zh-TW/skills/commands/update.md +64 -2
- package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -2
- package/bundled/locales/zh-TW/skills/commit-standards/conventional-commits.md +2 -1
- package/bundled/locales/zh-TW/skills/commit-standards/guide.md +137 -17
- package/bundled/locales/zh-TW/skills/commit-standards/language-options.md +21 -18
- package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -2
- package/bundled/locales/zh-TW/skills/contract-test-assistant/guide.md +81 -1
- package/bundled/locales/zh-TW/skills/database-assistant/SKILL.md +21 -5
- package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +4 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/create-methodology.md +2 -0
- package/bundled/locales/zh-TW/skills/dev-methodology/runtime.md +2 -0
- package/bundled/locales/zh-TW/skills/docs-generator/SKILL.md +19 -2
- package/bundled/locales/zh-TW/skills/docs-generator/guide.md +4 -3
- package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md +67 -42
- package/bundled/locales/zh-TW/skills/documentation-guide/documentation-structure.md +2 -1
- package/bundled/locales/zh-TW/skills/documentation-guide/readme-template.md +2 -1
- package/bundled/locales/zh-TW/skills/durable-execution-assistant/SKILL.md +32 -3
- package/bundled/locales/zh-TW/skills/e2e-assistant/SKILL.md +25 -7
- package/bundled/locales/zh-TW/skills/error-code-guide/SKILL.md +17 -34
- package/bundled/locales/zh-TW/skills/git-workflow-guide/SKILL.md +33 -38
- package/bundled/locales/zh-TW/skills/git-workflow-guide/branch-naming.md +2 -1
- package/bundled/locales/zh-TW/skills/git-workflow-guide/git-workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/incident-response-assistant/SKILL.md +35 -14
- package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md +2 -14
- package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +6 -2
- package/bundled/locales/zh-TW/skills/metrics-dashboard-assistant/SKILL.md +42 -3
- package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +85 -18
- package/bundled/locales/zh-TW/skills/pr-automation-assistant/SKILL.md +27 -3
- package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +11 -3
- package/bundled/locales/zh-TW/skills/project-discovery/guide.md +5 -3
- package/bundled/locales/zh-TW/skills/project-discovery/workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +19 -16
- package/bundled/locales/zh-TW/skills/project-structure-guide/language-patterns.md +2 -1
- package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md +26 -3
- package/bundled/locales/zh-TW/skills/refactoring-assistant/guide.md +4 -2
- package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +91 -45
- package/bundled/locales/zh-TW/skills/release-standards/changelog-format.md +4 -3
- package/bundled/locales/zh-TW/skills/release-standards/guide.md +14 -5
- package/bundled/locales/zh-TW/skills/release-standards/release-workflow.md +5 -1
- package/bundled/locales/zh-TW/skills/release-standards/semantic-versioning.md +2 -1
- package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +15 -6
- package/bundled/locales/zh-TW/skills/requirement-assistant/guide.md +18 -8
- package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-checklist.md +2 -1
- package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-writing.md +2 -1
- package/bundled/locales/zh-TW/skills/retrospective-assistant/guide.md +200 -6
- package/bundled/locales/zh-TW/skills/reverse-engineer/bdd-extraction.md +2 -1
- package/bundled/locales/zh-TW/skills/reverse-engineer/guide.md +161 -36
- package/bundled/locales/zh-TW/skills/reverse-engineer/tdd-analysis.md +2 -1
- package/bundled/locales/zh-TW/skills/reverse-engineer/workflow.md +2 -1
- package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +9 -1
- package/bundled/locales/zh-TW/skills/security-assistant/SKILL.md +25 -5
- package/bundled/locales/zh-TW/skills/security-scan-assistant/SKILL.md +34 -8
- package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md +3 -21
- package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +3 -1
- package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/spec-driven-dev/guide.md +35 -2
- package/bundled/locales/zh-TW/skills/sweep/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +10 -2
- package/bundled/locales/zh-TW/skills/tdd-assistant/guide.md +68 -9
- package/bundled/locales/zh-TW/skills/tdd-assistant/language-examples.md +693 -47
- package/bundled/locales/zh-TW/skills/tdd-assistant/tdd-workflow.md +183 -1
- package/bundled/locales/zh-TW/skills/test-coverage-assistant/SKILL.md +15 -5
- package/bundled/locales/zh-TW/skills/test-coverage-assistant/guide.md +26 -13
- package/bundled/locales/zh-TW/skills/testing-guide/testing-pyramid.md +2 -1
- package/bundled/locales/zh-TW/skills/testing-guide/testing-theory.md +3 -1
- package/bundled/locales/zh-TW/skills/tools/cline/README.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/copilot/README.md +65 -18
- package/bundled/locales/zh-TW/skills/tools/copilot/copilot-instructions.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/cursor/README.md +2 -1
- package/bundled/locales/zh-TW/skills/tools/windsurf/README.md +2 -1
- package/bundled/locales/zh-TW/skills/workflows/README.md +11 -9
- package/bundled/locales/zh-TW/templates/reverse-spec-template.md +50 -1
- package/bundled/skills/.claude-plugin/plugin.json +71 -0
- package/bundled/skills/commit-standards/SKILL.md +2 -2
- package/bundled/skills/commit-standards/guide.md +3 -2
- package/bundled/skills/commit-standards/language-options.md +19 -17
- package/package.json +2 -2
- package/src/commands/audit.js +28 -1
- package/src/commands/check.js +72 -3
- package/src/commands/compile.js +37 -4
- package/src/commands/config.js +49 -24
- package/src/commands/init.js +78 -30
- package/src/commands/open-work.js +6 -2
- package/src/commands/release-messages.js +228 -0
- package/src/commands/release.js +127 -68
- package/src/commands/run-intent.js +11 -0
- package/src/commands/spec.js +4 -2
- package/src/commands/update.js +173 -20
- package/src/compilers/claude-code-compiler.js +9 -1
- package/src/config/ai-agent-paths.js +14 -1
- package/src/core/installed-formats.js +15 -0
- package/src/core/open-work-config.js +20 -1
- package/src/core/project-config.js +55 -0
- package/src/i18n/messages.js +106 -2
- package/src/installers/hooks-installer.js +1 -1
- package/src/installers/manifest-installer.js +1 -1
- package/src/installers/skills-installer.js +1 -1
- package/src/installers/standards-installer.js +3 -1
- package/src/mcp/server.js +9 -3
- package/src/prompts/init.js +26 -22
- package/src/reconciler/actual-state-scanner.js +2 -8
- package/src/reconciler/backup-locations.js +5 -0
- package/src/reconciler/backup-manager.js +19 -11
- package/src/reconciler/desired-state-calculator.js +89 -57
- package/src/reconciler/plan-executor.js +101 -8
- package/src/reconciler/recorded-versions.js +49 -0
- package/src/reconciler/relative-path.js +23 -0
- package/src/uninstallers/hook-uninstaller.js +9 -1
- package/src/uninstallers/skills-uninstaller.js +22 -3
- package/src/utils/available-standards-report.js +25 -4
- package/src/utils/available-standards.js +13 -3
- package/src/utils/build-manifest.js +1 -1
- package/src/utils/commit-message-judge.js +60 -13
- package/src/utils/friction-detector.js +23 -11
- package/src/utils/git-hooks.js +106 -4
- package/src/utils/integration-generator.js +95 -67
- package/src/utils/legacy-hook-migration.js +121 -2
- package/src/utils/open-work-tracking.mjs +105 -16
- package/src/utils/sdd-header.js +16 -4
- package/src/utils/skills-installer.js +2 -1
- package/src/utils/spinner.js +14 -4
- package/src/utils/standard-validator.js +3 -2
- package/standards-registry.json +10 -8
- package/bundled/locales/zh-TW/core/guides/testing-guide.md +0 -2280
|
@@ -1,24 +1,28 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/versioning.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
|
|
3
|
+
source_version: 1.5.0
|
|
4
|
+
translation_version: 1.5.0
|
|
5
|
+
last_synced: 2026-10-16
|
|
6
|
+
source_hash: 5c995171e2a4
|
|
7
|
+
status: current
|
|
7
8
|
---
|
|
8
9
|
|
|
9
|
-
> **语言**: [English](../../../core/versioning.md) | [简体中文](../../zh-TW/core/versioning.md) | 简体中文
|
|
10
|
-
|
|
11
10
|
# 语义化版本标准
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
> **语言**: [English](../../../core/versioning.md) | [繁體中文](../../zh-TW/core/versioning.md) | 简体中文
|
|
13
|
+
|
|
14
|
+
**版本**: 1.5.0
|
|
15
|
+
**最后更新**: 2026-07-01
|
|
16
|
+
**适用范围**: 所有具有版本发布的软件项目
|
|
17
|
+
**范围**: universal
|
|
18
|
+
**行业标准**: Semantic Versioning 2.0.0
|
|
19
|
+
**参考**: [semver.org](https://semver.org/)
|
|
16
20
|
|
|
17
21
|
---
|
|
18
22
|
|
|
19
23
|
## 目的
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
本标准定义如何使用语义化版本(SemVer)对软件发布进行版本控制,以便向用户和维护者清晰地传达变更。
|
|
22
26
|
|
|
23
27
|
---
|
|
24
28
|
|
|
@@ -27,20 +31,20 @@ status: stale
|
|
|
27
31
|
```
|
|
28
32
|
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
Examples:
|
|
31
35
|
2.3.1
|
|
32
36
|
1.0.0-alpha.1
|
|
33
37
|
3.2.0-beta.2+20250112
|
|
34
38
|
```
|
|
35
39
|
|
|
36
|
-
###
|
|
40
|
+
### 组件
|
|
37
41
|
|
|
38
|
-
|
|
|
39
|
-
|
|
42
|
+
| 组件 | 用途 | 递增时机 |
|
|
43
|
+
|-----------|---------|-------------------|
|
|
40
44
|
| **MAJOR** | 破坏性变更 | 不兼容的 API 变更 |
|
|
41
45
|
| **MINOR** | 新功能 | 向后兼容的功能 |
|
|
42
|
-
| **PATCH** | 错误修复 |
|
|
43
|
-
| **PRERELEASE** |
|
|
46
|
+
| **PATCH** | 错误修复 | 向后兼容的错误修复 |
|
|
47
|
+
| **PRERELEASE** | 预发布标识符 | Alpha、beta、rc 版本 |
|
|
44
48
|
| **BUILD** | 构建元数据 | 构建号、提交哈希 |
|
|
45
49
|
|
|
46
50
|
---
|
|
@@ -55,14 +59,40 @@ MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
|
|
|
55
59
|
- 重大架构变更
|
|
56
60
|
- 不兼容的行为变更
|
|
57
61
|
|
|
62
|
+
**示例**:
|
|
63
|
+
```
|
|
64
|
+
1.9.5 → 2.0.0 # Remove deprecated API
|
|
65
|
+
3.2.1 → 4.0.0 # Change return type of public method
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**指南**:
|
|
69
|
+
- 将 MINOR 和 PATCH 重置为 0
|
|
70
|
+
- 编写迁移指南文档
|
|
71
|
+
- 在先前的 MINOR 版本中提供弃用警告
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
58
75
|
### MINOR 版本 (x.Y.0)
|
|
59
76
|
|
|
60
77
|
**递增时机**:
|
|
61
78
|
- 添加新功能(向后兼容)
|
|
62
|
-
-
|
|
79
|
+
- 弃用功能(不移除)
|
|
63
80
|
- 实质性内部改进
|
|
64
81
|
- 新的公开 API
|
|
65
82
|
|
|
83
|
+
**示例**:
|
|
84
|
+
```
|
|
85
|
+
2.3.5 → 2.4.0 # Add new API endpoint
|
|
86
|
+
1.12.0 → 1.13.0 # Add optional parameter to existing function
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**指南**:
|
|
90
|
+
- 将 PATCH 重置为 0
|
|
91
|
+
- 现有功能保持不变
|
|
92
|
+
- 新功能为可选启用(opt-in)
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
66
96
|
### PATCH 版本 (x.y.Z)
|
|
67
97
|
|
|
68
98
|
**递增时机**:
|
|
@@ -71,104 +101,738 @@ MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
|
|
|
71
101
|
- 文档更正
|
|
72
102
|
- 内部重构(无 API 变更)
|
|
73
103
|
|
|
104
|
+
**示例**:
|
|
105
|
+
```
|
|
106
|
+
3.1.2 → 3.1.3 # Fix null pointer exception
|
|
107
|
+
2.0.0 → 2.0.1 # Security vulnerability patch
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**指南**:
|
|
111
|
+
- 无新功能
|
|
112
|
+
- 无 API 变更
|
|
113
|
+
- 可立即安全更新
|
|
114
|
+
|
|
74
115
|
---
|
|
75
116
|
|
|
76
|
-
##
|
|
117
|
+
## 预发布版本
|
|
118
|
+
|
|
119
|
+
格式: `MAJOR.MINOR.PATCH-PRERELEASE`
|
|
120
|
+
|
|
121
|
+
### 预发布标识符
|
|
122
|
+
|
|
123
|
+
| 标识符 | 用途 | 稳定性 | 受众 |
|
|
124
|
+
|------------|---------|-----------|----------|
|
|
125
|
+
| `alpha` | 早期测试 | 不稳定 | 内部团队 |
|
|
126
|
+
| `beta` | 功能完备 | 基本稳定 | 早期采用者 |
|
|
127
|
+
| `rc` (release candidate) | 最终测试 | 稳定 | Beta 测试者 |
|
|
128
|
+
|
|
129
|
+
### 示例
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
1.0.0-alpha.1 # First alpha release
|
|
133
|
+
1.0.0-alpha.2 # Second alpha release
|
|
134
|
+
1.0.0-beta.1 # First beta release
|
|
135
|
+
1.0.0-beta.2 # Second beta release
|
|
136
|
+
1.0.0-rc.1 # Release candidate 1
|
|
137
|
+
1.0.0 # Stable release
|
|
138
|
+
```
|
|
77
139
|
|
|
78
|
-
|
|
79
|
-
|------|------|------|------|
|
|
80
|
-
| URL 路径 | `/api/v1/users` | 清晰、易于路由 | URL 污染 |
|
|
81
|
-
| 查询参数 | `/api/users?version=1` | 可选版本 | 缓存问题 |
|
|
82
|
-
| 标头 | `Accept: application/vnd.api.v1+json` | URL 干净 | 不可见 |
|
|
140
|
+
### 排序
|
|
83
141
|
|
|
84
|
-
|
|
142
|
+
预发布版本按字典序排序:
|
|
143
|
+
```
|
|
144
|
+
1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
|
|
145
|
+
```
|
|
85
146
|
|
|
86
147
|
---
|
|
87
148
|
|
|
88
|
-
##
|
|
149
|
+
## 构建元数据
|
|
150
|
+
|
|
151
|
+
格式: `MAJOR.MINOR.PATCH+BUILD`
|
|
152
|
+
|
|
153
|
+
### 示例
|
|
89
154
|
|
|
90
155
|
```
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
156
|
+
1.0.0+20250112 # Date-based build
|
|
157
|
+
2.3.1+001 # Sequential build number
|
|
158
|
+
3.0.0+sha.5114f85 # Git commit hash
|
|
159
|
+
1.2.0-beta.1+exp.sha.5114f85 # Combined pre-release and build
|
|
94
160
|
```
|
|
95
161
|
|
|
96
|
-
###
|
|
162
|
+
### 指南
|
|
163
|
+
|
|
164
|
+
- 构建元数据不应(SHOULD NOT)影响版本优先级
|
|
165
|
+
- 用于 CI/CD 跟踪
|
|
166
|
+
- 包含在构件中,但不用于版本比较
|
|
97
167
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
| 内部 API | 1 个次要版本 |
|
|
101
|
-
| 合作伙伴 API | 2 个次要版本 + 3 个月 |
|
|
102
|
-
| 公开 API | 2 个次要版本 + 6 个月 |
|
|
103
|
-
| 关键基础设施 | 最少 1 年 |
|
|
168
|
+
> **关键:构建元数据绝不能(MUST NOT)用作部署鉴别器。**
|
|
169
|
+
> 由于工具在优先级与比较中会忽略 `+build`(见上文),仅在构建元数据上存在差异的两个构建(`1.2.3+abc` 与 `1.2.3+def`)**对版本比较工具而言是无法区分的**——回滚目标与 `semver` 比较会将它们视为同一个发布版本。使用 `+sha` 来区分行为不同的已部署构建属于绕过治理:版本将不再是用于 changelog / SBOM / 审计 / 回滚 / SLA / CVE 范围的关联键。交付的变更必须(MUST)获得真实的版本号递增或具有唯一且不可变的构件标识(参见下方的**部署版本标识**)——`+sha` **绝非**替代品。
|
|
104
170
|
|
|
105
171
|
---
|
|
106
172
|
|
|
107
|
-
##
|
|
173
|
+
## 部署版本标识
|
|
174
|
+
|
|
175
|
+
> 来源:一种常见的故障模式——多个行为不同的热修复构建部署在同一个 `X.Y.Z` 下,仅能通过 `+sha` 进行区分,导致回答“生产环境中运行的是哪个构建 / 修复 X 到底部署了没有?”变成了提交考古。
|
|
176
|
+
|
|
177
|
+
本节规范**可部署单元**的标识——无论该单元对于项目而言是什么(容器镜像、tar 包、发布的软件包)。它是对下文[发布流程](#release-process)的补充,后者描述了一种具体的单机发布流程;此处的标识规则无论采用何种部署机制均适用。
|
|
178
|
+
|
|
179
|
+
### 核心不变量
|
|
180
|
+
|
|
181
|
+
**每个不同的可部署构建产物必须携带唯一且不可变的版本标识(正式版本号 + 提交 sha)。**部署、*晋级*或*回滚***已有**产物绝不能改变其标识。
|
|
182
|
+
|
|
183
|
+
- **锚定于产物,而非部署动作。**新的构建(不同的源码或依赖项)⇒ 新版本。在不同环境之间流转(staging → prod,一次构建多次部署)、重新部署(蓝绿 / 金丝雀)或回滚的*同一个*构建属于**同一个**产物,并保持其标识——绝不能对其重新递增版本号。在晋级/回滚时重新递增版本号会导致版本号与实际运行的内容不符。(当回滚恢复先前的产物时,它恢复的是该产物的原始标识——而不是生成一个新的标识。)
|
|
184
|
+
- **绝不要在同一个 `X.Y.Z` 下部署两个不同的构建。**
|
|
185
|
+
|
|
186
|
+
### 通过自动化强制执行,而非仅靠纪律
|
|
187
|
+
|
|
188
|
+
该不变量应当通过自动化机制而非仅凭人工纪律来强制执行——上述故障模式*正是*因为遗漏了手动递增版本。以下任一方式均可满足要求:
|
|
108
189
|
|
|
109
|
-
|
|
110
|
-
- [
|
|
111
|
-
-
|
|
112
|
-
- [ ] 添加必填请求字段
|
|
113
|
-
- [ ] 更改响应字段类型
|
|
114
|
-
- [ ] 更改错误码含义
|
|
190
|
+
- **提交驱动的发布自动化**(`semantic-release` / `standard-version`,参见[自动化工具](#automation-tools)):在 CI 中根据提交历史推导并递增版本号,从而避免人工遗忘递增。
|
|
191
|
+
- **基于 Git 拓扑深度的版本化**(MinVer / Nerdbank.GitVersioning / GitVersion):版本号派生自 git 提交拓扑结构,因此从结构上杜绝了冲突的可能。推荐用于多语言 / .NET / JVM 项目(自动化工具一节主要针对 Node)——参见[自动化工具](#automation-tools)下的 git-height 小节。注意单一代码库(monorepo)和 squash-merge 工作流的注意事项。
|
|
192
|
+
- **CI 唯一性关卡**:如果计算出的版本已作为 git 标签存在或已存在于注册表中,则使发布失败。
|
|
115
193
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
194
|
+
### 不可变产物(交叉引用)
|
|
195
|
+
|
|
196
|
+
唯一的*编号*是必要的,但并不充分——*产物*本身也必须是不可变且基于内容寻址的(例如,通过 digest 而非可变标签引用的容器镜像)。产物级别的具体要求——将部署固定到内容地址并禁止复用标签/版本——**属于 container-image-standards 的范畴**,并在其中加以规定;本标准仅要求版本标识本身保持唯一且不可变。
|
|
197
|
+
|
|
198
|
+
### 构建标识可观测(要求)
|
|
199
|
+
|
|
200
|
+
**已部署的服务必须通过可查询的端点**(专用的 `/version`,或嵌入在 `/health` 中)**暴露其构建标识——`version + commit sha + build time`**,以便运维人员无需检查二进制文件或进行提交考古即可确切了解当前运行的内容。基本原理:手动版本号可能会发生冲突(如上所述),因此运维需要借由 `sha` 来区分在同一个 `X.Y.Z` 下发布的两个构建。
|
|
201
|
+
|
|
202
|
+
要求:
|
|
203
|
+
|
|
204
|
+
- 暴露的 `sha` 必须与已部署产物的 sha 一致——它是**可验证的,而非自我报告的**(从构建中派生,切勿手动输入)。
|
|
205
|
+
- 端点应当进行访问控制;公开的构建标识端点会泄露内部提交标识。
|
|
206
|
+
- 发布后验证必须断言返回的 sha 等于已部署产物的 sha(参见[阶段 5:发布后验证](#phase-5-post-release-verification)),而不仅仅验证版本号是否正确。
|
|
207
|
+
|
|
208
|
+
这是部署 / 可观测性关注点:具体的验证*机制*(如何抓取端点以及如何将断言接入关卡)**属于 deployment-standards 的范畴**(将在其中进行规定),而 **supply-chain-attestation** 已经提供出处追踪(provenance),作为“该产物源自该 sha”的密码学背书。
|
|
122
209
|
|
|
123
210
|
---
|
|
124
211
|
|
|
125
|
-
##
|
|
212
|
+
## 初始开发阶段
|
|
126
213
|
|
|
127
|
-
###
|
|
214
|
+
### 0.x.x 版本
|
|
128
215
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
216
|
+
```
|
|
217
|
+
0.1.0 # Initial development release
|
|
218
|
+
0.2.0 # Add features
|
|
219
|
+
0.3.0 # Add more features
|
|
220
|
+
...
|
|
221
|
+
1.0.0 # First stable release
|
|
222
|
+
```
|
|
134
223
|
|
|
135
|
-
|
|
224
|
+
**指南**:
|
|
225
|
+
- 主版本号为 0 表示处于开发阶段
|
|
226
|
+
- API 可能会频繁变动
|
|
227
|
+
- MINOR 版本中允许包含破坏性变更
|
|
228
|
+
- 当 API 趋于稳定时迁移至 1.0.0
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## 版本生命周期
|
|
233
|
+
|
|
234
|
+
### 发布周期示例
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
Development Phase:
|
|
238
|
+
0.1.0 → 0.2.0 → 0.9.0
|
|
239
|
+
|
|
240
|
+
First Stable Release:
|
|
241
|
+
1.0.0
|
|
242
|
+
|
|
243
|
+
Feature Additions:
|
|
244
|
+
1.0.0 → 1.1.0 → 1.2.0
|
|
245
|
+
|
|
246
|
+
Bug Fixes:
|
|
247
|
+
1.2.0 → 1.2.1 → 1.2.2
|
|
248
|
+
|
|
249
|
+
Next Major Release:
|
|
250
|
+
1.2.2 → 2.0.0-alpha.1 → 2.0.0-beta.1 → 2.0.0-rc.1 → 2.0.0
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 变更日志集成
|
|
256
|
+
|
|
257
|
+
> **另请参阅**:有关全面的 CHANGELOG 编写指南、格式模板和示例,请参阅 [changelog-standards.md](changelog-standards.md)。
|
|
258
|
+
|
|
259
|
+
### CHANGELOG.md 快速参考
|
|
260
|
+
|
|
261
|
+
CHANGELOG 文件应遵循 [Keep a Changelog](https://keepachangelog.com/) 格式,并包含以下类别:
|
|
262
|
+
|
|
263
|
+
| 类别 | 用途 |
|
|
264
|
+
|----------|---------|
|
|
265
|
+
| `Added` | 新功能 |
|
|
266
|
+
| `Changed` | 现有功能的变更 |
|
|
267
|
+
| `Deprecated` | 未来将移除的功能 |
|
|
268
|
+
| `Removed` | 已移除的功能 |
|
|
269
|
+
| `Fixed` | 错误修复 |
|
|
270
|
+
| `Security` | 安全漏洞补丁 |
|
|
271
|
+
|
|
272
|
+
**破坏性变更**:添加前缀 `**BREAKING**:` 以确保可见性。
|
|
273
|
+
|
|
274
|
+
有关完整的格式模板和示例,请参阅 [changelog-standards.md](changelog-standards.md)。
|
|
275
|
+
|
|
276
|
+
### 排除规则
|
|
136
277
|
|
|
278
|
+
CHANGELOG 不应记录以下类型的变更:
|
|
279
|
+
|
|
280
|
+
#### 1. 被 `.gitignore` 排除的目录
|
|
281
|
+
|
|
282
|
+
从版本控制中排除的目录不会被提交,因此不应记录在 CHANGELOG 中。
|
|
283
|
+
|
|
284
|
+
**原则**:项目的 `.gitignore` 中列出的任何目录或文件都不应记录在 CHANGELOG 中。
|
|
285
|
+
|
|
286
|
+
**常见排除类别(示例)**:
|
|
287
|
+
|
|
288
|
+
| 类别 | 常见目录/文件 | 原因 |
|
|
289
|
+
|----------|-------------------------|--------|
|
|
290
|
+
| AI 协作工具 | `.claude/`, `.cursor/`, `.ai/` | 本地开发辅助工具,不在版本控制中 |
|
|
291
|
+
| 开发标准 | `.standards/` | 本地标准文档,不在版本控制中 |
|
|
292
|
+
| 构建输出 | `dist/`, `build/`, `out/` | 构建产物,不在版本控制中 |
|
|
293
|
+
| 大数据 | `data/`, `datasets/` | 数据文件,不在版本控制中 |
|
|
294
|
+
|
|
295
|
+
**验证方法**:
|
|
296
|
+
|
|
297
|
+
**macOS / Linux:**
|
|
298
|
+
```bash
|
|
299
|
+
# Before generating CHANGELOG, check project's .gitignore exclusions
|
|
300
|
+
cat .gitignore | grep -E "^[^#*]" | head -20
|
|
137
301
|
```
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
302
|
+
|
|
303
|
+
**Windows PowerShell:**
|
|
304
|
+
```powershell
|
|
305
|
+
# Before generating CHANGELOG, check project's .gitignore exclusions
|
|
306
|
+
Get-Content .gitignore | Where-Object { $_ -match "^[^#*]" } | Select-Object -First 20
|
|
142
307
|
```
|
|
143
308
|
|
|
309
|
+
**注意**:每个项目应根据自身的 `.gitignore` 设置确定排除项。上表仅为常见示例。
|
|
310
|
+
|
|
311
|
+
#### 2. 构建产物和临时文件
|
|
312
|
+
|
|
313
|
+
以下类型的变更也不应记录:
|
|
314
|
+
|
|
315
|
+
- `bin/`、`obj/`、`Release/`、`Debug/` 及其他构建输出
|
|
316
|
+
- `*.log`、`*.tmp` 及其他临时文件
|
|
317
|
+
- `node_modules/`、`packages/` 及其他依赖目录
|
|
318
|
+
|
|
319
|
+
#### 3. 环境与配置文件(敏感数据)
|
|
320
|
+
|
|
321
|
+
包含敏感数据的文件不应记录:
|
|
322
|
+
|
|
323
|
+
- `*.env`、`.env.*` 环境变量文件
|
|
324
|
+
- `*.local.json`、`*.local.yaml` 本地配置文件(例如 .NET 的 `appsettings.*.local.json`)
|
|
325
|
+
- `*.pem`、`*.key`、`*.p12` 密钥与证书文件
|
|
326
|
+
- `credentials.*`、`secrets.*` 凭据文件
|
|
327
|
+
|
|
328
|
+
### 最佳实践
|
|
329
|
+
|
|
330
|
+
生成 CHANGELOG 时,请遵循以下流程:
|
|
331
|
+
|
|
332
|
+
1. **列出变更的提交**
|
|
333
|
+
|
|
334
|
+
**macOS / Linux / Windows (Git):**
|
|
335
|
+
```bash
|
|
336
|
+
git log main..HEAD --oneline
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
2. **排除不需要记录的提交**
|
|
340
|
+
- 包含 "gitignore"、"version control" 或 "misc(version control)" 类型的提交
|
|
341
|
+
- 仅修改排除目录的提交
|
|
342
|
+
|
|
343
|
+
3. **对记录进行分类**
|
|
344
|
+
- 仅记录将提交到仓库的实际代码或文档变更
|
|
345
|
+
- 确保所有记录的文件路径都存在于仓库中
|
|
346
|
+
|
|
347
|
+
4. **验证记录**
|
|
348
|
+
|
|
349
|
+
**macOS / Linux:**
|
|
350
|
+
```bash
|
|
351
|
+
# Verify that recorded paths exist in the repository
|
|
352
|
+
git ls-files | grep -E "path/to/file"
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
**Windows PowerShell:**
|
|
356
|
+
```powershell
|
|
357
|
+
# Verify that recorded paths exist in the repository
|
|
358
|
+
git ls-files | Select-String -Pattern "path/to/file"
|
|
359
|
+
```
|
|
360
|
+
|
|
144
361
|
---
|
|
145
362
|
|
|
146
|
-
##
|
|
363
|
+
## 发布流程
|
|
147
364
|
|
|
148
|
-
###
|
|
365
|
+
### 概述
|
|
149
366
|
|
|
150
|
-
|
|
151
|
-
|-----------|-----|
|
|
152
|
-
| 破坏性变更 | MAJOR |
|
|
153
|
-
| 新功能 | MINOR |
|
|
154
|
-
| 错误修复 | PATCH |
|
|
367
|
+
完整的 Release 流程包含 5 个阶段:
|
|
155
368
|
|
|
156
|
-
|
|
369
|
+
1. **发布前诊断** - 强制要求
|
|
370
|
+
2. **环境准备**
|
|
371
|
+
3. **包生成**
|
|
372
|
+
4. **部署执行**
|
|
373
|
+
5. **发布后验证**
|
|
157
374
|
|
|
375
|
+
### 阶段 1:发布前诊断 - 强制要求
|
|
376
|
+
|
|
377
|
+
**目的**:在生成升级包之前评估目标服务器的环境状态
|
|
378
|
+
|
|
379
|
+
**检查项**:
|
|
380
|
+
- 系统工具版本
|
|
381
|
+
- 所需驱动
|
|
382
|
+
- 磁盘空间
|
|
383
|
+
- 数据库连通性
|
|
384
|
+
- 应用程序版本
|
|
385
|
+
- 配置完整性
|
|
386
|
+
|
|
387
|
+
**通过条件**(质量门禁):
|
|
388
|
+
- 已安装所有必需工具
|
|
389
|
+
- 磁盘空间充足(至少 500MB)
|
|
390
|
+
- 数据库连接正常
|
|
391
|
+
- 无系统级错误
|
|
392
|
+
|
|
393
|
+
**失败处理**:
|
|
394
|
+
- 若诊断失败,执行环境准备(阶段 2)
|
|
395
|
+
- 修复后重新执行诊断
|
|
396
|
+
- 严禁跳过诊断直接进入打包阶段
|
|
397
|
+
|
|
398
|
+
---
|
|
399
|
+
|
|
400
|
+
### 阶段 2:环境准备
|
|
401
|
+
|
|
402
|
+
**目的**:根据诊断报告结果安装缺失的工具和驱动
|
|
403
|
+
|
|
404
|
+
**验证标准**:
|
|
405
|
+
- 所有诊断项均通过
|
|
406
|
+
- 数据库连接测试成功
|
|
407
|
+
- 验证工具显示无错误
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
### 阶段 3:包生成
|
|
412
|
+
|
|
413
|
+
**目的**:生成包含最新版本的升级包
|
|
414
|
+
|
|
415
|
+
**执行步骤**:
|
|
416
|
+
```bash
|
|
417
|
+
# 1. Confirm current branch and version
|
|
418
|
+
git branch
|
|
419
|
+
git describe --tags
|
|
420
|
+
|
|
421
|
+
# 2. Generate upgrade package (using project-provided packaging script)
|
|
422
|
+
./tools/generate-upgrade-package.sh -v v1.2.1 -o ./dist
|
|
423
|
+
|
|
424
|
+
# 3. Verify upgrade package contents
|
|
425
|
+
tar -tzf dist/upgrade-package-*.tar.gz | head -20
|
|
158
426
|
```
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
427
|
+
|
|
428
|
+
#### 升级包命名
|
|
429
|
+
|
|
430
|
+
**格式**:`{PROJECT}-upgrade-v{VERSION}-{DATE}.tar.gz`
|
|
431
|
+
|
|
432
|
+
| 元素 | 说明 | 示例 |
|
|
433
|
+
|------|------|------|
|
|
434
|
+
| `{PROJECT}` | 项目名称(替换为实际项目名称) | `my-app`、`api-server` |
|
|
435
|
+
| `{VERSION}` | 版本号(与 Git tag 一致) | `1.2.1`、`2.0.0-beta.1` |
|
|
436
|
+
| `{DATE}` | 打包日期(YYYYMMDD) | `20251128` |
|
|
437
|
+
|
|
438
|
+
**示例**(将 `{PROJECT}` 替换为您的项目名称):
|
|
439
|
+
```
|
|
440
|
+
{PROJECT}-upgrade-v1.2.1-20251127.tar.gz
|
|
441
|
+
{PROJECT}-upgrade-v2.0.0-beta.1-20251201.tar.gz
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
### 阶段 4:部署执行
|
|
447
|
+
|
|
448
|
+
**目的**:在目标服务器上执行升级
|
|
449
|
+
|
|
450
|
+
**执行步骤**:
|
|
451
|
+
```bash
|
|
452
|
+
# 1. Upload upgrade package to target server
|
|
453
|
+
scp upgrade-package-*.tar.gz user@target:/tmp/
|
|
454
|
+
|
|
455
|
+
# 2. Extract upgrade package
|
|
456
|
+
cd /tmp
|
|
457
|
+
tar -xzf upgrade-package-*.tar.gz
|
|
458
|
+
cd upgrade-package-*/
|
|
459
|
+
|
|
460
|
+
# 3. Dry-run test (strongly recommended)
|
|
461
|
+
sudo ./upgrade.sh --dry-run
|
|
462
|
+
|
|
463
|
+
# 4. Actual upgrade
|
|
464
|
+
sudo ./upgrade.sh
|
|
163
465
|
```
|
|
164
466
|
|
|
467
|
+
**部署验证**:
|
|
468
|
+
- 备份已创建
|
|
469
|
+
- 服务成功停止
|
|
470
|
+
- 文件成功部署
|
|
471
|
+
- Schema 迁移成功(如适用)
|
|
472
|
+
- 服务成功启动
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
### 阶段 5:发布后验证
|
|
477
|
+
|
|
478
|
+
**目的**:确认升级成功且应用程序正常运行
|
|
479
|
+
|
|
480
|
+
**检查项**:
|
|
481
|
+
```bash
|
|
482
|
+
# 1. Check service status
|
|
483
|
+
systemctl status your-service
|
|
484
|
+
|
|
485
|
+
# 2. Check application build identity (version + commit sha + build time)
|
|
486
|
+
# Assert the returned sha matches the deployed artifact's sha — not just the version.
|
|
487
|
+
curl http://localhost:PORT/version # or /health, if build identity is embedded there
|
|
488
|
+
# Expected: {"version": "1.2.1", "sha": "<deployed-artifact-sha>", "buildTime": "..."}
|
|
489
|
+
|
|
490
|
+
# 3. Check logs for no errors
|
|
491
|
+
tail -100 /path/to/app.log | grep -i error
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
**成功标准**:
|
|
495
|
+
- 服务运行正常
|
|
496
|
+
- `/version`(或 `/health`)返回正确的版本号**以及**与已部署制品匹配的
|
|
497
|
+
commit sha——仅版本匹配是不够的,因为两个构建可以共享同一个
|
|
498
|
+
`X.Y.Z`(参见 [Build identity is observable](#build-identity-is-observable-requirement))
|
|
499
|
+
- 日志中无致命错误
|
|
500
|
+
- 功能验证通过
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
### 发布检查清单
|
|
505
|
+
|
|
506
|
+
**发布前(诊断与准备)**:
|
|
507
|
+
- [ ] 执行服务器诊断
|
|
508
|
+
- [ ] 诊断报告通过所有检查项
|
|
509
|
+
- [ ] 环境准备已完成(如有缺失)
|
|
510
|
+
- [ ] 环境验证工具已通过
|
|
511
|
+
|
|
512
|
+
**发布(打包与部署)**:
|
|
513
|
+
- [ ] 升级包生成成功
|
|
514
|
+
- [ ] 升级包内容验证通过
|
|
515
|
+
- [ ] 空运行(Dry-run)测试无异常
|
|
516
|
+
- [ ] 备份计划已准备
|
|
517
|
+
- [ ] 回滚计划已准备
|
|
518
|
+
|
|
519
|
+
**发布后(验证与监控)**:
|
|
520
|
+
- [ ] 服务启动成功
|
|
521
|
+
- [ ] 版本号正确
|
|
522
|
+
- [ ] 功能验证通过
|
|
523
|
+
- [ ] 日志无异常
|
|
524
|
+
|
|
525
|
+
---
|
|
526
|
+
|
|
527
|
+
### 质量门禁
|
|
528
|
+
|
|
529
|
+
以下检查点**必须通过**,否则无法进入下一阶段:
|
|
530
|
+
|
|
531
|
+
| 阶段 | 门禁 | 失败处理 |
|
|
532
|
+
|------|------|----------|
|
|
533
|
+
| **诊断** | 诊断报告无错误 | 环境准备 |
|
|
534
|
+
| **准备** | 验证工具通过 | 修复并重新验证 |
|
|
535
|
+
| **打包** | 升级包结构完整 | 重新打包 |
|
|
536
|
+
| **部署** | 空运行(Dry-run)无异常 | 分析日志并修复 |
|
|
537
|
+
| **验证** | 服务运行正常 | 回滚 |
|
|
538
|
+
|
|
539
|
+
---
|
|
540
|
+
|
|
541
|
+
### 回滚计划
|
|
542
|
+
|
|
543
|
+
如果升级失败,执行以下回滚步骤:
|
|
544
|
+
|
|
545
|
+
```bash
|
|
546
|
+
# 1. Stop service
|
|
547
|
+
sudo systemctl stop your-service
|
|
548
|
+
|
|
549
|
+
# 2. Restore backup
|
|
550
|
+
BACKUP_PATH="/path/to/backup-$(date +%Y%m%d)"
|
|
551
|
+
sudo rm -rf /path/to/app
|
|
552
|
+
sudo mv "$BACKUP_PATH" /path/to/app
|
|
553
|
+
|
|
554
|
+
# 3. Restart service
|
|
555
|
+
sudo systemctl start your-service
|
|
556
|
+
|
|
557
|
+
# 4. Verify rollback success
|
|
558
|
+
sudo systemctl status your-service
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
### 合规性
|
|
564
|
+
|
|
565
|
+
**强制要求**:
|
|
566
|
+
- 严禁跳过诊断阶段
|
|
567
|
+
- 严禁跳过空运行(Dry-run)测试
|
|
568
|
+
- 必须保留诊断报告
|
|
569
|
+
- 必须准备回滚计划
|
|
570
|
+
|
|
571
|
+
**审计追踪**:
|
|
572
|
+
- 所有 Release 文档至少保留 12 个月
|
|
573
|
+
- 诊断报告关联至 Git Tag
|
|
574
|
+
- 完整保留升级日志
|
|
575
|
+
|
|
576
|
+
---
|
|
577
|
+
|
|
578
|
+
## Git 中的版本标签
|
|
579
|
+
|
|
580
|
+
### 创建标签
|
|
581
|
+
|
|
582
|
+
```bash
|
|
583
|
+
# Annotated tag (recommended)
|
|
584
|
+
git tag -a v1.2.0 -m "Release version 1.2.0"
|
|
585
|
+
|
|
586
|
+
# Tag with detailed message
|
|
587
|
+
git tag -a v2.0.0 -m "Release version 2.0.0
|
|
588
|
+
|
|
589
|
+
Major changes:
|
|
590
|
+
- New authentication system
|
|
591
|
+
- Redesigned API
|
|
592
|
+
- Performance improvements"
|
|
593
|
+
|
|
594
|
+
# Push tag to remote
|
|
595
|
+
git push origin v1.2.0
|
|
596
|
+
|
|
597
|
+
# Push all tags
|
|
598
|
+
git push origin --tags
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
### 标签命名规范
|
|
602
|
+
|
|
603
|
+
```
|
|
604
|
+
v1.0.0 ✅ Recommended (with 'v' prefix)
|
|
605
|
+
1.0.0 ✅ Acceptable (without 'v')
|
|
606
|
+
version-1.0.0 ❌ Avoid (too verbose)
|
|
607
|
+
1.0 ❌ Avoid (incomplete version)
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
---
|
|
611
|
+
|
|
612
|
+
## 自动化工具
|
|
613
|
+
|
|
614
|
+
### standard-version (Node.js)
|
|
615
|
+
|
|
616
|
+
```bash
|
|
617
|
+
# Install
|
|
618
|
+
npm install --save-dev standard-version
|
|
619
|
+
|
|
620
|
+
# Add to package.json
|
|
621
|
+
{
|
|
622
|
+
"scripts": {
|
|
623
|
+
"release": "standard-version"
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
# Create release
|
|
628
|
+
npm run release # Auto-increment based on commits
|
|
629
|
+
npm run release -- --release-as minor # Force minor version
|
|
630
|
+
npm run release -- --release-as 2.0.0 # Specific version
|
|
631
|
+
```
|
|
632
|
+
|
|
633
|
+
### semantic-release (Node.js)
|
|
634
|
+
|
|
635
|
+
```bash
|
|
636
|
+
# Install
|
|
637
|
+
npm install --save-dev semantic-release
|
|
638
|
+
|
|
639
|
+
# Configure in .releaserc.json
|
|
640
|
+
{
|
|
641
|
+
"branches": ["main"],
|
|
642
|
+
"plugins": [
|
|
643
|
+
"@semantic-release/commit-analyzer",
|
|
644
|
+
"@semantic-release/release-notes-generator",
|
|
645
|
+
"@semantic-release/changelog",
|
|
646
|
+
"@semantic-release/npm",
|
|
647
|
+
"@semantic-release/git",
|
|
648
|
+
"@semantic-release/github"
|
|
649
|
+
]
|
|
650
|
+
}
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
### 基于 Git 高度推导的版本控制(多语言:.NET / JVM / 多语言)
|
|
654
|
+
|
|
655
|
+
上述工具以 Node/npm 为中心。对于 **.NET、JVM 或多语言项目**,更推荐**基于 Git 高度推导的版本控制**,其版本是根据 Git 标签图谱加上自上一个标签以来的提交数量(“提交高度”,commit height)自动计算得出,而不是存储在手动编辑的文件中。由于版本是 Git 历史的确定性函数,**两个不同的构建绝不会在同一版本号上发生冲突**,且不会遗忘任何手动版本递增步骤——这正是它能够从结构上而非依靠自律来满足[部署版本唯一性](#deployment-version-identity)的原因。
|
|
656
|
+
|
|
657
|
+
| 工具 | 生态系统 | 说明 |
|
|
658
|
+
|------|-----------|-------|
|
|
659
|
+
| **MinVer** | .NET / MSBuild | 从最近的 Git 标签加上提交高度推导版本;无需配置文件,无需集成构建服务器 |
|
|
660
|
+
| **Nerdbank.GitVersioning** (nbgv) | .NET(也支持 Node 等) | 读取 `version.json`;将版本 + Git 高度 + 提交 ID 写入程序集和软件包中 |
|
|
661
|
+
| **GitVersion** | 多语言(.NET,外加与语言无关的 CLI) | 由分支和标签拓扑驱动的可配置版本控制模式(例如 Mainline、持续交付 / 持续部署) |
|
|
662
|
+
|
|
663
|
+
**何时使用何种工具:**
|
|
664
|
+
|
|
665
|
+
- **Node / npm 项目** → 提交驱动的自动化(见上文 `semantic-release` / `standard-version`):版本递增由约定式提交(Conventional Commits)推导而来。
|
|
666
|
+
- **多语言 / .NET / JVM 项目** → 基于 Git 高度推导的工具(MinVer / Nerdbank.GitVersioning / GitVersion):版本由 Git 标签 + 提交高度推导而来。
|
|
667
|
+
|
|
668
|
+
这两类工具都消除了容易被遗忘的手动版本递增。**注意事项:** 在 monorepo(单一代码库)中,单个全仓库范围的提交高度可能无法清晰地映射到各个软件包的版本上,且 squash-merge(压缩合并)工作流程会改变提交高度——请根据你的打标签规范验证推导出的版本。
|
|
669
|
+
|
|
670
|
+
---
|
|
671
|
+
|
|
672
|
+
## 依赖版本范围
|
|
673
|
+
|
|
674
|
+
### npm (package.json)
|
|
675
|
+
|
|
676
|
+
```json
|
|
677
|
+
{
|
|
678
|
+
"dependencies": {
|
|
679
|
+
"exact": "1.2.3", // Exact version
|
|
680
|
+
"patch": "~1.2.3", // >=1.2.3 <1.3.0
|
|
681
|
+
"minor": "^1.2.3", // >=1.2.3 <2.0.0
|
|
682
|
+
"range": ">=1.2.3 <2.0.0", // Explicit range
|
|
683
|
+
"latest": "*" // ❌ Avoid - any version
|
|
684
|
+
}
|
|
685
|
+
}
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
**建议**:
|
|
689
|
+
- 大多数依赖项使用 `^`(次要版本更新)
|
|
690
|
+
- 保守更新使用 `~`(仅补丁更新)
|
|
691
|
+
- 关键依赖项使用精确版本
|
|
692
|
+
- 绝不要在生产环境中使用 `*`
|
|
693
|
+
|
|
694
|
+
---
|
|
695
|
+
|
|
696
|
+
### .NET (csproj)
|
|
697
|
+
|
|
698
|
+
```xml
|
|
699
|
+
<ItemGroup>
|
|
700
|
+
<!-- Exact version -->
|
|
701
|
+
<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
|
|
702
|
+
|
|
703
|
+
<!-- Minimum version -->
|
|
704
|
+
<PackageReference Include="Microsoft.Extensions.Logging" Version="[8.0.0,)" />
|
|
705
|
+
|
|
706
|
+
<!-- Version range -->
|
|
707
|
+
<PackageReference Include="AutoMapper" Version="[12.0.0,13.0.0)" />
|
|
708
|
+
</ItemGroup>
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
---
|
|
712
|
+
|
|
713
|
+
## 破坏性变更与弃用
|
|
714
|
+
|
|
715
|
+
破坏性变更是驱动 **MAJOR** 版本递增的因素(参见[递增规则](#incrementing-rules))——这就是 SemVer 向使用者传达不兼容变更的方式。演进和退役 API 的*契约层级*细节由负责这些关注点的标准所拥有,因此每条规则都有单一事实来源:
|
|
716
|
+
|
|
717
|
+
- **API 版本化策略、向后兼容性检查清单(何为破坏性变更)、代码中的弃用注解以及迁移指南模板** → [API 设计标准](api-design-standards.md#api-versioning-strategies)
|
|
718
|
+
- **弃用生命周期、按 API 级别的最短通知期限、`Sunset` / `Deprecation` 标头以及使用者通知** → [弃用与下线标准](deprecation-standards.md#api-deprecation)
|
|
719
|
+
|
|
720
|
+
本标准仅保留版本编号规则:不兼容的变更必须作为 MAJOR 升级发布,且弃用应在执行移除的 MAJOR 之前的某个 MINOR 版本中公布(参见 [MAJOR 版本](#major-version-x00)指南)。
|
|
721
|
+
|
|
722
|
+
---
|
|
723
|
+
|
|
724
|
+
## 项目配置
|
|
725
|
+
|
|
726
|
+
### 在 README.md 中记录
|
|
727
|
+
|
|
728
|
+
```markdown
|
|
729
|
+
## Versioning
|
|
730
|
+
|
|
731
|
+
This project follows [Semantic Versioning 2.0.0](https://semver.org/).
|
|
732
|
+
|
|
733
|
+
### Version Format
|
|
734
|
+
`MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`
|
|
735
|
+
|
|
736
|
+
### Release Cycle
|
|
737
|
+
- **Major releases**: Annually (breaking changes)
|
|
738
|
+
- **Minor releases**: Quarterly (new features)
|
|
739
|
+
- **Patch releases**: As needed (bug fixes)
|
|
740
|
+
|
|
741
|
+
### Support Policy
|
|
742
|
+
- Latest major version: Full support
|
|
743
|
+
- Previous major version: Security fixes only (1 year)
|
|
744
|
+
- Older versions: No support
|
|
745
|
+
|
|
746
|
+
### Changelog
|
|
747
|
+
See [CHANGELOG.md](CHANGELOG.md) for release history.
|
|
748
|
+
```
|
|
749
|
+
|
|
750
|
+
---
|
|
751
|
+
|
|
752
|
+
## 版本比较
|
|
753
|
+
|
|
754
|
+
### 优先级规则
|
|
755
|
+
|
|
756
|
+
```
|
|
757
|
+
1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
|
|
758
|
+
|
|
759
|
+
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0
|
|
760
|
+
|
|
761
|
+
1.0.0 < 1.0.0+001 (build metadata ignored in precedence)
|
|
762
|
+
```
|
|
763
|
+
|
|
764
|
+
### 代码中的比较
|
|
765
|
+
|
|
766
|
+
```javascript
|
|
767
|
+
// JavaScript (using semver package)
|
|
768
|
+
const semver = require('semver');
|
|
769
|
+
|
|
770
|
+
semver.gt('1.2.3', '1.2.2'); // true
|
|
771
|
+
semver.satisfies('1.2.3', '^1.0.0'); // true
|
|
772
|
+
semver.major('2.3.1'); // 2
|
|
773
|
+
```
|
|
774
|
+
|
|
775
|
+
---
|
|
776
|
+
|
|
777
|
+
## 常见问题
|
|
778
|
+
|
|
779
|
+
### Q: 我应该何时发布 1.0.0?
|
|
780
|
+
|
|
781
|
+
**A**: 当 API 稳定且准备好承诺向后兼容时。
|
|
782
|
+
|
|
783
|
+
---
|
|
784
|
+
|
|
785
|
+
### Q: 内部破坏性变更是否需要递增 MAJOR?
|
|
786
|
+
|
|
787
|
+
**A**: 不需要,仅在公开 API 变更时递增。内部重构属于 PATCH 或 MINOR。
|
|
788
|
+
|
|
789
|
+
---
|
|
790
|
+
|
|
791
|
+
### Q: 我可以跳过版本号吗?
|
|
792
|
+
|
|
793
|
+
**A**: 可以,但不推荐。为了清晰起见,请使用连续的版本编号。
|
|
794
|
+
|
|
795
|
+
---
|
|
796
|
+
|
|
797
|
+
### Q: 库与应用程序该如何进行版本控制?
|
|
798
|
+
|
|
799
|
+
**A**:
|
|
800
|
+
- **库**:严格遵循 SemVer(API 至关重要)
|
|
801
|
+
- **应用程序**:可以更加灵活(用户体验至关重要)
|
|
802
|
+
|
|
165
803
|
---
|
|
166
804
|
|
|
167
805
|
## 相关标准
|
|
168
806
|
|
|
169
807
|
- [变更日志标准](changelog-standards.md)
|
|
170
|
-
- [Git
|
|
808
|
+
- [Git 工作流标准](git-workflow.md)
|
|
171
809
|
- [提交消息指南](commit-message-guide.md)
|
|
810
|
+
- [API 设计标准](api-design-standards.md) — API 版本化策略、向后兼容性规则、迁移指南
|
|
811
|
+
- [弃用与下线标准](deprecation-standards.md) — 弃用生命周期与最短通知期限
|
|
812
|
+
|
|
813
|
+
---
|
|
814
|
+
|
|
815
|
+
## 版本历史
|
|
816
|
+
|
|
817
|
+
| 版本 | 日期 | 变更 |
|
|
818
|
+
|---------|------|---------|
|
|
819
|
+
| 1.5.0 | 2026-07-01 | 新增:在自动化工具中为多语言 / .NET / JVM 项目添加了基于 git-height 推导的版本控制工具(MinVer / Nerdbank.GitVersioning / GitVersion)(UDS #138 R2);将“构建标识可观测”提升为一项要求——已部署的服务必须通过可查询端点暴露 `version + commit sha + build time`——并在 Phase 5 发布后验证中添加了 commit-sha + build-time 断言(UDS #138 R3) |
|
|
820
|
+
| 1.4.0 | 2026-06-24 | 移出(至单一来源):API 版本化策略(去重)、弃用时间线 + 各层级期限、向后兼容性检查清单,以及迁移指南模板——现归属于 api-design-standards / deprecation-standards;版本控制标准对其进行交叉引用(XSPEC-298 R8, UDS #126) |
|
|
821
|
+
| 1.3.0 | 2026-06-23 | 新增:部署版本标识章节;构建元数据作为部署区分标识的注意事项(源自 UDS #138) |
|
|
822
|
+
| 1.2.0 | 2025-12-30 | 新增:API 版本化策略、弃用时间线、向后兼容性检查清单 |
|
|
823
|
+
| 1.1.3 | 2025-12-24 | 新增:相关标准章节 |
|
|
824
|
+
| 1.1.2 | 2025-12-11 | 改进:升级包命名示例,使用通用占位符代替硬编码的项目名称 |
|
|
825
|
+
| 1.1.1 | 2025-12-04 | 重构:CHANGELOG 排除规则以使其更通用(移除了特定于项目的目录) |
|
|
826
|
+
| 1.1.0 | 2025-12-04 | 新增:CHANGELOG 排除规则、发布流程章节 |
|
|
827
|
+
| 1.0.0 | 2025-11-12 | 初始版本控制标准 |
|
|
828
|
+
|
|
829
|
+
---
|
|
830
|
+
|
|
831
|
+
## 参考资料
|
|
832
|
+
|
|
833
|
+
- [Semantic Versioning 2.0.0](https://semver.org/)
|
|
834
|
+
- [Keep a Changelog](https://keepachangelog.com/)
|
|
835
|
+
- [Calendar Versioning](https://calver.org/)(备用方案)
|
|
172
836
|
|
|
173
837
|
---
|
|
174
838
|
|