Contributing Guide

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

When to Create ADRs

Create ADRs for foundational decisions only:

High cost to change mid/late project
Architectural patterns and technology standards
Security frameworks and compliance requirements
Infrastructure patterns that affect multiple teams

Do not create ADRs for:

Implementation details (use documentation)
Project-specific configurations
Operational procedures that change frequently
Tool-specific guidance that belongs in user manuals

Quick Workflow

Open the repository - Use Codespaces, a dev container, or an agency-managed workstation with the required tools
Get number - just next-number
Create file - ###-short-name.md in correct directory (see content types)
Write content - Follow template below
Set annual review metadata - Review must be one year after Date
Add to SUMMARY.md - Include new ADR in navigation (required for mdBook)
Lint - just lint to fix formatting, check metadata, check SUMMARY.md, and validate links
Submit PR - Ready for review

Useful Commands

just --list      # Show all available commands
just next-number # Get next ADR number
just check-summary # Verify SUMMARY.md includes all markdown files
just check-metadata # Verify status/date/review metadata
just lint        # Run checks and fixes
just serve       # Preview locally on port 8080
just build       # Build website and print view

AI-Assisted Contributions

AI tools may help draft or review ADRs, but a human contributor remains responsible for the final content.

Prefer isolated or local AI tooling per ADR 011: AI Tool and Agent Governance
Review adr-design-guardrails.md before proposing changes
Browse reference-architectures/ for project kickoff patterns
Check existing ADRs in development/, operations/, and security/ before creating new guidance
Human review is required for all AI-generated changes before merge
Recommended tools include OpenCode and Goose

flowchart LR
    setup[Environment Setup]
    create[Content Creation]
    validate[Validation]
    publish[Publication]

    setup --> create --> validate --> publish
    validate -->|fix issues| create

    style setup fill:#e3f2fd
    style create fill:#e8f5e8
    style validate fill:#f3e5f5
    style publish fill:#fff3e0

Project Notes

Documentation is built with mdBook
Navigation is defined in SUMMARY.md; new ADRs must be added there
just build creates the website and a single-page print view
Use Mermaid diagrams where a simple visual explanation is clearer than text alone
Each maintained guidance page has Status, Date, and Review metadata
Review dates are annual by default: set Review exactly one year after Date

Directory Structure

Directory	Content
`development/`	API standards, CI/CD, releases
`operations/`	Infrastructure, logging, config
`security/`	Isolation, secrets, AI governance
`reference-architectures/`	Project kickoff templates

Content Types: When to Use What

ADRs (Architecture Decision Records)

Purpose: Document foundational technology decisions that are expensive to change
Format: ###-decision-name.md in development/, operations/, or security/
Examples: “Managed Kubernetes”, “Secrets management”, “HTTP API contracts”

Reference Architectures

Purpose: Project kickoff templates that combine multiple existing ADRs
Format: descriptive-name.md in reference-architectures/
Examples: “Content Management”, “Data Pipelines”, “Identity Management”

Rules:

Reference architectures are informative compositions, not a place to create foundational decisions
Mandatory statements must trace to Accepted ADRs or authoritative policy
Proposed ADR dependencies must be labelled and require project approval
Product and provider mappings are non-normative examples unless an Accepted ADR explicitly selects them
Add missing foundational decisions to the proposed-decision backlog
Include minimum and higher-assurance variants, legacy adoption, required artifacts, operating ownership, acceptance checks, migration, and exit

Applicability, non-goals, prerequisites, and simpler alternatives are clear
Accepted and Proposed dependencies are distinguished
Every mandatory statement traces to an Accepted ADR or authoritative policy
Minimum, higher-assurance, and legacy-transition variants are practical
Capabilities are provider-neutral; AWS, Azure, Google Cloud, SaaS, and legacy examples are labelled non-equivalent where relevant
OpenTofu or Terraform is the preferred provisionable infrastructure path under ADR 010
Kickoff artifacts, ownership, service levels, support, and cost are explicit
Classification, privacy, sharing, records, offshoring, accessibility, resilience, recovery, migration, rollback, and exit are addressed
Acceptance checks are testable with representative users and journeys

Quality Standards

Before submitting:

Title is concise (under 50 characters) and actionable
Status, date, and annual review metadata are present
Synopsis states when to use and avoid the ADR, the decision, minimum evidence, and direct ADR dependencies
All acronyms defined on first use
Active voice (not passive)
Scope, non-goals, and related ADRs are clear
Policy references use authoritative links and durable capability terms
Compliance claims distinguish full, partial, and out-of-scope coverage
Implementation checklist is specific enough for project kickoff
Required evidence and exception handling are explicit
Passes just lint without errors

Title Examples:

GOOD: “ADR 002: Managed Kubernetes” (concise and capability-focused)
GOOD: “ADR 008: Email Authentication Protocols” (specific, clear)
BAD: “ADR 004: Enforce release quality with CI/CD prechecks and build attestation” (too long)
BAD: “Container stuff” or “Security improvements” (too vague)

Status Guide

Status	Meaning
`Proposed`	Under review
`Accepted`	Active decision
`Superseded`	Replaced by newer ADR

Use this metadata line directly below the title:

**Status:** Proposed | **Date:** YYYY-MM-DD | **Review:** YYYY-MM-DD

Set Review to the same month and day in the following year. For example, Date: 2026-06-09 uses Review: 2027-06-09.

Annual Review Checklist

Use this checklist for every scheduled review:

Status is still correct: Proposed, Accepted, or Superseded
Decision still reflects current WA Government policy and standards
External links still resolve and point to the intended guidance
Related ADR links are current
Compliance mapping is still accurate
Implementation checklist remains practical for new projects
Acronyms, glossary terms, and diagrams remain clear
Review date is advanced by one year after the review is complete

ADR References

Reference format:

[ADR 005: Secrets Management](../security/005-secrets-management.md)
Quick reference: per ADR 005
Multiple refs: aligned with ADR 001 and ADR 005

Examples:

“Encryption handled per ADR 005: Secrets Management”
“Access controls aligned with ADR 001”

Writing Tips

Be specific about capabilities: “Use managed Kubernetes only when the workload-fit criteria apply” not “Use containers”
Include implementation: How, not just what
Define scope: What’s included and excluded
State non-goals: Help readers avoid using an ADR outside its intended scope
Link by decision: Prefer ADR links over repeating requirements in multiple places
Reference standards: Link to external docs
Use durable terms: Map to capabilities such as application patching or identity and access management, not policy clause numbers
Separate audit snapshots: Keep exact policy versions and clauses in agency assurance or risk records where point-in-time traceability is needed
Map honestly: Say an ADR supports a capability; do not imply that adopting an ADR alone proves compliance
Make controls testable: Use must for mandatory requirements and name the evidence an implementation must retain
Australian English: Use “organisation” not “organization”, “jurisdiction” not “government”
Character usage: Use plain-text safe Unicode - avoid emoji, smart quotes, em-dashes for print page compatibility
Mermaid diagrams: Use Mermaid for diagrams with clean syntax and universal compatibility
- Use when text alone isn’t sufficient (system relationships, data flows, workflows)
- Keep simple: 5-7 components max, clear labels, logical flow
- Use flowchart TB for compact layouts, flowchart LR for flows
- Use style directives for color styling, keep labels short

DGOV DTT Architecture Decision Records