Skip to content

docs: add changelog generation via git-cliff#20

Merged
llbbl merged 1 commit into
mainfrom
chore/changelog
Jul 26, 2026
Merged

docs: add changelog generation via git-cliff#20
llbbl merged 1 commit into
mainfrom
chore/changelog

Conversation

@llbbl

@llbbl llbbl commented Jul 26, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add CHANGELOG.md with a 0.1.0 entry covering the scaffold, conversion core, the three transports, and reverse conversion
  • Add git-cliff config (cliff.toml) and changelog / changelog:preview / changelog:release package scripts
  • Document the changelog workflow in the README

Changes

Documentation

  • CHANGELOG.md: New file with a 0.1.0 entry covering the package scaffold, deterministic Pandoc conversion core, the three transports (local file, SharePoint, Google Drive), and docx-to-markdown reverse conversion. Dependency and API-shape notes that no commit subject can convey (fflate now a runtime dependency, google-auth-library an optional peer, PandocErrorCode/TransportErrorCode being open unions) are hand-added to the release entry.
  • README.md: Document the changelog workflow and conventional commit expectations.

Build System

  • cliff.toml: git-cliff configuration. Merge commits are filtered out of the changelog. A commit preprocessor normalizes the squash-merge subject of PR Add docx-to-markdown reverse conversion (Tier-2) #16, which lost its conventional prefix because GitHub uses the PR title as the commit subject -- without it that work is silently dropped from the changelog.
  • package.json: Add changelog (full regeneration), changelog:preview (show unreleased without writing), and changelog:release (prepend unreleased, leaving published entries intact) scripts. changelog:release is preferred over a full regeneration once a version ships, since regenerating from history would discard the hand-added dependency/API notes above.

Test plan

  • pnpm changelog:preview runs cleanly
  • pnpm changelog:release prepends correctly without touching the 0.1.0 entry

package.json stays at 0.0.0 — versioning is #7's job ("version via tag"). The 0.1.0 heading in the changelog is dated 2026-07-26; if the first publish slips, re-run pnpm changelog with the real tag so the date matches the release.

Closes #19

Add CHANGELOG.md with a 0.1.0 entry covering the package scaffold, the
deterministic Pandoc conversion core, the three transports (local file,
SharePoint, Google Drive), and docx-to-markdown reverse conversion.

Entries are generated with git-cliff from cliff.toml, exposed as
`changelog` (full regeneration), `changelog:preview` (show unreleased
without writing), and `changelog:release` (prepend unreleased, leaving
published entries intact) package scripts.

cliff.toml filters merge commits out of the changelog, and includes a
commit preprocessor that normalizes the squash-merge subject of PR #16
back to a conventional `feat:` prefix -- GitHub uses the PR title as the
squash commit subject, and #16's title lacked the prefix, so without
this preprocessor that work is silently dropped from generated output.

Dependency and API-shape notes that no commit subject can convey --
`fflate` now being a runtime dependency, `google-auth-library` as an
optional peer, and `PandocErrorCode`/`TransportErrorCode` being open
unions -- are hand-added to the 0.1.0 release entry. That's why
`changelog:release` (prepend) is preferred over a full regeneration
once a version has shipped: regenerating from history would discard
those hand-written notes.

Closes #19
@llbbl
llbbl merged commit a0f1d94 into main Jul 26, 2026
4 checks passed
@llbbl
llbbl deleted the chore/changelog branch July 26, 2026 11:46
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.

Add CHANGELOG.md before first npm publish

1 participant