Changelog

All notable changes to the UDE (Universal Documentation Engine) project will be documented in this file.

[v2.0] - 2026-07-08

The v2.0 milestone represents a comprehensive architectural overhaul, introducing strict typing, advanced decoupled CI/CD integrations, and enterprise-grade security gates.

Breaking Changes

Three changes stop an unmodified v1.0 configuration from building. All three fail loudly with a specific message rather than degrading silently. See migration-v2.md for the exact messages and the fix for each.

• sidebar.toml is now mandatory and must declare at least one [[sidebar]] entry, in every directory containing a ude_doc_config.json, Hugo variants included. It replaces the per-renderer toc_*.json files as the navigation source and resolves through a three-tier deep merge (global → SDK → document). Missing, empty and malformed files all stop the build: there is no default navigation at any tier, because a sidebar the author never wrote renders successfully and leaves nothing to notice. The [groups] folder taxonomy is deliberately the opposite — it keeps its engine default, since a uniform layout is a sensible fallback where invented navigation is not.
• sidebar_structures_dir removed from ude_global_config.json. The key is trapped explicitly, not ignored; folder taxonomy moved to sidebar.toml's [groups] table, which is schema-validated with extra="forbid".
• renderer.type must be a renderer family key (html, oda_html, hugo_markdown, oda_hugo_markdown, plus aliases), never a concrete renderer class name. The language-specific subclass is now selected by the renderer factory from collector.language.

Explicitly not breaking: the v1.0 flat CLI (ude --doc-config …) works unchanged, v1.0 IR files still load, and the ClassEntity / NamespaceEntity / MethodEntity names are retained as aliases of the new models.

Added

• Typed Entity Models: Complete schema evolution replacing untyped ClassEntity with 7 strict Pydantic models (e.g., VariableModel, MethodModel).
• Decoupled CLI Architecture: New subcommands ude parse, ude render, ude compile, and ude audit allowing discrete IR payload generation and rendering. The IR is gzip-compressed (.json.gz).
• Strict Coverage Auditing: GlobalConfig.coverage_mode and coverage_threshold settings, empowering the new ude audit blocking quality gate. audit exits 2 when the gate rejects the target; the embeddable apply_coverage_gate() raises UdeException instead of calling sys.exit().
• Public Library API: UdeOrchestrator exposes parse, render and run for embedding the engine without the CLI.
• Unified Logging: a single ude root logger driven by log_level / log_file, silent by default when imported as a library.
• L2 Render Cache: unchanged entities skip re-rendering on repeat builds.
• Three-Tier Doxyfile Merge: key-level merge across global, SDK and document tiers, resolved via global_templates_dir.
• Cross-Repository Orchestration: Formalized payload synchronization via GitHub repository_dispatch webhooks across the submodule topology.
• Automated Security Guards: pydantic_guard (Bash/PowerShell) to strictly block obsolete dictionary key access.
• Project Catalog Metadata: Added project_name and version fields to ProjectCatalog. Both are optional and default to an empty string.

Changed

• Refactored fields: List[str] to fields: List[VariableModel].
• Enforced strict shell execution (bash -euo pipefail {0}) and minimized permissions in all GitHub Actions workflows.

Documentation Quality

• Doc-O-Matic output parity verified across 39 SDK/language combinations spanning 16 SDKs. Every difference against the reference documentation is either resolved, covered by a documented parsing rule, or individually confirmed as real API content the reference tool does not document.
• Two areas are deliberately out of scope, by nature rather than omission: SWIG binding folders that are components of another SDK and have no reference documentation of their own, and Python, for which Doc-O-Matic never produced output — leaving regression-against-previous-build as the only available comparison there.

---

[v1.0] - 2025-01-15

The initial MVP release establishing the core documentation generation capabilities.

Added

• Flat CLI flag architecture for single-pass documentation generation.
• Basic ClassEntity and NamespaceEntity string-keyed data structures.
• Support for Doxygen XML parsing and basic HTML/Markdown rendering output.

Related Docs: (Paths below are repository-root-relative.)

• user-docs/docs/migration-v2.md — step-by-step migration guide for the breaking changes listed above
• user-docs/docs/cli-reference.md — reference for the new ude parse/render/compile/audit subcommands