Skip to content

ADR-0001: Git as Canonical Documentation Source

Status

proposed — decided during initial drafting; not yet formally ratified by a human review checkpoint.

Date

2026-07-10

Context

Devonshire Digital needs one clearly authoritative place for approved company standards, AI-agent operating instructions, decisions, and product specifications. Multiple tools are already in use or under consideration for different purposes — Notion for lightweight collaboration and planning, and this Git repository for structured documentation. Without an explicit decision, it is easy for the "real" version of a document to become ambiguous, with Notion and Git drifting apart and neither being reliably authoritative.

Decision

This Git repository is the canonical source for approved company standards, AI-agent operating instructions, architecture decisions, product specifications, and other technical/documentation artifacts. Notion is a management and collaboration tool only — useful for portfolio views, prioritization, and discussion — and is never treated as authoritative over what is recorded in Git. See ADR-0006 for the corresponding statement of Notion's role.

Consequences

  • Every substantive document has one authoritative location, resolvable by path and document_id, with full version history via Git.
  • Enables code-review-style practices for documentation: diffs, pull requests (if/when a remote is added), and reviewable change history.
  • Requires discipline to prevent Notion from silently diverging into a shadow "source of truth" — anyone updating a Notion page that duplicates Git content is responsible for keeping Git as the reference point, not the other way around.
  • Anyone (human or AI agent) unsure which source to trust should default to Git.

Alternatives Considered

  • Notion-as-source-of-truth. Rejected: Notion pages lack robust version history/diffing suited to formal governance documents, and mixing management workflow content with canonical policy content in the same tool tends to blur the two over time.
  • Wiki-based systems (e.g., a dedicated wiki platform). Rejected: introduces another tool and another place documents can drift from code and specifications, without a clear advantage over a well-organized Git repository for this company's current scale.

Follow-up Actions

  • Document the specific division of responsibilities between Git and Notion in docs/governance/git-and-notion-responsibilities.md (owned by another workstream in this founding effort).
  • Ensure every AI-agent operating document reinforces "Git is canonical" so agents do not treat Notion content as authoritative.

Report an issue about this page