A README Documentation Gate: Compile Packaging Facts, Sign User Promises

Описание и применение

В статье описывается автоматизированный процесс разделения фактов и обещаний в README, чтобы избежать устаревшей или вводящей в заблуждение документации.

Задача

Public READMEs often mix machine‑verifiable facts with human‑signed promises, leading to stale or misleading documentation.

Результат

The README now accurately reflects the repository’s current state, separating machine‑verifiable facts from human‑signed promises, reducing onboarding friction and preventing accidental contractual claims.

Рабочий процесс

• 1. Run the local deterministic script to extract facts from pyproject.toml, source files, and pytest collection.
• 2. Generate readme_facts.json containing package name, version, console‑script names, test node IDs, and public module paths.
• 3. Maintain promise_register.yaml with human‑signed statements such as install commands, supported Python/OS windows, and copy‑paste examples.
• 4. Use a documentation gate that compares compiled facts against the register; fail if any signed field contains a placeholder or mismatches.
• 5. Render the final README from the verified facts and signed promises.
• 6. Publish the README once the gate passes.

Доказательства

The compiler writes readme_facts.json from packaging metadata and test collection.

Источник

The gate refuses to render when any signed field still contains a placeholder or when compiled names no longer match the register.

Источник