Changelog Automation#

The repository uses chloggen to manage release notes. Contributors add individual YAML files to .chloggen/ for every PR; these are validated, previewed, and then collapsed into CHANGELOG.md at release time via make chlog-update.

How It Works#

The chloggen config maps the user category to CHANGELOG.md and defaults all entries to that category.

The Makefile defines CHLOGGEN and CHLOGGEN_CONFIG, with the four targets at lines 132–147.

CI Enforcement#

The .github/workflows/changelog.yml workflow runs on every PR to main or release/* branches and enforces two rules 1:

1. No direct edits to CHANGELOG.md or CHANGELOG-API.md.
2. At least one .chloggen/*.yaml addition per PR.

Both checks are skipped when any of the following conditions are true 2:

• The PR carries the dependencies label
• The PR carries the Skip Changelog label
• The PR title contains [chore]

The dependabot[bot] actor is also excluded entirely via a job-level if condition 3.

The Renovate Bypass Gap (Resolved)#

renovate.json automatically labels every Renovate-created PR with renovatebot and dependencies. Because the changelog workflow skips the chloggen check for any PR labeled dependencies, all Renovate bumps silently bypassed the requirement 2 4.

This was intentional for ordinary transitive Go module upgrades, but created a coverage gap for user-visible bundled components like OBI (eBPF Instrumentation), whose version directly controls the eBPF instrumentation behavior shipped in otelcol-contrib.

Concrete Example: v0.160.0 OBI Drift#

This gap produced a documented, confirmed bug in v0.160.0 5:

1. PR #1615 (Aug 19) bumped OBI v0.10.0 → v0.11.0 and added a chloggen entry referencing the original PR #1604.
2. PR #1622 (Aug 25, Renovate) bumped OBI v0.11.0 → v0.12.2 in distributions/otelcol-contrib/manifest.yaml — no .chloggen/ entry was created.
3. v0.160.0 was cut on Sep 2 with the stale v0.11.0 line still in CHANGELOG.md.

The manifest is the authoritative source for the compiled OBI version: scripts/prepare-obi.sh reads the version directly from the manifest.yaml gomod line and downloads the matching release tarball 5. The CHANGELOG entry, however, came from the earlier chloggen YAML file and was never updated. The net effect: otelcol-contrib:0.160.0 shipped OBI v0.12.2 while the release notes advertised v0.11.0 — a two-minor-version undocumented jump 5.

Known Gaps and Proposed Fixes#

The root cause was structural: the dependencies label exemption treated all Renovate PRs identically, regardless of whether the bumped package was an internal Go dep or a user-facing component 5.

OBI bypass#

This gap has been resolved as of PR #1638. The fix implements the selective chloggen requirement approach: a packageRules entry in renovate.json now removes the dependencies label from OBI update PRs (matching go.opentelemetry.io/obi), keeping only the renovatebot label. This forces the changelog check for OBI bumps: Renovate will open the PR, but the Changelog workflow will fail until a maintainer adds a .chloggen/ entry or applies the Skip Changelog label. The red check makes it impossible to merge the PR unnoticed.

Considered alternatives (from issue #1636):

• Source-of-truth approach: Generate release notes that read the OBI version directly from manifest.yaml, so the version in the changelog is always derived from the same file that drives the build — eliminating the possibility of drift.
• Manual process: Require maintainers to add a .chloggen/ entry when merging Renovate PRs that affect user-visible components.

Key Files#