Skip to content

Contributing

This repository is the governance and documentation source of truth for Devonshire Digital LLC. It is private and proprietary — there is no external contribution process — but the same discipline applies whether the contributor is a human or an AI agent.

Before you start

Branching and commits

  • Default branch is main.
  • Use Conventional Commits style prefixes:
  • docs: — documentation content changes
  • feat: — a new document, template, script, or capability
  • fix: — correcting an error in existing content or scripts
  • chore: — maintenance (formatting, metadata cleanup, tooling)
  • refactor: — restructuring without changing meaning
  • Keep commits scoped to one logical change. Avoid bundling unrelated document updates into a single commit.

When an ADR is required

Record an Architecture Decision Record under docs/decisions/ (use the template in templates/) whenever a change:

  • Establishes or changes a company-wide policy or standard.
  • Introduces or changes a material technical architecture choice that would be expensive to reverse.
  • Resolves an entry in docs/governance/open-questions.md in a way that other documents will depend on.

Routine documentation edits, typo fixes, and clarifications do not need an ADR.

Required validation

Before proposing or merging any change:

python scripts/check.py

If tests exist for the area you changed:

python -m unittest discover tests

Do not merge a change with failing validation unless the failure is pre-existing, unrelated, and explicitly noted.

Documentation metadata requirements

Every substantive document (policy, standard, guide, template, record, specification) must carry the front matter block defined in docs/governance/documentation-taxonomy.md, including a unique document_id, document_type, status, owner (a role, never a personal name), and applies_to. Simple directory index README.md files may omit it or use a minimal form.

New content should generally start at status: draft or status: proposed. Only a human owner can move a document to status: approved, and that transition should be a deliberate, visible edit — not incidental to an unrelated change.

Adding a venture, product, or standard

  • New venture: use scripts/create_venture.py to scaffold ventures/<slug>/, then add an entry to the portfolio (portfolio/) per docs/company/portfolio-strategy.md.
  • New product: use scripts/create_product.py to scaffold the product specification within its venture directory. Do not begin implementation before the required specification exists, unless explicitly authorized.
  • New standard: add it under docs/standards/ with correct metadata, and reference it from docs/standards/ or the relevant company doc's "related documents." Consider whether it needs an ADR explaining why it was adopted.
  • New template: add it under templates/, and reference it from any document/process that should use it.

Avoiding accidental policy changes

  • Do not change a document's meaning while doing something that looks like formatting cleanup. Keep substantive and cosmetic changes in separate commits where practical.
  • Do not change status from draft/proposed to approved without a human explicitly directing it.
  • Do not delete or rename a document_id — supersede instead, using the supersedes front-matter field, and keep the old document discoverable.

Review expectations

  • Company-level policy and standards changes should be reviewed by the Founder role before being treated as settled.
  • AI-agent-authored changes to anything in docs/company/, docs/governance/, or docs/standards/ are drafts until a human reviews them, regardless of how confident the draft looks.
  • High-risk-domain content (legal, financial, privacy, security, medical, food safety) always requires human review — see docs/company/customer-trust-principles.md.

Report an issue about this page