universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-CN/skills/claude-code/release-standards/release-workflow.md

@@ -0,0 +1,345 @@
+---
+source: ../../../../../skills/claude-code/release-standards/release-workflow.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-01-14
+status: current
+---
+
+# 發布流程指南
+
+> **Language**: [English](../../../../../skills/claude-code/release-standards/release-workflow.md) | 简体中文
+
+**版本**: 2.0.0
+**最後更新**: 2026-01-14
+**適用範圍**: 所有使用語義化版本的软体项目
+
+---
+
+## 目的
+
+本文件提供適用於任何软体项目的通用發布流程指南。涵蓋版本管理、發布类型和标准發布流程。
+
+> **注意**：项目特有配置（額外的版本文件、翻譯同步、自订验证脚本）請在项目的 `CLAUDE.md` 文件中定義。
+
+---
+
+## 發布类型
+
+### 1. Beta 發布（测试版本）
+
+**使用时机：**
+- 在穩定版發布前测试新功能
+- 向早期採用者收集回饋
+- 在生产環境前验证错误修正
+
+**版本模式：** `X.Y.Z-beta.N`（例如：`3.2.1-beta.1`）
+
+**npm 标签：** `@beta`
+
+---
+
+### 2. 穩定發布（正式版本）
+
+**使用时机：**
+- 所有功能已测试并验证
+- 准备好用於生产環境
+- 所有测试通過
+
+**版本模式：** `X.Y.Z`（例如：`3.2.1`）
+
+**npm 标签：** `@latest`
+
+---
+
+### 3. Alpha 發布（早期测试）
+
+**使用时机：**
+- 非常早期的测试，功能不穩定
+- 僅限內部团队测试
+
+**版本模式：** `X.Y.Z-alpha.N`（例如：`3.3.0-alpha.1`）
+
+**npm 标签：** `@alpha`
+
+---
+
+### 4. 候選發布（预發布）
+
+**使用时机：**
+- 穩定版發布前的最終测试
+- 不包含新功能，僅错误修正
+
+**版本模式：** `X.Y.Z-rc.N`（例如：`3.2.1-rc.1`）
+
+**npm 标签：** `@rc`
+
+---
+
+## 标准發布流程
+
+### 步骤 1：發布前检查
+
+```bash
+# 确保在 main 分支并已更新
+git checkout main
+git pull origin main
+
+# 执行测试
+npm test  # 或项目的测试指令
+
+# 执行程序码检查
+npm run lint  # 或项目的 lint 指令
+
+# 检查 git 状态
+git status  # 应为乾淨状态
+```
+
+### 步骤 2：更新版本
+
+```bash
+# npm 项目
+npm version X.Y.Z        # 穩定版
+npm version X.Y.Z-beta.N # Beta 版
+
+# 其他项目，手动更新版本文件
+```
+
+### 步骤 3：更新 CHANGELOG
+
+依照 [Keep a Changelog](https://keepachangelog.com/) 格式更新 `CHANGELOG.md`：
+
+```markdown
+## [Unreleased]
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- 新功能描述
+
+### Changed
+- 变更描述
+
+### Fixed
+- 错误修正描述
+```
+
+### 步骤 4：提交与标签
+
+```bash
+# 提交变更
+git add .
+git commit -m "chore(release): X.Y.Z"
+
+# 建立并推送标签
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+### 步骤 5：建立 Release
+
+建立 GitHub/GitLab Release：
+- Tag：`vX.Y.Z`
+- 標題：`vX.Y.Z - [Release Name]`
+- 若为 beta/alpha/rc，標记为 pre-release
+- 從 CHANGELOG 加入發布说明
+
+### 步骤 6：验证發布
+
+```bash
+# npm 套件
+npm view <package-name> dist-tags
+
+# 测试安裝
+npm install -g <package-name>@<version>
+```
+
+---
+
+## npm dist-tag 策略
+
+| 版本模式 | npm Tag | 安裝指令 |
+|---------|---------|---------|
+| `X.Y.Z` | `latest` | `npm install <package>` |
+| `X.Y.Z-beta.N` | `beta` | `npm install <package>@beta` |
+| `X.Y.Z-alpha.N` | `alpha` | `npm install <package>@alpha` |
+| `X.Y.Z-rc.N` | `rc` | `npm install <package>@rc` |
+
+### 自动标签偵测
+
+用於 CI/CD 自动化，使用正則表达式偵测版本类型：
+
+```bash
+VERSION=$(node -p "require('./package.json').version")
+
+if [[ $VERSION =~ -beta\. ]]; then
+  TAG=beta
+elif [[ $VERSION =~ -alpha\. ]]; then
+  TAG=alpha
+elif [[ $VERSION =~ -rc\. ]]; then
+  TAG=rc
+else
+  TAG=latest
+fi
+
+npm publish --tag $TAG
+```
+
+---
+
+## CHANGELOG 格式
+
+### Beta 發布格式
+
+```markdown
+## [X.Y.Z-beta.N] - YYYY-MM-DD
+
+> ⚠️ **Beta 發布**：这是测试版本。
+
+### Added
+- 功能描述
+
+### Fixed
+- 错误修正描述
+```
+
+### 穩定發布格式
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- 功能描述及詳情
+
+### Changed
+- 变更描述
+
+### Fixed
+- 错误修正描述
+```
+
+---
+
+## 版本编号策略
+
+遵循[語義化版本](https://semver.org/)：
+
+| 变更类型 | 版本递增 | 範例 |
+|---------|---------|------|
+| 破壞性变更 | MAJOR | 2.9.5 → 3.0.0 |
+| 新功能（向後相容） | MINOR | 3.1.5 → 3.2.0 |
+| 错误修正（向後相容） | PATCH | 3.2.0 → 3.2.1 |
+| 预發布 | 新增後綴 | 3.2.1 → 3.2.1-beta.1 |
+
+---
+
+## 疑難排解
+
+### npm Tag 错误
+
+如果使用错误的标签發布：
+
+```bash
+npm dist-tag add <package>@<version> <correct-tag>
+```
+
+### 需要撤回發布
+
+```bash
+# 选项 1：棄用
+npm deprecate <package>@<version> "Please use <new-version> instead"
+
+# 选项 2：取消發布（僅限 72 小时內）
+npm unpublish <package>@<version>
+
+# 选项 3：發布修補版本
+npm version patch
+```
+
+---
+
+## 预發布检查清单
+
+### 通用检查
+
+- [ ] 所有测试通過
+- [ ] Linting 通過
+- [ ] Git 工作目录乾淨
+- [ ] CHANGELOG 已更新
+- [ ] 在正确的分支（穩定版用 main）
+
+### Beta 發布前
+
+- [ ] 通用检查完成
+- [ ] 已知問題已记录
+
+### 穩定發布前
+
+- [ ] 通用检查完成
+- [ ] Beta 测试完成（如適用）
+- [ ] 無嚴重错误
+- [ ] 已建立迁移指南（如有破壞性变更）
+
+---
+
+## 项目特有配置
+
+项目特有的發布需求請在 `CLAUDE.md` 中定義：
+
+```markdown
+## Release Process (Project-Specific)
+
+### Additional Version Files
+- `path/to/file1.json` - description
+- `path/to/file2.json` - description
+
+### Pre-release Scripts
+# macOS / Linux
+./scripts/your-pre-release-check.sh
+
+# Windows PowerShell
+.\scripts\your-pre-release-check.ps1
+
+### Additional Verification
+- Custom verification step 1
+- Custom verification step 2
+```
+
+这讓 AI 助手在执行 `/release` 指令时自动套用项目特有規則。
+
+---
+
+## AI 助理指南
+
+協助發布时：
+
+1. **識别發布类型：** 詢問是 beta、alpha、rc 或穩定版
+2. **执行预發布检查：** 测试、linting、git 状态
+3. **检查项目特有規則：** 阅读 `CLAUDE.md` 取得額外需求
+4. **更新版本：** 使用適當的版本指令
+5. **更新 CHANGELOG：** 遵循标准格式
+6. **建立 git tag：** 格式 `v{VERSION}`
+7. **建立 release：** GitHub/GitLab release
+8. **验证發布：** 检查 dist-tags 并测试安裝
+
+---
+
+## 相关文件
+
+- [語義化版本指南](./semantic-versioning.md)
+- [Changelog 格式](./changelog-format.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 2.0.0 | 2026-01-14 | 重構为通用指南，项目特有内容移至 CLAUDE.md |
+| 1.0.0 | 2026-01-02 | 初始發布流程指南 |
+
+---
+
+## 授权
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权發布。

package/bundled/locales/zh-CN/skills/claude-code/release-standards/semantic-versioning.md

@@ -0,0 +1,250 @@
+---
+source: skills/claude-code/release-standards/semantic-versioning.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-25
+status: current
+---
+
+# 語意化版本指南
+
+> **语言**: [English](../../../../../skills/claude-code/release-standards/semantic-versioning.md) | 简体中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-24
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+本文件提供软体發布中語意化版本控制（SemVer）的指南。
+
+---
+
+## 格式
+
+```
+MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+```
+
+### 組成部分
+
+| 組成部分 | 用途 | 何时递增 |
+|-----------|---------|-------------------|
+| **MAJOR** | 重大变更 | 不相容的 API 变更 |
+| **MINOR** | 新功能 | 向後相容的功能性 |
+| **PATCH** | 错误修正 | 向後相容的错误修正 |
+| **PRERELEASE** | 预發布識别码 | Alpha、beta、rc 版本 |
+| **BUILD** | 建置元数据 | 建置编号、提交雜湊值 |
+
+---
+
+## MAJOR 版本（X.0.0）
+
+**递增时机**:
+- 重大 API 变更
+- 移除已棄用的功能
+- 重大架構变更
+- 不相容的行为变更
+
+**範例**:
+```
+1.9.5 → 2.0.0  # Remove deprecated API
+3.2.1 → 4.0.0  # Change return type of public method
+```
+
+**指南**:
+- 將 MINOR 和 PATCH 重置为 0
+- 撰写迁移指南文件
+- 在先前的 MINOR 版本中提供棄用警告
+
+---
+
+## MINOR 版本（x.Y.0）
+
+**递增时机**:
+- 新增新功能（向後相容）
+- 棄用功能（不移除）
+- 实质的內部改进
+- 新的公開 API
+
+**範例**:
+```
+2.3.5 → 2.4.0  # Add new API endpoint
+1.12.0 → 1.13.0  # Add optional parameter
+```
+
+**指南**:
+- 將 PATCH 重置为 0
+- 現有功能保持不变
+- 新功能採用选择性加入
+
+---
+
+## PATCH 版本（x.y.Z）
+
+**递增时机**:
+- 错误修正（無新功能）
+- 安全性修補
+- 文件修正
+- 內部重構（無 API 变更）
+
+**範例**:
+```
+3.1.2 → 3.1.3  # Fix null pointer exception
+2.0.0 → 2.0.1  # Security vulnerability patch
+```
+
+**指南**:
+- 無新功能
+- 無 API 变更
+- 可立即安全更新
+
+---
+
+## 预發布版本
+
+### 識别码
+
+| 識别码 | 用途 | 穩定性 | 目標受眾 |
+|------------|---------|-----------|----------|
+| `alpha` | 早期测试 | 不穩定 | 內部团队 |
+| `beta` | 功能完整 | 大致穩定 | 早期採用者 |
+| `rc` | 最終测试 | 穩定 | Beta 测试者 |
+
+### 範例
+
+```
+1.0.0-alpha.1       # First alpha release
+1.0.0-alpha.2       # Second alpha release
+1.0.0-beta.1        # First beta release
+1.0.0-beta.2        # Second beta release
+1.0.0-rc.1          # Release candidate 1
+1.0.0               # Stable release
+```
+
+### 排序
+
+```
+1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
+```
+
+---
+
+## 建置元数据
+
+### 範例
+
+```
+1.0.0+20250112            # Date-based build
+2.3.1+001                 # Sequential build number
+3.0.0+sha.5114f85         # Git commit hash
+```
+
+**注意**: 建置元数据不会影響版本優先順序。
+
+---
+
+## 初始开发（0.x.x）
+
+```
+0.1.0  # Initial development release
+0.2.0  # Add features
+0.9.0  # Approaching stability
+1.0.0  # First stable release
+```
+
+**指南**:
+- 主版本 0 表示开发阶段
+- API 可能經常变更
+- MINOR 版本允許重大变更
+- API 穩定时移至 1.0.0
+
+---
+
+## 版本生命周期範例
+
+```
+Development Phase:
+0.1.0 → 0.2.0 → 0.9.0
+
+First Stable Release:
+1.0.0
+
+Feature Additions:
+1.0.0 → 1.1.0 → 1.2.0
+
+Bug Fixes:
+1.2.0 → 1.2.1 → 1.2.2
+
+Next Major Release:
+1.2.2 → 2.0.0-alpha.1 → 2.0.0-beta.1 → 2.0.0-rc.1 → 2.0.0
+```
+
+---
+
+## Git 标签
+
+### 建立标签
+
+```bash
+# 附註标签（建议）
+git tag -a v1.2.0 -m "Release version 1.2.0"
+
+# 推送标签到遠端
+git push origin v1.2.0
+
+# 推送所有标签
+git push origin --tags
+```
+
+### 标签命名慣例
+
+```
+v1.0.0          ✅ 建议（帶 'v' 前綴）
+1.0.0           ✅ 可接受（不帶 'v'）
+version-1.0.0   ❌ 避免（太冗長）
+1.0             ❌ 避免（不完整版本）
+```
+
+---
+
+## 相依性版本範圍
+
+### npm (package.json)
+
+```json
+{
+  "dependencies": {
+    "exact": "1.2.3",           // 确切版本
+    "patch": "~1.2.3",          // >=1.2.3 <1.3.0
+    "minor": "^1.2.3",          // >=1.2.3 <2.0.0
+    "range": ">=1.2.3 <2.0.0",  // 明确範圍
+    "latest": "*"               // ❌ 避免 - 任何版本
+  }
+}
+```
+
+---
+
+## 相关标准
+
+- [版本控制标准](../../../../../core/versioning.md)
+- [变更日誌格式指南](./changelog-format.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2025-12-24 | 新增：标准區段（目的、相关标准、版本历史、授权） |
+
+---
+
+## 授权
+
+本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权發布。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)