Skip to content
Structured MADR

Changelog

All notable changes to Structured MADR are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.1.0] - 2026-01-15

Section titled “[1.1.0] - 2026-01-15”

Added

Section titled “Added”
  • GitHub Action: Shareable validation action for CI/CD pipelines
    • Composite action with configurable inputs (path, pattern, schema, strict, fail-on-error)
    • Node.js validator with JSON Schema (ajv) and body structure validation
    • GitHub-compatible annotations for PR feedback
    • Outputs for workflow integration (valid, total, passed, failed, warnings)
  • Project ADRs: Exemplar ADRs demonstrating the format (dogfooding)
    • ADR-0001: Adopt Structured MADR Format for Project Documentation
    • ADR-0002: Shareable GitHub Action for Structured MADR Validation
  • CI/CD: GitHub workflow to validate project and example ADRs
  • Documentation: README updated with action usage, inputs/outputs, and local validation instructions

Changed

Section titled “Changed”
  • Tooling: Added npm package.json with validation dependencies (ajv, ajv-formats, glob, yaml)

[1.0.0] - 2026-01-15

Section titled “[1.0.0] - 2026-01-15”

Added

Section titled “Added”
  • Initial release of Structured MADR specification
  • YAML frontmatter schema with required and optional fields
  • Hierarchical decision drivers (Primary/Secondary)
  • Per-option risk assessment (Technical/Schedule/Ecosystem)
  • Categorized consequences (Positive/Negative/Neutral)
  • Required Audit section with compliance tracking
  • JSON Schema for frontmatter validation (schemas/structured-madr.schema.json)
  • Full template with guidance text (templates/template.md)
  • Bare template for experienced users (templates/template-bare.md)
  • Real-world example ADR (examples/0001-use-rust-implementation-language.md)
  • Formal specification document (SPECIFICATION.md)
  • Contributing guidelines

Design Decisions

Section titled “Design Decisions”
  • MADR Compatibility: Section structure follows MADR 4.0.0 conventions for familiarity
  • Machine-Readable Frontmatter: YAML chosen for broad tooling support
  • Audit Requirements: Mandatory audit section ensures decisions are tracked and validated
  • Risk Assessment: Three-dimension risk model (Technical/Schedule/Ecosystem) provides comprehensive evaluation
  • Status Values: Limited to MADR-compatible values (proposed, accepted, deprecated, superseded)
Section titled “Links”