v13 migration guide misses the render-function migration for custom writerOpt

[yangxu52]

Describe the bug

The v13 migration guide states that most existing .versionrc configurations continue to work unchanged and specifically says:

parserOpts and writerOpts overrides work as before

However, v13 upgrades conventional-changelog from v4 to v8. In conventional-changelog v8, Handlebars template strings and partial files were replaced with JavaScript render
functions.

As a result, existing custom writerOpts templates do not work as before. A string-valued commitPartial that worked with commit-and-tag-version@12.7.3 fails after upgrading to v13.

Current behavior

Given an existing configuration such as:

module.exports = {
  writerOpts: {
    commitPartial: '- {{subject}}',
  },
}

Running:

commit-and-tag-version --dry-run

with v13 fails during changelog generation:

✔ bumping version in package.json
commitPartial is not a function

This behavior is reproducible with both commit-and-tag-version@13.0.0 and 13.1.2.

The underlying breaking change is documented in the conventional-changelog v8 release:

Handlebars template strings and partial files were replaced with render functions.

Expected behavior

The v13 migration guide should explicitly document the render-function migration for users with custom writer templates.

In particular, it should explain that:

• writerOpts.commitPartial, headerPartial, and footerPartial must now be render functions rather than Handlebars strings or partial files.
• A custom writerOpts.mainTemplate must be migrated to a writerOpts.template render function.
• @conventional-changelog/template provides the official Markdown, URL, repository, and composition helpers for implementing these functions.
• ESM .versionrc.js configuration files require commit-and-tag-version@13.1.0 or newer.
• Users importing @conventional-changelog/template from their configuration must declare it as a direct dependency when using strict dependency managers such as pnpm.

The statement that all writerOpts overrides “work as before” should also be qualified so that it does not include the removed Handlebars template interface.

I also suggest adding @conventional-changelog/template to the direct dependencies of commit-and-tag-version. The v13 migration makes these helpers part of the supported
customization path rather than merely an implementation detail inherited transitively through conventional-changelog-writer or a preset.

Declaring the package as a dependency alone would not make it directly importable from user configuration under strict dependency managers. If the intention is to let users access the
helpers without installing another dependency, commit-and-tag-version could additionally expose a supported subpath export, for example:

import { segments, words, link, url } from 'commit-and-tag-version/template'

Otherwise, the migration guide should explicitly instruct users to install the helper package themselves:

npm install --save-dev @conventional-changelog/template

Environment

• Working version: commit-and-tag-version@12.7.3
• Affected versions: 13.0.0, 13.1.2
• Node.js: 22 or newer
• OS: Linux

Possible Solution

Add a migration section similar to the following:

Custom changelog templates now use render functions

conventional-changelog v8 replaced Handlebars templates with JavaScript render functions. String-valued writer templates must be rewritten as functions.

Before:

module.exports = {
  writerOpts: {
    mainTemplate: '...',
    commitPartial: '- {{subject}}',
  },
}

After:

import { words } from '@conventional-changelog/template'

function commitPartial(_context, commit) {
  return words(commit.subject || commit.header, commit.shortHash)
}

export default {
  writerOpts: {
    commitPartial,
  },
}

If a custom main template is used, replace mainTemplate with a template(context) function.

For dependency handling, either:

1. Document that users must install @conventional-changelog/template directly; or
2. Add it as a direct dependency and expose its helpers through a supported commit-and-tag-version/template subpath.

Additional context

• commit-and-tag-version v13 migration guide:
  https://github.com/absolute-version/commit-and-tag-version/blob/master/MIGRATION.md
• conventional-changelog v8.0.0 release:
  https://github.com/conventional-changelog/conventional-changelog/releases/tag/conventional-changelog-v8.0.0
• Upstream render-function change, #1477:
  feat(conventional-changelog-writer,conventional-changelog-angular,conventional-changelog-conventionalcommits,conventional-changelog,template)!: replace handlebars templates with render functions conventional-changelog/conventional-changelog#1477
• Official template helper documentation:
  https://conventional-changelog.js.org/template/
• ESM configuration support added in commit-and-tag-version 13.1.0:
  https://github.com/absolute-version/commit-and-tag-version/releases/tag/v13.1.0

[TimothyJones]

Thank you so much for the detailled writeup! Very much appreciated, and sorry for the undocumented breaking change.

I think the direct dependency approach makes sense and is aligned with the purpose of this project.

I would absolutely accept a PR correcting this, alternatively I'll do it in a week or two on my next open source day.

[yangxu52]

@TimothyJones

A simple PR has been submitted, which not include subpath export .

Subpath export belongs to a new public API, should be discussed separately.
Perhaps it would be better to release the next minor version.