Contributing to TranscriptX

This document covers contribution workflow and how to keep documentation in sync with the codebase.

Documentation authority model

TranscriptX documentation is structured into explicit layers:

  • CONTRACT — owns invariants, schemas, support policy, and rule definitions.

  • GUIDE — owns user/developer flows and examples; may summarize contracts briefly, but may not define rules.

  • ARCHITECTURE — owns system shape, boundaries, and extension points; defers to contracts for invariants.

  • PRODUCT — owns roadmap, vision, and planning/status material.

Hard rules:

  • Do not put Type: / Authority: rows at the top of Markdown files. The CONTRACT / GUIDE / ARCHITECTURE / PRODUCT layers are writing rules, not page headers. They rendered on hosted Sphinx pages. Authority lives in CONTRACT_INDEX.md and the contract files themselves.

  • Every major concept must have one authoritative home.

  • Guides must not define rules.

  • Architecture docs must not define rules.

  • Runtime docs (docs/runtime/*) must describe behavior and operations only; they must not define invariants or support policy.

  • If a GUIDE, ARCHITECTURE, or runtime doc contains normative language for storage, run truth, output layout, or support policy, you must move or delete it and replace it with a short summary plus a link to the authoritative contract.

  • New rule definitions must be added to an existing contract doc whenever possible (docs/runtime/STORAGE.md, docs/run_outcome_contract.md, docs/contracts/output-contract-v1.md, docs/public_surfaces.md). Do not create new contract docs lightly.

Contract authorities (single source of truth)

Each core concept has exactly one authoritative contract:

  • Storage → docs/runtime/STORAGE.md

  • Run truth → docs/run_outcome_contract.md

  • Outputs → docs/contracts/output-contract-v1.md

  • Support surfaces → docs/public_surfaces.md

  • Terminology index → docs/TERMS.md (GUIDE; aggregates terms from contracts — not authoritative by itself).

When you change behavior for any of these concepts, you must update the corresponding contract first, then adjust guides to summarize and link to it.

Documentation sync and failure checklist

Use this checklist when changing entrypoints, compose files, workflows, or any behavior covered by contracts.

1. Contract changes

If you change:

  • storage layout, sidecar paths, metadata subtrees, imports, or rename behavior → update docs/runtime/STORAGE.md.

  • run outcome semantics, allowed statuses, or precedence vs manifest.json and artifacts → update docs/run_outcome_contract.md.

  • output directory layout, output naming, manifest schemas, or run_results placement → update docs/contracts/output-contract-v1.md.

  • supported/unsupported interfaces or support policy → update docs/public_surfaces.md.

It is a docs failure if these changes are only described in README, runtime guides, or architecture docs without being reflected in the contracts.

2. Guides, architecture, and runtime docs (must not define rules)

Treat the following as hard failure conditions in reviews and automated checks:

  • Any GUIDE or ARCHITECTURE doc that defines:

    • storage paths or layout rules,

    • sidecar or metadata subtree rules,

    • run status or run truth semantics,

    • support policy rules.

  • Any runtime doc (docs/runtime/*) that contains invariant or rule definitions for:

    • storage paths/layout,

    • sidecars or metadata trees,

    • run status semantics or execution truth,

    • support or public-surface policy.

In all these cases, fix the doc by:

  • moving the rule (if valid) into the appropriate contract, and

  • replacing the original text with a ≤2-line summary and a direct link to the contract.

3. Entry points and examples

To avoid drift between the web launcher, Docker setup, Python API docs, and architecture docs, also check:

  1. Regenerate and review --help output
    Run transcriptx --help (or python -m transcriptx.web --help). The installed console script only launches Streamlit (--host, --port). Update docs/generated/cli.md so launcher flags and Python API examples match the code. Do not document removed terminal subcommands.

  2. Verify README examples
    Ensure installation (Docker happy path and native helper) and first-analysis steps in README.md are runnable with the current code. README is a user-guide entry: outcomes, GUI labels, install, privacy. It must summarize and link to contracts instead of restating rules. Do not put schema-epoch, install-marker, or public-surfaces tables on the README.

  3. Verify Docker examples
    Ensure docs/runtime/docker.md and README Docker sections match docker-compose.yml (service names, volume paths, ENTRYPOINT usage). Docker docs must describe operational behavior only; detailed storage layout and output rules belong in contracts.

  4. Confirm no removed interfaces are referenced
    Search docs and README for old terminal subcommands (e.g. transcriptx transcript …, transcriptx analyze) and deprecated entry paths (e.g. streamlit_app.py, transcriptx web-viewer). Replace runnable examples with supported surfaces from public_surfaces.md. Automated coverage: tests/contracts/test_stale_surface_references.py.

  5. Confirm version consistency and public-entry parity
    If the package version is displayed anywhere (e.g. in docs or image labels), it should match pyproject.toml version. Keep website/index.html footer version, README outline (hero → screenshots → what you can do → privacy → first analysis → install), and docs/index.md Start-here toctree in sync. USER_INDEX.md is an exhaustive sitemap, not a second start page. Voices: user guide vs technical reference vs maintainer — docs_architecture_1_0.md.

Keep this process lightweight and manual unless a small local helper (e.g. script that runs --help and diffs) is clearly justified.

Source of truth

No implicit contracts

  • If a rule (invariant, requirement, or guarantee) exists, it must be written in a CONTRACT document.

  • If a rule is not written in a CONTRACT document, it is not part of the system’s contract and must not be treated as such in code or guides.

  • When introducing new behavior or invariants, update the appropriate CONTRACT doc first, then adjust guides, architecture, and runtime docs to summarize and link back to it.

Import adapter contribution guardrails

When adding/changing transcript import adapters:

  1. Keep adapters thin: source-legibility normalization only; semantic normalization belongs in import core.

  2. Do not add vendor-name branching in orchestrator, writer, or managed workflow.

  3. Do not write files from adapters.

  4. Do not parse-fallback silently to other adapters after selection.

  5. Treat diagnostic codes as stable contracts; code changes require explicit tests/docs updates.

Development and testing

See developer_quickstart.md for pipeline structure, adding analysis modules, and testing. Run tests from the repo root (e.g. pytest); see tests/README.md and the Makefile for CI and smoke tests.