Skip to content

What Release-Please Can't Do

I wanted to version CONTRIBUTING.md independently from the main project. Separate changelog. Separate release cycle. Separate tags.

Release-please said no.

The Goal

The Scenario

Our CONTRIBUTING.md lives in a central repository and gets distributed to 75+ other repos.

When we update the guidelines, we wanted:

  1. A dedicated changelog for contribution guideline changes
  2. Tags like contributing-1.0.0, contributing-1.1.0
  3. Independent versioning from the main platform

This seemed reasonable. Release-please supports monorepo configurations with multiple packages. Why not add CONTRIBUTING.md as a package?

The Attempt

{
  "packages": {
    ".": {
      "release-type": "simple",
      "component": "platform"
    },
    "contributing": {
      "release-type": "simple",
      "component": "contributing-guidelines"
    }
  }
}

Error: contributing is not a directory.

The Discovery

Key Limitation

Release-please packages are directory-based. The path must point to a directory, not a single file.

The configuration path must point to a directory containing versionable files.

From the release-please documentation:

Each package path should be a directory relative to the repository root.

A single file at the repository root cannot be a package. Workarounds like:

  • Creating a contributing/ directory with just the file
  • Using symlinks
  • Nested manifests

All create more problems than they solve.

The Solution

Accept the limitation. Use extra-files instead:

{
  "packages": {
    ".": {
      "release-type": "simple",
      "extra-files": [
        {
          "type": "generic",
          "path": "CONTRIBUTING.md",
          "glob": false
        }
      ]
    }
  }
}

The file gets its version updated alongside the main package. Add the annotation:

---
title: Contributing Guidelines
version: 1.4.2 # x-release-please-version
---

Release-please finds x-release-please-version and updates the number.

What This Means

Want Reality
Independent versioning Shares version with parent package
Separate changelog Changes appear in main changelog
Dedicated tags No separate tags
Per-file release cycle Releases with everything else

For most use cases, this is fine. The file version updates automatically. Distribution workflows can read it. Consumers know which version they have.

If you truly need independent versioning for a single file, you need a different tool or a directory wrapper.

The Changelog Compromise

Even without independent versioning, you can control what appears in changelogs. Hide noise with scope filtering:

{
  "changelog-sections": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "docs", "section": "Documentation" },
    { "type": "chore", "scope": "deps", "section": "Dependencies", "hidden": true },
    { "type": "test", "section": "Tests", "hidden": true },
    { "type": "ci", "section": "CI/CD", "hidden": true }
  ]
}

The scope field targets specific commit patterns. chore(deps): bump lodash gets hidden. chore: update build config appears under Maintenance.

Schema Validation

One more lesson: always validate against the schema.

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
}

I initially tried release-name to customize the release title. The option doesn't exist. It was a hallucination. The schema would have caught it immediately.

When Directory-Based Makes Sense

The limitation exists for good reasons:

  1. Changelogs need location - Where does CHANGELOG.md go for a single file?
  2. Version files need context - package.json, Chart.yaml, version.txt live in directories
  3. Monorepos are directories - Each package is a self-contained unit

Release-please is built for packages, not files. Once I accepted that, the configuration became obvious.

Deep Dive

CONTRIBUTING.md now shares our platform version. It's not what I originally wanted, but it's the right tool for the job.

Comments