Documentation Governance

This document defines the processes that keep TradeMasterAPI's documentation accurate, consistent, and useful for contributors and end-users alike.

Purpose

Documentation drift—where docs describe a different version, path, or behaviour than what the code actually provides—erodes trust and slows onboarding. The practices below prevent that drift from occurring.

Single Sources of Truth

Artefact	Canonical Location	Updated By
Current version	`VERSION` (root)	Release script / release author
Version in README	`README.md` header	Must match `VERSION` at every release
API reference	`docs/API_DOCUMENTATION.md`	Any PR that adds/changes endpoints
Release notes	`docs/release_notes/vX.Y.Z.md`	Release author, using `docs/release_notes_template.md`
Development log	`prompt.ai/development_log.md`	Every merged PR
Git workflow	`prompt.ai/git_workflow.md`	Process changes only

Per-Sprint Documentation Checklist

At the end of every sprint (or before any release), the team must verify each item below. A sprint is not considered complete until all boxes are checked.

Version Alignment

[ ] VERSION file reflects the upcoming release number.
[ ] README.md version string matches VERSION.
[ ] Latest release-notes file exists in docs/release_notes/ and follows the template.

Path and Run-Instruction Accuracy

[ ] Clone URL in README.md points to the correct GitHub organisation/repo.
[ ] Backend and frontend setup commands in README.md work from a fresh clone.
[ ] Helper-script table in README.md lists every script in scripts/.
[ ] Test commands in README.md match actual test locations (tests/selenium/, tests/ui_tests/, backend_v2/tests/).

API Documentation

[ ] Every public endpoint is documented in docs/API_DOCUMENTATION.md.
[ ] Request/response examples are current.
[ ] Any deprecated endpoints are marked as such.

Contributor-Facing Docs

[ ] CONTRIBUTING.md is up to date with current branch strategy and commit conventions.
[ ] New dependencies are listed with version constraints where appropriate.
[ ] Any new environment variables are documented.

Development Log

[ ] prompt.ai/development_log.md contains an entry for every significant change in this sprint.
[ ] Release summary file (prompt.ai/vX.Y.Z_release_summary.md) is created for releases.

Pull-Request Documentation Gate

Every pull request should include documentation updates when the change:

Adds, removes, or modifies an API endpoint.
Changes installation steps or prerequisites.
Introduces new environment variables or configuration.
Alters the project directory structure.
Bumps the project version.

Reviewers should verify that documentation is updated before approving.

Versioning Rules

Follow Semantic Versioning 2.0.0.
The VERSION file is the single source of truth for the current version.
On every release, update VERSION, the README header, and create a release-notes file.

Ownership

The author of the release PR is responsible for completing the per-sprint checklist. All contributors share responsibility for keeping docs accurate within their own PRs.