release-please

What this skill does

# release-please

## Overview

[release-please](https://github.com/googleapis/release-please) automates versioning and releases by analyzing Conventional Commit messages:

1. **Push** conventional commits to your default branch
2. **release-please creates/updates a Release PR** with version bump and changelog
3. **Merge** the Release PR to trigger a GitHub Release
4. **Publish** step runs when a release is created (npm, PyPI, crates.io, etc.)

release-please handles version determination, changelog generation, and git tagging. You write good commit messages; it does the rest.

## Commit Message Assistance

When a user asks for help writing a commit message (not setting up a pipeline):

1. **Ask what changed** — "What did you change and why?" (skip if already described)
2. **Suggest the type** — Pick from the type table below, explain why that type fits
3. **Draft the message** — Write the full commit message (header + body if needed + footers)
4. **Confirm** — Present it for the user to approve or adjust

If the change is breaking, always include a `BREAKING CHANGE:` footer explaining migration impact.

## Pipeline Setup Flow

When a user wants to set up release-please, follow this interactive protocol.

If `.github/workflows/release.yml` (or similar) already exists, read it first, compare against the templates in `references/workflow-templates.md`, and suggest specific improvements rather than replacing it wholesale. Common improvement opportunities: missing concurrency groups, publish not gated on `release_created`, missing idempotent publish check, overly broad permissions.

### Step 1: Detect Project Type

Scan the repository for package manifests:

| File | Release Type |
|------|-------------|
| `package.json` | `node` |
| `pyproject.toml` / `setup.py` | `python` |
| `pom.xml` | `java` |
| `go.mod` | `go` |
| `Cargo.toml` | `rust` |
| `*.gemspec` | `ruby` |
| `composer.json` | `php` |
| `pubspec.yaml` | `dart` |
| `mix.exs` | `elixir` |
| `Chart.yaml` | `helm` |

If multiple manifests exist at the root, ask which is primary. If none found, use `simple`.

### Step 2: Ask Configuration Questions

Ask these questions (skip any already answered or obvious from context):

1. **Is this a monorepo?** (multiple packages in subdirectories)
2. **What is the default branch?** (default: `main`)
3. **Do you need pre-release support?** (manual alpha/beta/rc releases)
4. **Where do you publish?** (npm, GitHub Packages, PyPI, Maven Central, crates.io, Docker, none)
5. **What is the current version?** (check package manifest, default: `0.0.0`)

### Step 3: Generate Files

Create three files based on the answers:

#### release-please-config.json

```json
{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "draft": false,
      "prerelease": false,
      "versioning": "default",
      "extra-files": []
    }
  }
}
```

Adjust `release-type` based on detected project type. For monorepos, add multiple entries under `packages` with `component` names.

#### .release-please-manifest.json

```json
{
  ".": "1.0.0"
}
```

Set to the current released version. Use `"0.0.0"` for new projects.

#### .github/workflows/release.yml

For **Node.js → npm public registry** (most common), use this base template:

```yaml
name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
      version: ${{ steps.release.outputs.version }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release

  publish:
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

For **other ecosystems**, see `references/workflow-templates.md` for complete templates including:
- Node.js → GitHub Packages (with idempotent publish check)
- Python → PyPI (trusted publishers)
- Java → Maven Central
- Go (tags only, optional GoReleaser)
- Rust → crates.io
- Docker (build + push with semver tags)
- Monorepo (per-package publish jobs)
- Pre-release pattern (workflow_dispatch with version resolution)

**Always customize:**
- Replace `main` with the actual default branch if different
- Adjust Node version, Python version, Java version, etc.
- Add registry-specific secrets configuration
- If pre-release support is needed, use the pre-release template from `references/workflow-templates.md`

## Configuration Quick Reference

| Option | Default | Purpose |
|--------|---------|---------|
| `release-type` | — | Package ecosystem (required) |
| `bump-minor-pre-major` | `false` | Treat `feat` as patch when < 1.0.0 |
| `changelog-path` | `CHANGELOG.md` | Where to write the changelog |
| `include-v-in-tag` | `true` | Tag as `v1.2.3` vs `1.2.3` |
| `separate-pull-requests` | `false` | One PR per package (monorepo) |
| `draft` | `false` | Create release PRs as drafts |
| `extra-files` | `[]` | Additional files with version strings to update |
| `changelog-sections` | (defaults) | Customize which types appear in changelog |

### Monorepo Quick Setup

```json
// release-please-config.json
{
  "packages": {
    "packages/core": { "release-type": "node", "component": "core" },
    "packages/cli": { "release-type": "node", "component": "cli" }
  }
}
```

```json
// .release-please-manifest.json
{ "packages/core": "0.0.0", "packages/cli": "0.0.0" }
```

Use component names as commit scopes: `feat(core): add streaming support`

For full configuration options, see `references/config-options.md`.

## Commit Message Guide

release-please reads commit messages to determine version bumps and generate changelogs. Every commit to the default branch must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).

### Format

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

[optional body]

[optional footer(s)]
```

- Use imperative present tense: "add" not "added"
- Do not capitalize the first letter of the description
- Do not end with a period

### Type → Version Bump

| Type | Bump | Triggers Release? |
|------|------|-------------------|
| `feat` | Minor | Yes |
| `fix` | Patch | Yes |
| `deps` | Patch | Yes |
| `refactor` | — | No |
| `perf` | — | No |
| `test` | — | No |
| `docs` | — | No |
| `style` | — | No |
| `chore` | — | No |
| `build` | — | No |
| `ci` | — | No |

**Breaking changes** (any type with `!` or `BREAKING CHANGE:` footer) → **Major** bump.

### Breaking Change Examples

```
feat(api)!: redesign authentication flow

BREAKING CHANGE: /auth/login now requires OAuth2 tokens instead of API keys.
```

```
refactor(database): migrate from MongoDB to PostgreSQL

BREAKING CHANGE: all database connection strings must be updated.
```

### Special Footers

| Footer | Purpose |
|--------|---------|
| `BREAKING CHANGE: <desc>` | Triggers major version bump |
| `Release-As: x.x.x` | Force a specific version number |

### Quick Examples

```
feat(booking): add search by date range endpoint
fix(auth): resolve token refresh race condition
deps: upgrade @nestjs/core to v11.0.0
test(scheduler): add unit tests for cron parser
chore: update .gitignore
```

### No AI Co-Author Trailers

**NEVER add `Co-Authored-By` trailers for AI agents** in co