Universal Documentation Engine Operational Documentation

Appearance

Migration Guide: UDE v1.0 to v2.0 ​

This guide details the enterprise-grade migration path from UDE v1.0 to v2.0, outlining breaking changes, new configuration paradigms, and CLI architecture decoupling.

Breaking Changes & Schema Evolution ​

In v2.0, the untyped ClassEntity model has been replaced with strict Pydantic typed models. Specifically, the loose strings inside fields: List[str] have evolved:

  • v1.0: fields: ["int count", "string name"]
  • v2.0: fields: List[VariableModel] where each VariableModel requires .name, .type, and .docstring attributes.

ProjectCatalog Additions ​

The root ProjectCatalog now mandates two new fields to support multi-versioned SDK documentation:

  • project_name (string)
  • version (string)

CLI Architecture Decoupling ​

The legacy flat CLI flags are preserved for backward compatibility, but v2.0 introduces a decoupled pipeline via subcommands. You can now separate the IR (Intermediate Representation) generation from the rendering phase:

Generate IR:

bash
ude parse --output-ir catalog.json

Render from IR:

bash
ude render --input-ir catalog.json

Coverage Auditing & ude audit ​

v2.0 introduces strict documentation coverage gates controlled via GlobalConfig:

  • coverage_mode: Accepts allow-undocumented (warns) or reject-undocumented (fails the build).
  • coverage_threshold: Specifies the percentage of entities that must be documented (e.g., 0.98 for 98%).

ude audit Table Format ​

When executing ude audit, the engine outputs a strict Markdown table to stdout:

markdown
| Module | Entities | Documented | Coverage | Status |
|--------|----------|------------|----------|--------|
| Core   | 150      | 150        | 100%     | PASS   |
| API    | 50       | 45         | 90%      | FAIL   |
| Total  | 200      | 195        | 97.5%    | FAIL   |

GitHub Actions Integration ​

To enforce this coverage in CI, integrate ude audit as a blocking step:

yaml
      - name: UDE Coverage Audit
        shell: bash -euo pipefail {0}
        env:
          PYTHONPATH: engine
        run: |
          python -m ude.cli audit --threshold 98 --mode reject-undocumented

Step-by-Step Migration Checklist ​

  1. [ ] Update all custom renderers to consume VariableModel attributes (.name, .type, .docstring) instead of raw strings for class fields.
  2. [ ] Add project_name and version fields to your root ude_global_config.json.
  3. [ ] Pivot your CI pipelines to use ude parse and ude render if you require decoupled IR artifact storage.
  4. [ ] Define coverage_mode and coverage_threshold in your global configuration.
  5. [ ] Integrate ude audit into your GitHub Actions workflow as a mandatory quality gate.

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

  • user-docs/docs/cli-reference.md — full reference for the subcommands introduced here
  • user-docs/docs/changelog.md — condensed v1.0 -> v2.0 release notes

Copyright © 2026