Surface package changelogs on docs site

[masenf]

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Description

This PR adds changelog discovery and rendering to the docs site, making package changelogs accessible at /docs/changelog/ instead of requiring users to visit GitHub releases.

What changed:

1. New reflex_docs/changelogs.py module — Discovers and normalizes changelogs:

   • discover_repo_changelogs() finds towncrier-managed changelogs in the monorepo (repo root + packages/*/CHANGELOG.md)
   • find_distribution_changelog() locates changelogs shipped with installed distributions (e.g., reflex-enterprise)
   • discover_changelogs() combines both sources, ordering reflex first then alphabetically
   • normalize_changelog() ensures consistent H1 headings across different changelog formats (towncrier vs. Keep-a-Changelog)

2. Changelog rendering in docs — Integrated into the docs pipeline:

   • New handle_changelog_doc() handler normalizes changelog markdown and limits TOC to version headings (H2 and above)
   • Changelogs are registered as virtual docs under docs/changelog/ with the main reflex changelog at the section index
   • Updated footer link to point to /changelog/ instead of GitHub releases

3. Sidebar navigation — Added changelog section to the docs sidebar:

   • New get_sidebar_items_changelog() dynamically generates sidebar items from discovered packages
   • Changelog routes are treated as API reference content for sidebar styling

4. Helper function — Added render_markdown_with_toc() to extract heading structure while rendering markdown

5. Documentation — Updated CONTRIBUTING.md to explain where changelogs are published

Tests

• Added comprehensive test suite in docs/app/tests/test_changelogs.py covering:
  • Repo changelog discovery (monorepo structure)
  • Distribution changelog discovery (installed packages)
  • Changelog normalization (towncrier and Keep-a-Changelog formats)
  • Page title generation
  • Edge cases (missing distributions, stale file records, no file metadata)
• Added route validation test in test_routes.py to ensure all discovered changelogs are served
• Added section naming test in test_agent_files.py for root-level markdown docs

All tests pass with the changes.

Related issues

Closes the need for users to navigate to GitHub releases for changelog information.

https://claude.ai/code/session_01ToXo8Yg1VTuuT2jgBqK6T7

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/lucid-hypatia-xq0xzi (c8aad6c) with main (f232cf4)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR surfaces package changelogs directly on the docs site at /docs/changelog/, replacing the GitHub releases link in the footer. It discovers changelogs from the monorepo (repo root + packages/*/) and from installed distributions (e.g., reflex-enterprise), normalises their headings, and registers them as virtual docs with a filtered TOC limited to version-level headings.

• changelogs.py — new module handles discovery (discover_repo_changelogs, find_distribution_changelog) and normalisation (normalize_changelog). The shallowest-path sort prevents vendored third-party changelogs from shadowing the top-level one.
• Docs pipeline integration — changelogs are injected into all_docs at module level, routed through a new handle_changelog_doc handler, and wired into the sidebar under the api-reference layout with their own index entry.
• CI & version bump — APP_HARNESS_FLAG is added to integration-test and dependency-check jobs so tests continue to pass with the reflex-enterprise>=0.9.0.post1 upgrade that ships the first CHANGELOG.md in its wheel.

Confidence Score: 5/5

Safe to merge — changes are additive, well-tested, and confined to the docs app.

All changes are additive: a new discovery module, a new rendering handler, sidebar wiring, and CI flag additions. The implementation is consistent with existing patterns in the codebase, includes a comprehensive test suite covering discovery, normalisation, route validation, and edge cases. The only production code path that could fail at runtime (file read on render) is guarded by the same startup-time existence check used elsewhere in the pipeline.

No files require special attention.

Important Files Changed

Filename	Overview
docs/app/reflex_docs/changelogs.py	New module: discovers and normalises changelogs from the monorepo and from installed distributions. Logic is correct; shallowest-path heuristic for vendored changelogs is sound and well-tested.
docs/app/reflex_docs/pages/docs/init.py	Adds changelog virtual-doc registration at module level and the handle_changelog_doc handler. Pattern is consistent with existing library-doc handling; TOC filtering to level ≤ 2 is intentional and correct.
docs/app/reflex_docs/docgen_pipeline.py	Adds render_markdown_with_toc that combines heading extraction and markdown rendering in a single parse pass. Correctly reuses existing parse_document / ReflexDocTransformer infrastructure.
docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/reference.py	Adds get_sidebar_items_changelog() that lazily imports changelog_packages and constructs flat SideBarItem entries. Mirrors the existing api_reference pattern.
docs/app/reflex_docs/templates/docpage/sidebar/sidebar.py	Wires changelog sidebar section into sidebar_comp and sidebar; adds changelog_index parameter and a create_sidebar_section call. URL matching correctly extends is_api_reference for /changelog/ paths.
docs/app/reflex_docs/templates/docpage/docpage.py	Updates footer Changelog link from GitHub releases URL to the new in-docs /changelog/ route. Minimal, correct change.
docs/app/agent_files/_plugin.py	One-line fix: strips .md suffix from root-level markdown file names when computing the llms.txt section name, preventing labels like "Changelog.md".
docs/app/tests/test_changelogs.py	Comprehensive test suite covering discovery, normalisation, shallowest-path selection, stale records, missing distributions, and ordering. Good use of _FakeDist for isolation.
docs/app/tests/test_routes.py	Adds route validation test asserting every discovered changelog is served; hardcoded reflex-base assertion provides a concrete regression guard.
docs/app/tests/test_agent_files.py	Adds test for the _section_for_path bug fix covering both root-level and subdirectory markdown paths.
packages/reflex-site-shared/src/reflex_site_shared/constants.py	Updates CHANGELOG_URL constant from GitHub releases URL to the docs-site changelog path. Simple, correct change.
.github/workflows/integration_tests.yml	Adds APP_HARNESS_FLAG: "true" env var to two CI jobs so integration tests bypass the enterprise-tier restriction introduced by the reflex-enterprise upgrade.
.github/workflows/check_outdated_dependencies.yml	Same APP_HARNESS_FLAG addition for the dependency-check workflow frontend job.
docs/app/pyproject.toml	Pins reflex-enterprise>=0.9.0.post1 to pick up the wheel that ships CHANGELOG.md.
pyproject.toml	Marks reflex-enterprise = false in the uv workspace so it is treated as a registry dependency rather than a local editable package.

_{Reviews (4): Last reviewed commit: "Set APP_HARNESS_FLAG for CI jobs that ru..." | Re-trigger Greptile}