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.

来源