Skip to main content

Changelog Troubleshooting

Changelog Troubleshooting

Generation Recovery

Diagnose repository ranges, message sources, semantic processing, release behavior, rendering, and final Markdown separately.

Commandcusty changelog generate

Category

Troubleshooting

Quick Command

history -> providers -> processing -> releases -> Jinja -> CHANGELOG.md
Git rangesprovidersgroupingrendering
History Source
GitProvider
Optional Source
PendingCommitProvider
Renderer
JinjaRenderer
Output
CHANGELOG.md

Scope of This Page​

Use this page to locate the changelog stage that produced unexpected data and to understand boundaries shared by collection, processing, releases, and rendering. For a visible custy changelog generate symptom and its direct fix, use the Generate troubleshooting guide.

Locate the Unexpected Stage​

Generation Boundaries

1
Eligibility
Confirm generation was enabled, not skipped, and allowed by release or force conditions.
completed
2
Tag ranges
Confirm local tags, their ordering, stable boundaries, prerelease families, and the HEAD range.
completed
3
Message collection
Compare committed messages with optional latest pending-template content.
current
4
Semantic processing
Review cleaning, ignore rules, parsing, expansion, deduplication, type mapping, and scope grouping.
pending
5
Release behavior
Review hidden, title-only, custom-message, promotion, comparison, and release ordering behavior.
pending
6
Rendering and write
Validate the active Jinja template, render toggles, destination diff, and successful final write.
pending

Pending Content​

The active factory can add PendingCommitProvider for the newest unreleased range when pending content is enabled. It can therefore contribute messages from the configured commit-message file.

Compare Inputs and Output

Evidence commands
bash
git log --oneline --decorate --all
git tag --sort=-version:refname
git diff -- CHANGELOG.md
custy --log-level DEBUG changelog generate

Preserve manual changelog content before regenerating. Correct the first history, configuration, parsing, or template cause; repeated forced generation does not make an incorrect input correct.

Safe Recovery

  1. Save the current CHANGELOG.md diff and project template.
  2. Identify whether collection, processing, release planning, or rendering is wrong.
  3. Correct only that input or active property.
  4. Generate again and review the entire diff.
  5. Confirm unrelated working-tree content remains intact before staging.

Continue

Related Commands

Commands commonly used together with this command.