release-please-standards

Release-Please Standards

Version: 2025.1

Standard release-please configuration for automated semantic versioning and changelog generation.

Standard Configuration

GitHub Actions Workflow

File: .github/workflows/release-please.yml

name: Release Please

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}

Configuration Files

File: release-please-config.json

{
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-sections": [
        {"type": "feat", "section": "Features"},
        {"type": "fix", "section": "Bug Fixes"},
        {"type": "perf", "section": "Performance"},
        {"type": "deps", "section": "Dependencies"},
        {"type": "docs", "section": "Documentation", "hidden": true},
        {"type": "chore", "section": "Miscellaneous", "hidden": true}
      ]
    }
  },
  "plugins": ["node-workspace"]
}

File: .release-please-manifest.json

{
  ".": "0.0.0"
}

Note: Version 0.0.0 is a placeholder - release-please updates this automatically.

Project Type Variations

Node.js Frontend/Backend

• release-type: node
• plugins: node-workspace
• Updates: package.json version field

Python Service

• release-type: python
• Updates: pyproject.toml version field, __version__ in code

Infrastructure (Helm)

• release-type: helm
• Updates: Chart.yaml version field

Multi-package Repository

{
  "packages": {
    "packages/frontend": {
      "release-type": "node",
      "component": "frontend"
    },
    "packages/backend": {
      "release-type": "node",
      "component": "backend"
    }
  },
  "plugins": [
    "node-workspace",
    {
      "type": "linked-versions",
      "groupName": "workspace",
      "components": ["frontend", "backend"]
    }
  ]
}

Required Components

Minimum Requirements

1. Workflow file: .github/workflows/release-please.yml

   • Uses googleapis/release-please-action@v4
   • Token: MY_RELEASE_PLEASE_TOKEN secret
   • Triggers on push to main

2. Config file: release-please-config.json

   • Valid release-type for project
   • changelog-sections defined

3. Manifest file: .release-please-manifest.json

   • Lists all packages with current versions

Token Configuration

The workflow uses MY_RELEASE_PLEASE_TOKEN secret (not GITHUB_TOKEN) because:

• Allows release PRs to trigger other workflows
• Enables CI checks on release PRs
• Maintains proper audit trail

Compliance Checking

Status Levels

Status	Condition
PASS	All three files present with valid configuration
WARN	Files present but using deprecated action version
FAIL	Missing required files or invalid configuration

Validation Rules

1. Workflow validation:

   • Action version: v4 (warn if older)
   • Token: Must use secret, not hardcoded
   • Trigger: Must include push to main

2. Config validation:

   • release-type: Must be valid (node, python, helm, simple)
   • changelog-sections: Must include feat and fix

3. Manifest validation:

   • Must be valid JSON
   • Packages must match config

Protected Files

IMPORTANT: Release-please manages these files automatically:

• CHANGELOG.md - Never edit manually
• Version fields in package.json, pyproject.toml, Chart.yaml
• .release-please-manifest.json - Only edit for initial setup

See release-please-protection skill for enforcement.

Conventional Commits

Release-please requires conventional commit messages:

Prefix	Release Type	Example
feat:	Minor	feat: add user authentication
fix:	Patch	fix: correct login timeout
feat!:	Major	feat!: redesign API
BREAKING CHANGE:	Major	In commit body

Installation

1. Create workflow file
2. Create config file
3. Create manifest file
4. Add MY_RELEASE_PLEASE_TOKEN to repository secrets
5. Ensure pre-commit has conventional-pre-commit hook

Troubleshooting

Release PR Not Created

• Check conventional commit format
• Verify workflow has correct permissions
• Ensure token has write access

Version Not Updated

• Check manifest file is valid JSON
• Verify release-type matches project
• Review release-please logs in Actions

CI Not Running on Release PR

• Token must be PAT, not GITHUB_TOKEN
• Verify workflow trigger includes pull_request