Description

Closes #1267.

Why

commitizen.changelog.generate_tree_from_commits() parses both the commit subject and each \n\n-separated block of commit.body against commit_parser. So a commit such as

feat: new feature

refactor: incidental cleanup

produces two changelog entries:

### Feat
- new feature
### Refactor
- incidental cleanup

This is rarely what the author intended — they wrote one feat, the body was just a note. The maintainer ack on #1267 confirms the body-parsing is undesirable, but flipping the default would be a behaviour break for existing users (some intentionally rely on it for multi-message commits).

What changed

How it works

1. Default-off semantics. changelog_subject_only = false is the default in both the Settings TypedDict and DEFAULT_SETTINGS, so BaseConfig.__init__ always seeds the dict-key with False and the dict-index access in Changelog.__call__ cannot KeyError.
2. Single chokepoint. Body iteration happens at one place — the chain([subject_match], (body_map_pat.match(block) for block in commit.body.split("\n\n"))) in generate_tree_from_commits(). Replacing the second argument of chain with () when subject_only=True is the entire behavioural change.
3. Why from __future__ import annotations matters. The new body_matches: Iterable[re.Match[str] | None] annotation only resolves in TYPE_CHECKING blocks at runtime; without from __future__ import annotations the import would have to leave TYPE_CHECKING. The file already had it.
4. The end-to-end test was specifically requested. Both reviewers (sonnet-4.6 and GitHub Copilot) flagged that the lib-level test alone wouldn't catch a typo in the self.config.settings["changelog_subject_only"] lookup at commands/changelog.py. The fixup commit 292feb4f adds an integration test that constructs a real config and runs cz changelog --dry-run, then verified by hand that the test fails (with KeyError) when the config key is mistyped.

Backward compatibility

• The default false preserves the historical body-parsing behaviour for every user who hasn't opted in.
• All 158 pre-existing tests/test_changelog.py and tests/commands/test_changelog_command.py tests pass unchanged.
• The new subject_only kwarg on generate_tree_from_commits() defaults to False, so any external caller that imports the function continues to work.

Checklist

• I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude following the guidelines

Code Changes

• Add test cases to all the changes you introduce (1 unit test + 1 integration test)
• Run uv run poe all locally to ensure this change passes linter check and tests (poe lint clean; 159 changelog tests pass)
• Manually test the changes (see "Steps to Test" below)
• Update the documentation for the changes

Documentation Changes

• Added a ### changelog_subject_only section to docs/commands/changelog.md
• Run uv run poe doc locally to ensure the documentation pages render correctly
• Check and fix any broken links (internal or external)

Expected Behavior

Applies to both cz changelog and cz bump --changelog.

Steps to Test This Pull Request

git fetch fork fix/1267-changelog-subject-only
git checkout fork/fix/1267-changelog-subject-only

# 1. Lib-level regression test (forces the body-skip behaviour at the call site).
uv run pytest tests/test_changelog.py -k subject_only -v

# 2. End-to-end test (real config file, real cz changelog invocation).
uv run pytest tests/commands/test_changelog_command.py::test_changelog_subject_only_setting_skips_body_parsing -v

# 3. Verify the e2e test would catch a typo in the config-key wiring.
sed -i.bak 's/changelog_subject_only/changelog_subject_only_TYPO/' commitizen/commands/changelog.py
uv run pytest tests/commands/test_changelog_command.py::test_changelog_subject_only_setting_skips_body_parsing -v
# expected: KeyError: 'changelog_subject_only_TYPO'
mv commitizen/commands/changelog.py.bak commitizen/commands/changelog.py
uv run pytest tests/commands/test_changelog_command.py::test_changelog_subject_only_setting_skips_body_parsing -v
# expected: 1 passed

# 4. Full changelog suite (no regressions).
uv run pytest tests/test_changelog.py tests/commands/test_changelog_command.py -q
# expected: 159 passed

Additional Context

Surfaced while triaging open issues in #1965. Maintainer ack on #1267 confirmed body-parsing is at-best opt-in. The end-to-end integration test was added in fixup commit 292feb4f after both review passes (sonnet-4.6 and Copilot) flagged the wiring as the only path not exercised by tests.