release-please-protection

Release-Please 保护

自动检测并阻止对所有项目中由 release-please 管理的文件进行手动编辑。

概述

此技能可主动检测并警告由 Google 的 release-please 自动化工具管理的文件。它会在问题编辑尝试发生之前将其识别出来，从而帮助避免合并冲突和工作流中断。

此技能的触发场景

此技能会在以下场景中自动触发：

1. 直接编辑受保护文件的请求
2. 用户提及版本升级、发布或变更日志更新
3. 大范围重构可能会涉及受版本控制的文件
4. 文档更新可能会包含 CHANGELOG.md
5. **“修复所有问题”**或类似的全面修改请求

受保护的文件

强保护（权限系统）

Claude Code 的权限系统会完全禁止编辑以下文件：

• **/CHANGELOG.md - 所有位置的变更日志文件

禁止的操作： Edit、Write、MultiEdit
允许的操作： Read（用于分析和获取上下文）

软保护（技能检测）

编辑这些文件前会触发警告和建议：

包管理器清单文件（版本字段）

• package.json → "version": "x.y.z"（npm/Node.js）
• pyproject.toml → version = "x.y.z"（Python/uv）
• Cargo.toml → version = "x.y.z"（Rust/cargo）
• .claude-plugin/plugin.json → "version": "x.y.z"（Claude Code 插件）
• pom.xml → <version>x.y.z</version>（Maven/Java）
• build.gradle → version = 'x.y.z'（Gradle）
• pubspec.yaml → version: x.y.z（Dart/Flutter）

为何采用软保护？ Claude Code 的权限系统作用于文件级别，而非字段级别。禁止编辑整个清单文件会妨碍通过自动化工具（npm、cargo、uv 等）进行正常的依赖更新。

检测逻辑

尝试进行任何编辑之前，此技能会检查：

1. 文件路径分析

if file_path ends with "CHANGELOG.md":
    → Inform user of hard permission block
    → Explain release-please workflow
    → Suggest conventional commit approach

2. 内容模式匹配

if file is package manifest AND edit touches version field:
    → Warn about release-please management
    → Explain why manual edits cause conflicts
    → Offer to edit OTHER fields (but not version)
    → Provide conventional commit template

3. 意图识别

if user request contains keywords: "version", "release", "bump", "changelog":
    → Proactively explain release-please workflow
    → Check if files in scope are protected
    → Suggest proper approach before attempting edits

响应模板

尝试编辑 CHANGELOG.md 时

⚠️ CHANGELOG.md Protection Active

I cannot edit CHANGELOG.md files - they're protected by Claude Code's permission
system because they're managed by release-please automation.

**Why this matters:**
Manual edits to CHANGELOG.md cause merge conflicts with automated release PRs,
breaking your release workflow.

**Proper workflow:**
1. Make your changes with conventional commit messages:
   - feat: adds new features (minor version bump)
   - fix: bug fixes (patch version bump)
   - chore: maintenance tasks (no version bump)
   - BREAKING CHANGE: breaking changes (major version bump)

2. Release-please automatically:
   - Detects conventional commits
   - Generates CHANGELOG entries
   - Creates a release PR with version bumps
   - Tags releases when PR is merged

**Example commit:**

feat(auth): add OAuth2 support

Implements OAuth2 authentication flow with PKCE. Includes refresh token rotation and session management.

**Need to override?**
For emergency fixes, temporarily edit ~/.claude/settings.json:
1. Comment out the CHANGELOG.md deny rules
2. Make your edits
3. Re-enable protection

检测到编辑版本字段时

⚠️ Version Field Protection Warning

I notice you're asking me to modify the version field in [file_name]. This field
is typically managed by release-please automation.

**Current version:** [current_version]
**Requested change:** [requested_change]

**Why manual edits are problematic:**
- Creates merge conflicts with release-please PRs
- Can cause version numbering inconsistencies
- Bypasses conventional commit history tracking

**I can help in two ways:**

1. **Automated approach (recommended):**
   I'll help you craft a conventional commit message that will trigger the
   appropriate version bump when release-please creates its next release PR.

   For [requested_change], you should use:
   - `feat:` for minor version bump
   - `fix:` for patch version bump
   - `feat!:` or `BREAKING CHANGE:` for major version bump

2. **Manual override (emergency only):**
   If you absolutely need to manually set the version (e.g., aligning with
   external requirements), I can edit other fields in [file_name] but will
   skip the version field. You'll need to edit that manually or temporarily
   disable the skill protection.

Which approach would you prefer?

请求大范围重构时

📋 Release-Please Files Detected

I've identified several release-please managed files in the scope of this
refactoring:

**Protected files found:**
- plugins/dotfiles-core/CHANGELOG.md (hard block)
- plugins/dotfiles-toolkit/.claude-plugin/plugin.json (version field)
- [other files...]

**My approach:**
✅ I'll refactor all other files as requested
⚠️ I'll skip protected files and explain why
📝 I'll provide a summary of skipped changes

**If you need version/changelog updates:**
I'll generate appropriate conventional commit messages that will trigger
release-please to make those changes automatically.

Should I proceed with this approach?

Conventional Commit 指南

此技能会根据更改类型即时提供 Conventional Commit 模板：

添加功能

feat(scope): brief description

Detailed explanation of what was added and why.
Can be multiple paragraphs.

Refs: #issue-number

修复错误

fix(scope): brief description

Explanation of the bug and how it was fixed.

Fixes: #issue-number

破坏性更改

feat(scope)!: brief description

BREAKING CHANGE: Explanation of what breaks and migration path.

Details about the new behavior.

Refs: #issue-number

杂项（不升级版本）

chore(scope): brief description

Maintenance work that doesn't affect functionality.
Examples: dependency updates, refactoring, docs.

与其他技能集成

此技能会与以下技能协同工作：

• Chezmoi Expert - 确保 dotfiles 模板不会手动编辑版本
• Git Workflow - 在创建 PR 前强制使用 Conventional Commit
• GitHub Actions - 了解 release-please 工作流配置

技能配置

位于 dot_claude/skills/release-please-protection/（源目录）；chezmoi apply 后会变为 ~/.claude/skills/release-please-protection/：

• SKILL.md - 此文件（技能定义）
• patterns.md - 受保护文件模式参考
• workflow.md - release-please 工作流详细指南

限制

此技能无法阻止的情况

1. 明确覆盖限制 - 即使收到警告，仍明确指示我进行编辑
2. 上下文之外的文件 - 不在当前上下文窗口中的文件
3. 外部工具 - sed、awk 或直接使用 bash 编辑等命令
4. Git 操作 - 手动使用 git commit 提交已修改的受保护文件

此技能可以阻止的情况

1. 意外编辑 - 及时发现并阻止错误
2. 违反工作流 - 说明正确的 release-please 模式
3. 合并冲突 - 避免自动化 PR 冲突
4. 版本不一致 - 保持语义化版本管理规范

紧急覆盖

如果确实必须手动编辑受保护文件：

临时权限覆盖

# 1. Edit global settings
vim ~/.claude/settings.json

# 2. Comment out deny rules
"deny": [
  "Bash(git add .)",
  "Bash(git add -A)",
  "Bash(git add --all)",
  // "Edit(**/CHANGELOG.md)",
  // "Write(**/CHANGELOG.md)",
  // "MultiEdit(**/CHANGELOG.md)"
]

# 3. Make your edits

# 4. Re-enable protection (uncomment the lines)

# 5. Verify with chezmoi
chezmoi diff ~/.claude/settings.json
chezmoi apply  # If template is out of sync

技能绕过（不推荐）

# Temporarily disable skill
mv .claude/skills/release-please-protection .claude/skills/release-please-protection.disabled

# Make edits

# Re-enable
mv .claude/skills/release-please-protection.disabled .claude/skills/release-please-protection

成功指标

当满足以下条件时，说明此技能运行正常：

✅ 所有编辑 CHANGELOG.md 的尝试都被拦截，并附有有帮助的说明 ✅ 修改版本字段时会触发警告并提供替代方案 ✅ 常规提交建议与请求的更改相符 ✅ 用户在收到首次警告后能理解 release-please 工作流 ✅ 不会与自动创建的发布 PR 发生合并冲突 ✅ 版本号始终遵循语义化版本规范

延伸阅读

• 完整的受保护文件模式列表请参见 patterns.md
• release-please 工作流的详细文档请参见 workflow.md
• Release-please 文档：https://github.com/googleapis/release-please
• 常规提交规范：https://www.conventionalcommits.org/