Skip to content

fix(ci): commit CHANGELOG.md on the first release - #19

Merged
cvega merged 1 commit into
mainfrom
fix/changelog-commit
Jun 14, 2026
Merged

cvega merged 1 commit into
mainfrom
fix/changelog-commit

Conversation

@cvega

@cvega cvega commented Jun 14, 2026

Copy link
Copy Markdown
Owner

What

Fixes the release pipeline's Update CHANGELOG.md job, which silently skipped its commit, and seeds the initial CHANGELOG.md. This is why v0.0.3 produced a published release but no CHANGELOG.md landed on main.

Root cause

The job guarded its commit like this:

if git diff --quiet -- CHANGELOG.md; then
  echo "unchanged — nothing to commit."
else
  git add CHANGELOG.md; git commit ...; git push origin main
fi

git diff --quiet only inspects tracked files. On the first release the freshly generated CHANGELOG.md is untracked, so the check reports "no change" → the else-branch never runs → the file is never committed, yet the step exits 0 (green). It would stay broken on every release until the file became tracked.

Fix

Stage first, then test the staged diff:

git add CHANGELOG.md
if git diff --cached --quiet -- CHANGELOG.md; then
  echo "unchanged — nothing to commit."
else
  git commit ...; git push origin main
fi

git diff --cached --quiet correctly detects a newly-added file. Proven locally on a throwaway repo:

  • old guard on an untracked CHANGELOG.md → "unchanged → SKIP" (the bug)
  • new guard → "changed → COMMIT" (correct)

Also seeds CHANGELOG.md

Generated with git-cliff (v2.13.1, the action's version) using the repo's cliff.toml, covering history through v0.0.3. So the file is complete now, and future releases append to a tracked file (which also keeps the guard on its normal git diff --cached path going forward).

Validation

  • release.yml parses as valid YAML.
  • Full gate suite green (ok: true) — CHANGELOG.md is markdown at the repo root, outside the lint/dup/typecheck scopes, so it doesn't affect any gate.
  • The v0.0.3 release page itself is unaffected (its notes come from a separate git-cliff step that already worked) — this only repairs the tracked CHANGELOG.md and the workflow so it won't recur.

Note

The change touches .github/workflows/release.yml, so the fixed job only actually runs on the next tagged release — but CHANGELOG.md is committed in this PR, so the file is present on main immediately regardless.

The release pipeline's "Update CHANGELOG.md" job guarded its commit with
`git diff --quiet -- CHANGELOG.md`, which only inspects tracked files. On
the first release the freshly generated CHANGELOG.md is untracked, so the
check reported "no change" and silently skipped the commit while the step
still exited 0 — which is why v0.0.3 produced a release but no CHANGELOG.md
on main.

Stage the file first, then test the staged diff
(`git diff --cached --quiet`), which correctly detects a new file. Verified
locally: the old guard skips an untracked CHANGELOG.md, the new guard
commits it.

Also seed CHANGELOG.md (generated by git-cliff through v0.0.3, using the
repo's cliff.toml) so history is complete and future releases append to a
tracked file.
@cvega
cvega merged commit 862763f into main Jun 14, 2026
2 checks passed
@cvega
cvega deleted the fix/changelog-commit branch June 18, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant