Release Please Protection

Release-Please Protection

Automatically detects and prevents manual edits to release-please managed files across all projects.

Overview

This skill provides proactive detection and warnings for files managed by Google's release-please automation tool. It helps prevent merge conflicts and workflow disruptions by identifying problematic edit attempts before they occur.

When This Skill Activates

The skill automatically activates in these scenarios:

1. Direct edit requests to protected files 2. User mentions of version bumps, releases, or changelog updates 3. Broad refactoring that might touch version-controlled files 4. Documentation updates that could include CHANGELOG.md 5. "Fix all issues" or similar sweeping requests

Protected Files

Hard Protection (Permission System)

These files are completely blocked from editing by Claude Code's permission system:

• **/CHANGELOG.md - All changelog files in any location

Operations blocked: Edit, Write, MultiEdit Operations allowed: Read (for analysis and context)

Soft Protection (Skill Detection)

These files trigger warnings and suggestions before edits:

Package Manager Manifests (Version Fields)

• 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 plugins)
• pom.xml → <version>x.y.z</version> (Maven/Java)
• build.gradle → version = 'x.y.z' (Gradle)
• pubspec.yaml → version: x.y.z (Dart/Flutter)

Why soft protection? Claude Code's permission system operates at the file level, not field level. Blocking entire manifest files would prevent legitimate dependency updates via automated tools (npm, cargo, uv, etc.).

Detection Logic

Before attempting any edit, the skill checks:

1. File Path Analysis

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

2. Content Pattern Matching

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. Intent Recognition

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

Response Templates

When CHANGELOG.md Edit Attempted

⚠️ 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

When Version Field Edit Detected

⚠️ 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?

When Broad Refactoring Requested

📋 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 Guide

The skill provides instant conventional commit templates based on the type of change:

Feature Addition

feat(scope): brief description

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

Refs: #issue-number

Bug Fix

fix(scope): brief description

Explanation of the bug and how it was fixed.

Fixes: #issue-number

Breaking Change

feat(scope)!: brief description

BREAKING CHANGE: Explanation of what breaks and migration path.

Details about the new behavior.

Refs: #issue-number

Chore (No Version Bump)

chore(scope): brief description

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

Integration with Other Skills

This skill works alongside:

• Chezmoi Expert - Ensures dotfiles templates don't manually edit versions
• Git Workflow - Enforces conventional commits before creating PRs
• GitHub Actions - Aware of release-please workflow configurations

Skill Configuration

Located in dot_claude/skills/release-please-protection/ (source) which becomes ~/.claude/skills/release-please-protection/ after chezmoi apply:

• SKILL.md - This file (skill definition)
• patterns.md - Protected file pattern reference
• workflow.md - Detailed release-please workflow guide

Limitations

What This Skill Cannot Prevent

1. Explicit overrides - If you explicitly instruct me to edit despite warnings 2. Out-of-context files - Files not in the current context window 3. External tools - Commands like sed, awk, or direct bash edits 4. Git operations - Manual git commit with modified protected files

What This Skill DOES Prevent

1. Accidental edits - Catching mistakes before they happen 2. Workflow violations - Explaining proper release-please patterns 3. Merge conflicts - Preventing automated PR conflicts 4. Version inconsistencies - Maintaining semantic versioning discipline

Emergency Overrides

If you absolutely must manually edit protected files:

Temporary Permission Override

# 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

Skill Bypass (Not Recommended)

# 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

Success Metrics

This skill is working properly when:

✅ All CHANGELOG.md edit attempts are blocked with helpful explanations ✅ Version field modifications trigger warnings and alternatives ✅ Conventional commit suggestions match the requested changes ✅ Users understand the release-please workflow after first warning ✅ No merge conflicts occur with automated release PRs ✅ Version numbers follow semantic versioning consistently

Further Reading

• See patterns.md for complete list of protected file patterns
• See workflow.md for detailed release-please workflow documentation
• Release-please docs: https://github.com/googleapis/release-please
• Conventional commits: https://www.conventionalcommits.org/

Protected File Patterns Reference

Comprehensive reference of file patterns managed by release-please automation.

Hard Protection (Permission System Blocks)

These files are completely blocked from Edit/Write/MultiEdit operations via Claude Code's permission system in ~/.claude/settings.json:

CHANGELOG Files

Pattern: **/CHANGELOG.md
Regex:   .*CHANGELOG\.md$

Locations in dotfiles:

• /Users/lgates/.local/share/chezmoi/plugins/dotfiles-core/CHANGELOG.md
• /Users/lgates/.local/share/chezmoi/plugins/dotfiles-toolkit/CHANGELOG.md
• Any future plugin CHANGELOG.md files

Protection Level: HARD (cannot be bypassed by Claude) Read Access: Allowed (for analysis) Why Protected: Release-please generates these from conventional commits

Soft Protection (Skill Detection & Warning)

These files trigger warnings when version fields are modified:

Node.js / npm

File: package.json

Version Pattern:

{
  "version": "1.2.3",
  ...
}

Detection Regex: "version"\s*:\s*"[\d]+\.[\d]+\.[\d]+"

Other Protected Fields (if present):

• None - only version field is release-please managed

Safe to Edit:

• dependencies, devDependencies
• scripts
• name, description, keywords
• All other fields

---

Python / uv / pip

File: pyproject.toml

Version Pattern:

[project]
version = "0.2.0"

Detection Regex: ^\s*version\s*=\s*"[\d]+\.[\d]+\.[\d]+"

Example Location:

• /Users/lgates/.local/share/chezmoi/plugins/dotfiles-ui-hooks/hooks/voice-notify/pyproject.toml

Safe to Edit:

• [project.dependencies]
• [project.optional-dependencies]
• [build-system]
• name, description, authors
• All other fields

---

Rust / Cargo

File: Cargo.toml

Version Pattern:

[package]
name = "my-crate"
version = "0.1.0"

Detection Regex: ^\s*version\s*=\s*"[\d]+\.[\d]+\.[\d]+"

Safe to Edit:

• [dependencies]
• [dev-dependencies]
• [[bin]], [lib]
• authors, description, license
• All other fields

---

Claude Code Plugins

File: .claude-plugin/plugin.json

Version Pattern:

{
  "name": "dotfiles-core",
  "version": "3.0.0",
  ...
}

Detection Regex: "version"\s*:\s*"[\d]+\.[\d]+\.[\d]+"

Example Locations:

• /Users/lgates/.local/share/chezmoi/plugins/dotfiles-core/.claude-plugin/plugin.json
• /Users/lgates/.local/share/chezmoi/plugins/dotfiles-toolkit/.claude-plugin/plugin.json
• /Users/lgates/.local/share/chezmoi/plugins/*/. claude-plugin/plugin.json

Safe to Edit:

• displayName, description
• publisher, categories
• agents, commands, skills
• All other fields

---

Maven / Java

File: pom.xml

Version Pattern:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0.0</version>
</project>

Detection Regex: <version>[\d]+\.[\d]+\.[\d]+</version>

Safe to Edit:

• <dependencies>
• <build>, <plugins>
• <properties>
• All other elements

---

Gradle / Kotlin

File: build.gradle or build.gradle.kts

Version Pattern:

version = '1.0.0'

Detection Regex: version\s*=\s*['"][\d]+\.[\d]+\.[\d]+['"]

Safe to Edit:

• dependencies { }
• plugins { }
• repositories { }
• All other blocks

---

Dart / Flutter

File: pubspec.yaml

Version Pattern:

name: my_app
version: 1.0.0+1

Detection Regex: ^version:\s*[\d]+\.[\d]+\.[\d]+

Safe to Edit:

• dependencies:
• dev_dependencies:
• flutter:, assets:
• All other fields

---

Marketplace Registry

File: .claude-plugin/marketplace.json

Pattern: Contains version references for all registered plugins

Protection Level: SOFT (version references only)

Why: This file aggregates plugin versions and shouldn't be manually edited as release-please updates it via plugin updates

---

Release Workflow Files

Potential Files (if present):

• .github/workflows/release-please.yml
• .github/workflows/release.yml
• .release-please-config.json
• .release-please-manifest.json

Protection: Skill warns when editing these to ensure workflow integrity

Safe to Edit:

• Workflow trigger conditions
• Additional CI steps
• Notification configurations

Unsafe to Edit:

• release-please action versions
• Manifest configuration paths
• Release type configurations (without understanding impact)

---

Detection Strategy by Request Type

"Update dependencies"

• ✅ Allow: editing dependencies sections
• ⚠️ Warn: if version field is in diff
• 🛑 Block: CHANGELOG.md modifications

"Bump version to X.Y.Z"

• ⚠️ Intercept: suggest conventional commit instead
• 📚 Explain: release-please workflow
• 🔧 Offer: create conventional commit template

"Fix all linting issues"

• ✅ Allow: most file modifications
• ⚠️ Skip: version fields if touched
• 🛑 Block: CHANGELOG.md formatting

"Refactor codebase"

• ✅ Allow: code file modifications
• ⚠️ Warn: if package manifests in scope
• 🛑 Block: CHANGELOG.md, explain workaround

"Update documentation"

• ✅ Allow: README.md, docs/ folder
• 🛑 Block: CHANGELOG.md modifications
• 💡 Suggest: include in PR description instead

---

Pattern Matching Priority

When detecting protected files, use this priority order:

1. Exact filename match (highest priority)

• CHANGELOG.md → Hard block

2. Extension + content pattern

• .json + "version": → Check if package.json or plugin.json

3. Path pattern

• **/.claude-plugin/plugin.json → Plugin manifest
• **/pyproject.toml → Python project

4. Content-only pattern (lowest priority)

• Any file with version field regex → Soft warn

---

False Positive Handling

Some files may contain version-like strings but aren't managed by release-please:

Safe Version References

• package-lock.json (auto-generated, safe to regenerate)
• Cargo.lock (auto-generated, safe to regenerate)
• uv.lock (auto-generated, safe to regenerate)
• VERSION.txt (if not in release-please config)
• Documentation examples with version numbers
• Test fixtures with hardcoded versions

Detection Heuristic

if file ends with ".lock" or "-lock.json":
    → Skip version field detection
if file in docs/ or examples/ or tests/:
    → Lower warning severity
if version number in comment or string literal:
    → Context-dependent (check if it's a config value)

---

Regex Patterns Summary

For implementation reference:

# CHANGELOG.md (hard block)
.*CHANGELOG\.md$

# package.json version
"version"\s*:\s*"[\d]+\.[\d]+\.[\d]+(-.+)?"

# pyproject.toml version
^\s*version\s*=\s*"[\d]+\.[\d]+\.[\d]+(-.+)?"

# Cargo.toml version
^\s*version\s*=\s*"[\d]+\.[\d]+\.[\d]+(-.+)?"

# pom.xml version
<version>[\d]+\.[\d]+\.[\d]+(-.+)?</version>

# build.gradle version
version\s*=\s*['"][\d]+\.[\d]+\.[\d]+(-.+)?['"]

# pubspec.yaml version
^version:\s*[\d]+\.[\d]+\.[\d]+(\+\d+)?

# plugin.json version (same as package.json)
"version"\s*:\s*"[\d]+\.[\d]+\.[\d]+(-.+)?"

Note: Patterns include optional pre-release suffixes (-alpha, -beta.1, etc.) and build metadata.

---

Testing Protection

To verify patterns are working:

# Test CHANGELOG.md hard block
echo "test" >> CHANGELOG.md  # Should be blocked by permission system

# Test version field detection (skill should warn)
# Via Claude: "Update the version in package.json to 2.0.0"

# Test conventional commit suggestion
# Via Claude: "Bump the version for a new feature"

---

Customization

To add additional protected patterns:

1. For hard blocks: Edit ~/.claude/settings.json deny rules 2. For soft blocks: Update this patterns.md file with new detection logic 3. For custom workflows: Extend SKILL.md response templates

---

Pattern Maintenance

This patterns reference should be updated when:

• New package managers are added to your projects
• Claude Code introduces new manifest types
• Release-please adds support for new file formats
• Project structure changes significantly
• False positives/negatives are discovered

Last updated: 2025-10-29 Maintained by: Dotfiles release-please-protection skill

Release-Please Workflow Guide

Complete guide to using Google's release-please automation for version management and changelog generation.

What is Release-Please?

Release-please is a GitHub Action that:

• Automatically generates CHANGELOGs from conventional commit messages
• Determines version bumps based on commit types (semver)
• Creates release PRs with all changes grouped together
• Tags releases when the PR is merged
• Publishes packages to registries (if configured)

Key benefit: Zero manual intervention for version management and changelog updates.

---

The Problem With Manual Edits

Why Manual CHANGELOG.md Edits Fail

You: edit CHANGELOG.md manually
Release-please: creates PR updating CHANGELOG.md automatically

Result: MERGE CONFLICT 💥

GitHub blocks the PR because:
- Both changes modify the same file
- Release-please can't auto-merge
- You must manually resolve conflicts
- Your manual entry might be duplicated or lost

Why Manual Version Bumps Fail

You: change version in package.json from 1.0.0 → 1.1.0
Release-please: analyzes commits, determines version should be 1.0.1

Result: VERSION MISMATCH 💥

Consequences:
- Release-please overwrites your manual bump
- Version history becomes inconsistent
- Semantic versioning is violated
- Dependency tracking breaks

---

The Correct Workflow

Step 1: Make Your Changes

Work normally - write code, fix bugs, add features:

# Make your changes
vim src/auth.ts

# Stage changes
git add src/auth.ts

Step 2: Write a Conventional Commit

Use conventional commit format to describe your change:

git commit -m "feat(auth): add OAuth2 support

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

Refs: #42"

Conventional commit format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Step 3: Push to Remote

git push origin main
# or push to feature branch and create PR

Step 4: Release-Please Activates

After your commit is merged to main branch:

1. Release-please analyzes new commits since last release 2. Determines version bump based on commit types:

• feat: → minor version bump (1.0.0 → 1.1.0)
• fix: → patch version bump (1.0.0 → 1.0.1)
• feat!: or BREAKING CHANGE: → major version bump (1.0.0 → 2.0.0)
• chore:, docs:, style: → no version bump

3. Creates or updates a release PR containing:

• CHANGELOG.md with new entries
• package.json (or equivalent) with new version
• All other version-managed files updated

Step 5: Review the Release PR

Release-please creates a PR like:

Title: chore(main): release 1.1.0

Changes:
- CHANGELOG.md: added entries for new features
- package.json: version bumped from 1.0.0 → 1.1.0
- Cargo.toml: version bumped from 1.0.0 → 1.1.0

What you should review:

• ✅ Version number is correct for the changes
• ✅ CHANGELOG entries accurately describe commits
• ✅ All version files are updated consistently
• ✅ No unexpected changes included

Step 6: Merge the Release PR

# Via GitHub UI: click "Merge pull request"
# Or via CLI:
gh pr merge <PR-number> --squash

Step 7: Release-Please Creates Tagged Release

After merge:

• 📦 Creates Git tag (e.g., v1.1.0)
• 🎉 Creates GitHub Release with CHANGELOG notes
• 🚀 Triggers any publish workflows (npm, crates.io, etc.)

---

Conventional Commit Types

feat: - New Feature (Minor Version Bump)

Adds new functionality visible to users.

Example:

git commit -m "feat(api): add user profile endpoints

Implements GET/POST/PUT/DELETE operations for user profiles.
Includes validation and error handling.

Refs: #123"

Version impact: 1.2.3 → 1.3.0

Use when:

• Adding new API endpoints
• Implementing new user-facing features
• Adding new configuration options
• Expanding capabilities

---

fix: - Bug Fix (Patch Version Bump)

Fixes incorrect behavior without adding new features.

Example:

git commit -m "fix(auth): prevent token refresh race condition

Fixes issue where multiple concurrent requests could
trigger simultaneous token refreshes, causing 401 errors.

Fixes: #456"

Version impact: 1.2.3 → 1.2.4

Use when:

• Fixing bugs
• Resolving security vulnerabilities
• Correcting incorrect behavior
• Patching edge cases

---

feat!: or BREAKING CHANGE: - Breaking Change (Major Version Bump)

Changes that break backwards compatibility.

Example:

git commit -m "feat(api)!: redesign authentication flow

BREAKING CHANGE: The authentication endpoint now requires
OAuth2 instead of API keys. Users must migrate their
integrations to use the new /oauth/token endpoint.

Migration guide: docs/migration/v2.md

Refs: #789"

Version impact: 1.2.3 → 2.0.0

Use when:

• Removing public APIs
• Changing API signatures
• Modifying configuration schemas
• Requiring new dependencies

---

chore: - Maintenance (No Version Bump)

Internal changes that don't affect users.

Example:

git commit -m "chore(deps): update development dependencies

Updates test frameworks and linting tools to latest versions.
No user-facing changes."

Version impact: No change

Use when:

• Updating dev dependencies
• Refactoring internal code
• Updating CI/CD configs
• Improving build processes

---

Other Types (No Version Bump)

• docs: - Documentation only changes
• style: - Code style/formatting (no logic changes)
• refactor: - Code refactoring (no behavior change)
• perf: - Performance improvements (if no breaking changes)
• test: - Adding or updating tests
• build: - Build system changes
• ci: - CI/CD configuration changes

---

Scope Guidelines

The <scope> is optional but helps organize changelogs:

Good scopes:

• (auth) - Authentication system
• (api) - API endpoints
• (cli) - Command-line interface
• (ui) - User interface
• (db) - Database layer
• (plugin-core) - Core plugin for Claude Code

Avoid:

• Generic scopes like (misc), (stuff)
• File names like (index.js)
• Too specific like (line-47-fix)

---

Multi-Paragraph Commit Messages

For complex changes, use detailed commit messages:

git commit -m "feat(plugins): add plugin marketplace support

Implements local plugin marketplace for Claude Code plugins.
Users can now distribute plugins via directory-based marketplaces.

Key features:
- Plugin manifest schema with versioning
- Marketplace registration in settings.json
- Automatic plugin discovery and loading
- Version conflict resolution

Technical notes:
- Uses plugin.json schema v1.0
- Marketplace path can be relative or absolute
- Supports nested plugin directories

Refs: #101, #102
Co-authored-by: AI Assistant <ai@example.com>"

This generates detailed CHANGELOG entries.

---

Working with Multiple Commits

Release-please groups all commits since the last release:

Last release: v1.0.0

Commits since then:
1. feat(auth): add OAuth2           → Triggers 1.1.0
2. fix(auth): handle edge case      → Already triggering 1.1.0
3. docs: update README              → No version bump
4. feat(api): add webhooks          → Still 1.1.0 (not 1.2.0)

Result: One release PR with v1.1.0

Release-please creates ONE release PR containing all changes.

If you want separate releases:

# Option 1: Merge release PR after each feature
git commit -m "feat(auth): add OAuth2"
git push
# Wait for release PR, merge it
# Now next feature gets its own release

# Option 2: Use release branches (advanced)
# Configure release-please to track multiple branches

---

Handling Edge Cases

Emergency Hotfix (Skip Normal Process)

Sometimes you need to release immediately:

# 1. Make critical fix
git commit -m "fix(security): patch CVE-2024-12345

Critical security fix for XSS vulnerability.

GHSA-xxxx-yyyy-zzzz"

# 2. Push to main
git push origin main

# 3. Manually trigger release workflow (if configured)
gh workflow run release-please.yml

# 4. Merge release PR immediately
# 5. Wait for tagged release and deployment

Or manually bump if release-please is blocked:

# Only use this if release-please is completely broken

# 1. Comment out CHANGELOG.md deny rules in ~/.claude/settings.json
# 2. Manually edit version and CHANGELOG.md
# 3. Commit as chore: (won't trigger release-please)
git commit -m "chore(release): emergency hotfix v1.0.1"
# 4. Push and tag manually
git tag v1.0.1
git push origin main --tags
# 5. Restore deny rules

Sync Drift (Manual Edit Was Made)

If someone manually edited version/CHANGELOG:

# 1. Pull latest changes
git pull origin main

# 2. Check release-please PR
gh pr view <release-PR-number>

# 3. If conflicts exist:
gh pr checkout <release-PR-number>

# 4. Resolve conflicts preferring release-please changes
git checkout --theirs CHANGELOG.md package.json
git add CHANGELOG.md package.json
git commit -m "chore: resolve release-please conflicts"
git push

# 5. Merge release PR
gh pr merge <release-PR-number>

# 6. Future: prevent manual edits via this skill

Force Version Bump (Override Semantic Versioning)

Release-please usually determines versions automatically, but you can override:

Method 1: Config file (.release-please-config.json)

{
  "packages": {
    ".": {
      "release-type": "simple",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "version": "2.0.0"  // Forces next release to be 2.0.0
    }
  }
}

Method 2: Commit message footer

git commit -m "feat(api): add new endpoints

Release-As: 2.0.0"

Use sparingly - defeats the purpose of automation.

---

Multi-Package Repositories (Monorepos)

If you have multiple packages in one repo:

.release-please-config.json:

{
  "packages": {
    "plugins/dotfiles-core": {
      "release-type": "simple",
      "package-name": "dotfiles-core",
      "changelog-path": "CHANGELOG.md"
    },
    "plugins/dotfiles-toolkit": {
      "release-type": "simple",
      "package-name": "dotfiles-toolkit",
      "changelog-path": "CHANGELOG.md"
    }
  }
}

Commits specify package:

# Scoped commits determine which package releases
git commit -m "feat(dotfiles-core): add new agent"
# Only dotfiles-core gets a release

git commit -m "feat(dotfiles-toolkit): update command"
# Only dotfiles-toolkit gets a release

git commit -m "feat: update shared configuration"
# Affects all packages (root release)

---

Debugging Release-Please

Check workflow runs:

gh run list --workflow=release-please.yml
gh run view <run-id> --log

Verify configuration:

cat .release-please-config.json
cat .release-please-manifest.json

Test commit parsing:

# Check if commits follow conventional format
git log --oneline | head -10

# View release-please PR if it exists
gh pr list --label "autorelease: pending"

Common issues:

No release PR created:

• Check if commits follow conventional format
• Verify workflow file exists (.github/workflows/release-please.yml)
• Check workflow permissions (needs write access to PRs)
• Look for errors in workflow runs

Wrong version bump:

• Review commit messages - type determines bump
• Check for accidental BREAKING CHANGE footers
• Verify release-please config for overrides

CHANGELOG.md conflicts:

• Someone manually edited CHANGELOG.md
• Merge release PR and resolve conflicts favoring release-please version
• Enable this protection skill to prevent future manual edits

---

Best Practices

✅ Do This

• Write clear, descriptive commit messages
• Use appropriate conventional commit types
• Group related changes in single commits
• Review release PRs before merging
• Keep commits atomic (one logical change each)
• Use multi-paragraph messages for complex changes

❌ Don't Do This

• Manually edit CHANGELOG.md
• Manually bump version numbers
• Use generic commit messages ("fix stuff")
• Mix breaking and non-breaking changes in one commit
• Bypass conventional commit format
• Edit release PRs after creation (let release-please regenerate)

---

Integration with Claude Code

This skill enforces proper workflow by:

1. Blocking CHANGELOG.md edits via permission system 2. Warning on version field modifications before they happen 3. Suggesting conventional commits when version bumps requested 4. Providing commit templates matching user intent 5. Explaining conflicts when automation fails

When Claude suggests conventional commits:

You: "Bump version to add new authentication feature"

Claude (this skill):
⚠️ Instead of manually bumping the version, I'll help you create
a conventional commit that will trigger release-please to bump
the version automatically.

Suggested commit:
---
feat(auth): add OAuth2 authentication support

Implements OAuth2 2.0 authentication flow with PKCE.
Supports authorization code grant with refresh tokens.

Features:
- Token refresh handling
- Session management
- Secure state validation

Refs: #issue-number
---

This will trigger a minor version bump (X.Y.0) when merged.
Would you like me to create this commit?

---

Further Resources

• Release-Please Documentation: https://github.com/googleapis/release-please
• Conventional Commits Spec: https://www.conventionalcommits.org/
• Semantic Versioning: https://semver.org/
• GitHub Actions Integration: https://github.com/googleapis/release-please/tree/main/docs
• Config Schema: https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md

---

Last updated: 2025-10-29 Part of: release-please-protection skill for Claude Code