docs(customization): verify executable no-bump plugin example

[bearomorphism]

Description

This stacked follow-up on #2097 makes the published Python-class bump-rule example executable and verified from a single shared source.

It updates the docs to include docs/examples/cz_docs_only.py, adds focused runtime tests for the documented bump_map = {"docs": None} behavior, includes the example in mypy coverage, and tightens the example pattern so fixup!, fixture, and fix! do not silently mis-bump.

During validation, review also surfaced a parent-relative compatibility regression, so this branch restores commitizen.bump.find_increment as a shim and adds a regression test for that public helper without reverting the inherited VersionIncrement work from #2097.

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: Pi following the guidelines

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained
  • Document any manual testing steps performed
• Update the documentation for the changes

Documentation Changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly
• Check and fix any broken links (internal or external)

Expected Behavior

The documented custom plugin example is the same Python file that documentation publishes, mypy checks, and the test suite executes. A docs: commit matched by that example produces no increment, a normal fix: commit produces a PATCH increment, and nearby false positives such as fixup!, fixture, and fix! do not silently produce a PATCH bump.

Steps to Test This Pull Request

1. Run uv run mypy.
2. Run uv run pytest tests/commands/test_documented_python_class_examples.py tests/test_bump_find_increment.py.
3. Run uv run mkdocs build.
4. Confirm docs/customization/python_class.md includes docs/examples/cz_docs_only.py and that the example remains consistent with the tested module.

Additional Context

• Base branch: fm/commitizen-bumprule-pr
• PR 2097 supplies the inherited None typing fix this follow-up builds on: refactor(bump): use VersionIncrement ordering for bump detection #2097

[github-actions]

🔍 Commitizen bump preview

Merging this PR will produce the following bump:

bump: version 4.19.0 → 4.19.1
tag to create: v4.19.1
increment detected: PATCH

## v4.19.1 (2026-10-01)

### Fix

- **types**: allow documented None bump_map values

### Refactor

- **bump**: replace find_increment with VersionIncrement max

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.