From d2a529e60bf29dab816c99f93a42110cb3f4e447 Mon Sep 17 00:00:00 2001 From: Mark Bacon Date: Mon, 19 Oct 2026 12:54:51 +0100 Subject: [PATCH 1/4] Titles: drop EG numbers from guideline titles, and sentence case throughout - The 26 guidelines are titled by name alone (Research, prototyping and experiments, not EG-025: ...). Their IDs stay in the front matter, the guidelines table and rule references. - The chapters of six guides, the radar quadrants and the business principles page move to sentence case with 'and' for '&', like the rest of the site. Firmitas keeps its own style. Co-Authored-By: Claude Opus 5.5 --- content/guidelines/ai-agent-usage.md | 2 +- content/guidelines/architecture-principles.md | 2 +- content/guidelines/business-principles.md | 6 +++++- content/guidelines/coding-principles.md | 2 +- content/guidelines/coding-standard.md | 2 +- content/guidelines/competence-tooling-and-onboarding.md | 2 +- content/guidelines/components-reuse-and-variants.md | 2 +- content/guidelines/decision-records.md | 2 +- content/guidelines/defects-and-technical-debt.md | 2 +- content/guidelines/documentation-as-code.md | 2 +- content/guidelines/guidelines-governance.md | 2 +- content/guidelines/interfaces-and-co-design.md | 2 +- content/guidelines/logging-debug-and-diagnostics.md | 2 +- content/guidelines/observability-and-telemetry.md | 2 +- content/guidelines/pipelines-and-quality-gates.md | 2 +- content/guidelines/planning-delivery-and-improvement.md | 2 +- content/guidelines/pull-requests-and-review.md | 2 +- content/guidelines/quality-policy-and-attributes.md | 2 +- content/guidelines/release-update-and-production.md | 2 +- content/guidelines/requirements-and-traceability.md | 2 +- content/guidelines/research-and-prototyping.md | 2 +- content/guidelines/safety-regulatory-and-certification.md | 2 +- content/guidelines/security-and-data-protection.md | 2 +- content/guidelines/technology-and-third-party.md | 2 +- content/guidelines/testing-principles-and-strategy.md | 2 +- content/guidelines/values-and-ways-of-working.md | 2 +- content/guidelines/version-control-and-versioning.md | 2 +- content/guides/c4-model/01-c4-model-foundations.md | 4 ++-- content/guides/c4-model/02-diagrams-as-code-tooling.md | 4 ++-- content/guides/c4-model/03-system-context.md | 4 ++-- content/guides/c4-model/04-container-diagrams.md | 4 ++-- content/guides/c4-model/05-component-diagrams.md | 4 ++-- content/guides/c4-model/06-structurizr-dsl-reference.md | 4 ++-- content/guides/c4-model/07-deployment-and-dynamics.md | 4 ++-- .../guides/cybersecurity/01-threat-modeling-foundations.md | 4 ++-- .../cybersecurity/02-hardware-and-silicon-security.md | 4 ++-- .../cybersecurity/03-transport-and-network-security.md | 4 ++-- .../guides/cybersecurity/04-secure-firmware-updates-ota.md | 4 ++-- content/guides/cybersecurity/05-standards-and-compliance.md | 4 ++-- .../hil-and-automated-testing/01-the-iot-testing-pyramid.md | 4 ++-- .../02-host-based-firmware-testing.md | 4 ++-- .../03-qemu-virtual-hardware-simulation.md | 4 ++-- .../04-hil-bench-design-and-automation.md | 4 ++-- .../05-network-simulation-and-chaos-testing.md | 4 ++-- .../01-device-tiers-and-hardware-architecture.md | 4 ++-- .../02-connectivity-and-protocol-tradeoffs.md | 4 ++-- .../03-power-architecture-and-duty-cycling.md | 4 ++-- .../04-edge-storage-and-local-resilience.md | 4 ++-- .../05-edge-intelligence-and-processing.md | 4 ++-- .../iot-fleet-operations/01-zero-touch-device-onboarding.md | 4 ++-- .../iot-fleet-operations/02-scalable-telemetry-ingestion.md | 4 ++-- .../03-digital-twins-and-state-reconciliation.md | 4 ++-- .../iot-fleet-operations/04-fleet-scale-ota-campaigns.md | 4 ++-- .../05-fleet-observability-and-remote-diagnostics.md | 4 ++-- content/guides/scaling-architecture/01-advice-process.md | 4 ++-- .../guides/scaling-architecture/02-alignment-mechanisms.md | 4 ++-- content/radar/languages-and-frameworks.md | 4 ++-- content/radar/methods-and-patterns.md | 4 ++-- content/radar/platforms-and-operations.md | 4 ++-- content/radar/tools-and-utilities.md | 4 ++-- 60 files changed, 97 insertions(+), 93 deletions(-) diff --git a/content/guidelines/ai-agent-usage.md b/content/guidelines/ai-agent-usage.md index afe9ed3..916b99f 100644 --- a/content/guidelines/ai-agent-usage.md +++ b/content/guidelines/ai-agent-usage.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-005: AI agent usage +# AI agent usage - **Owner:** Build and tooling lead and Security lead - **Applies to:** All use of AI coding agents and assistants on team repositories diff --git a/content/guidelines/architecture-principles.md b/content/guidelines/architecture-principles.md index 98fa243..4d0a04e 100644 --- a/content/guidelines/architecture-principles.md +++ b/content/guidelines/architecture-principles.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-007: Architecture principles governance +# Architecture principles governance - **Owner:** Architecture group - **Applies to:** Architecture governance and decision-making across products and teams diff --git a/content/guidelines/business-principles.md b/content/guidelines/business-principles.md index 8c9c09a..66e0c10 100644 --- a/content/guidelines/business-principles.md +++ b/content/guidelines/business-principles.md @@ -1,4 +1,8 @@ -# Business & Vertical Principles Overview +--- +title: Business and vertical principles +--- + +# Business and vertical principles ## Generic Guidelines vs. Business & Vertical Principles diff --git a/content/guidelines/coding-principles.md b/content/guidelines/coding-principles.md index 2f09fb5..2af9878 100644 --- a/content/guidelines/coding-principles.md +++ b/content/guidelines/coding-principles.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-012: Coding principles governance +# Coding principles governance - **Owner:** Firmware and Software lead - **Applies to:** Code development by human engineers and AI agents diff --git a/content/guidelines/coding-standard.md b/content/guidelines/coding-standard.md index d23f78b..26651bb 100644 --- a/content/guidelines/coding-standard.md +++ b/content/guidelines/coding-standard.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-013: Coding standard +# Coding standard - **Owner:** Firmware lead - **Applies to:** All languages used in product and tooling code diff --git a/content/guidelines/competence-tooling-and-onboarding.md b/content/guidelines/competence-tooling-and-onboarding.md index 1d79e60..ed63247 100644 --- a/content/guidelines/competence-tooling-and-onboarding.md +++ b/content/guidelines/competence-tooling-and-onboarding.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-026: Competence, tooling and onboarding +# Competence, tooling and onboarding - **Owner:** Engineering manager - **Applies to:** All team members, all sites, and all tools and domains used diff --git a/content/guidelines/components-reuse-and-variants.md b/content/guidelines/components-reuse-and-variants.md index ef761e6..0ebcf93 100644 --- a/content/guidelines/components-reuse-and-variants.md +++ b/content/guidelines/components-reuse-and-variants.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-010: Components, reuse and variants +# Components, reuse and variants - **Owner:** Architecture group - **Applies to:** Every component, whether built in the product, reused from another product, or third party diff --git a/content/guidelines/decision-records.md b/content/guidelines/decision-records.md index 30edda4..abacb1b 100644 --- a/content/guidelines/decision-records.md +++ b/content/guidelines/decision-records.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-008: Decision records: RFCs and ADRs +# Decision records: RFCs and ADRs - **Owner:** Architecture group - **Applies to:** All significant technical, process and guideline decisions diff --git a/content/guidelines/defects-and-technical-debt.md b/content/guidelines/defects-and-technical-debt.md index 2ae1e92..46cd8e3 100644 --- a/content/guidelines/defects-and-technical-debt.md +++ b/content/guidelines/defects-and-technical-debt.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-018: Defect and technical debt management +# Defect and technical debt management - **Owner:** Test and quality lead - **Applies to:** All defects and technical debt in product and tooling diff --git a/content/guidelines/documentation-as-code.md b/content/guidelines/documentation-as-code.md index 014056c..0aaa5b1 100644 --- a/content/guidelines/documentation-as-code.md +++ b/content/guidelines/documentation-as-code.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-004: Documentation as code and terminology +# Documentation as code and terminology - **Owner:** Build and tooling lead - **Applies to:** All documentation describing the product, its design or the way it is built diff --git a/content/guidelines/guidelines-governance.md b/content/guidelines/guidelines-governance.md index 2b5a6fc..1f88532 100644 --- a/content/guidelines/guidelines-governance.md +++ b/content/guidelines/guidelines-governance.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-001: Guidelines governance +# Guidelines governance - **Owner:** Architecture group - **Applies to:** All engineering teams, sites and agents diff --git a/content/guidelines/interfaces-and-co-design.md b/content/guidelines/interfaces-and-co-design.md index 7a26777..cd81b11 100644 --- a/content/guidelines/interfaces-and-co-design.md +++ b/content/guidelines/interfaces-and-co-design.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-009: Interfaces and hardware and software co-design +# Interfaces and hardware and software co-design - **Owner:** Architecture group - **Applies to:** All software, protocol, hardware and cross-site interfaces diff --git a/content/guidelines/logging-debug-and-diagnostics.md b/content/guidelines/logging-debug-and-diagnostics.md index 718b4c7..8a1c173 100644 --- a/content/guidelines/logging-debug-and-diagnostics.md +++ b/content/guidelines/logging-debug-and-diagnostics.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-019: Logging, debug and fault diagnostics +# Logging, debug and fault diagnostics - **Owner:** Firmware lead - **Applies to:** All firmware, debug tooling and production builds diff --git a/content/guidelines/observability-and-telemetry.md b/content/guidelines/observability-and-telemetry.md index 5350fa8..8bc9f0c 100644 --- a/content/guidelines/observability-and-telemetry.md +++ b/content/guidelines/observability-and-telemetry.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-020: Observability and telemetry +# Observability and telemetry - **Owner:** Platform lead - **Applies to:** Devices, backend platform and the tooling that receives and displays their data diff --git a/content/guidelines/pipelines-and-quality-gates.md b/content/guidelines/pipelines-and-quality-gates.md index c3e2d15..8b86a2d 100644 --- a/content/guidelines/pipelines-and-quality-gates.md +++ b/content/guidelines/pipelines-and-quality-gates.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-016: Pipelines and quality gates +# Pipelines and quality gates - **Owner:** Build and tooling lead - **Applies to:** All build, test and release pipelines and their supporting infrastructure diff --git a/content/guidelines/planning-delivery-and-improvement.md b/content/guidelines/planning-delivery-and-improvement.md index dc826b2..57b4a1e 100644 --- a/content/guidelines/planning-delivery-and-improvement.md +++ b/content/guidelines/planning-delivery-and-improvement.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-024: Planning, delivery and improvement +# Planning, delivery and improvement - **Owner:** Engineering manager - **Applies to:** All planning, delivery management and improvement activity diff --git a/content/guidelines/pull-requests-and-review.md b/content/guidelines/pull-requests-and-review.md index 656d6d4..56d055c 100644 --- a/content/guidelines/pull-requests-and-review.md +++ b/content/guidelines/pull-requests-and-review.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-015: Pull requests and code review +# Pull requests and code review - **Owner:** Firmware lead - **Applies to:** All changes to protected branches, by people and agents diff --git a/content/guidelines/quality-policy-and-attributes.md b/content/guidelines/quality-policy-and-attributes.md index b27bcbc..0543f19 100644 --- a/content/guidelines/quality-policy-and-attributes.md +++ b/content/guidelines/quality-policy-and-attributes.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-003: Quality policy and quality attributes +# Quality policy and quality attributes - **Owner:** Test and quality lead - **Applies to:** All products and all engineering activities diff --git a/content/guidelines/release-update-and-production.md b/content/guidelines/release-update-and-production.md index 85dee86..6b8faf2 100644 --- a/content/guidelines/release-update-and-production.md +++ b/content/guidelines/release-update-and-production.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-021: Release, update and production +# Release, update and production - **Owner:** Release manager - **Applies to:** All releases, field updates, production programming and supported versions diff --git a/content/guidelines/requirements-and-traceability.md b/content/guidelines/requirements-and-traceability.md index 790c970..21fba18 100644 --- a/content/guidelines/requirements-and-traceability.md +++ b/content/guidelines/requirements-and-traceability.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-006: Requirements and traceability +# Requirements and traceability - **Owner:** Systems engineering lead - **Applies to:** All product requirements at every level diff --git a/content/guidelines/research-and-prototyping.md b/content/guidelines/research-and-prototyping.md index 10a8de7..d90b2c2 100644 --- a/content/guidelines/research-and-prototyping.md +++ b/content/guidelines/research-and-prototyping.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-025: Research, prototyping and experiments +# Research, prototyping and experiments - **Owner:** Research lead - **Applies to:** All exploratory work: spikes, prototypes, experiments and evaluations diff --git a/content/guidelines/safety-regulatory-and-certification.md b/content/guidelines/safety-regulatory-and-certification.md index 3c8821e..0de0c28 100644 --- a/content/guidelines/safety-regulatory-and-certification.md +++ b/content/guidelines/safety-regulatory-and-certification.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-023: Safety, regulatory and certification +# Safety, regulatory and certification - **Owner:** Regulatory lead - **Applies to:** All products and changes subject to safety, legal or certification requirements diff --git a/content/guidelines/security-and-data-protection.md b/content/guidelines/security-and-data-protection.md index 575227b..c206be8 100644 --- a/content/guidelines/security-and-data-protection.md +++ b/content/guidelines/security-and-data-protection.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-022: Security and data protection +# Security and data protection - **Owner:** Security lead - **Applies to:** All products, tooling, pipelines, data and AI tool use diff --git a/content/guidelines/technology-and-third-party.md b/content/guidelines/technology-and-third-party.md index 0594ef0..aa22811 100644 --- a/content/guidelines/technology-and-third-party.md +++ b/content/guidelines/technology-and-third-party.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-011: Technology selection and third-party components +# Technology selection and third-party components - **Owner:** Architecture group - **Applies to:** All tools, platforms, libraries, vendor SDKs and open-source components diff --git a/content/guidelines/testing-principles-and-strategy.md b/content/guidelines/testing-principles-and-strategy.md index 34ee409..0b29da3 100644 --- a/content/guidelines/testing-principles-and-strategy.md +++ b/content/guidelines/testing-principles-and-strategy.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-017: Testing principles and strategy +# Testing principles and strategy - **Owner:** Test and quality lead - **Applies to:** All verification activity, environments and test code diff --git a/content/guidelines/values-and-ways-of-working.md b/content/guidelines/values-and-ways-of-working.md index 8115b40..6f2bbec 100644 --- a/content/guidelines/values-and-ways-of-working.md +++ b/content/guidelines/values-and-ways-of-working.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-002: Engineering values and ways of working +# Engineering values and ways of working - **Owner:** Engineering manager - **Applies to:** All team members and sites diff --git a/content/guidelines/version-control-and-versioning.md b/content/guidelines/version-control-and-versioning.md index 84f6957..a361e27 100644 --- a/content/guidelines/version-control-and-versioning.md +++ b/content/guidelines/version-control-and-versioning.md @@ -10,7 +10,7 @@ review-by: 2027-09-30 supersedes: --- -# EG-014: Version control, commits and versioning +# Version control, commits and versioning - **Owner:** Build and tooling lead - **Applies to:** All repositories, branches, commits, tags and versioned artefacts diff --git a/content/guides/c4-model/01-c4-model-foundations.md b/content/guides/c4-model/01-c4-model-foundations.md index 55eaceb..e0e2c5f 100644 --- a/content/guides/c4-model/01-c4-model-foundations.md +++ b/content/guides/c4-model/01-c4-model-foundations.md @@ -1,8 +1,8 @@ --- -title: "The C4 Model: Origins, Philosophy, and Core Mechanics" +title: "The C4 model: origins, philosophy and core mechanics" --- -# The C4 Model: Origins, Philosophy, and Core Mechanics +# The C4 model: origins, philosophy and core mechanics ## 1. The Architecture Communication Crisis: Why Traditional Diagrams Fail diff --git a/content/guides/c4-model/02-diagrams-as-code-tooling.md b/content/guides/c4-model/02-diagrams-as-code-tooling.md index a169af4..f3be576 100644 --- a/content/guides/c4-model/02-diagrams-as-code-tooling.md +++ b/content/guides/c4-model/02-diagrams-as-code-tooling.md @@ -1,8 +1,8 @@ --- -title: "Diagrams as Code: Tooling, DSLs, and Repository Integration" +title: "Diagrams as code: tooling, DSLs and repository integration" --- -# Diagrams as Code: Tooling, DSLs, and Repository Integration +# Diagrams as code: tooling, DSLs and repository integration ## 1. The Diagrams-as-Code Paradigm diff --git a/content/guides/c4-model/03-system-context.md b/content/guides/c4-model/03-system-context.md index f3c0eeb..a9355c9 100644 --- a/content/guides/c4-model/03-system-context.md +++ b/content/guides/c4-model/03-system-context.md @@ -1,8 +1,8 @@ --- -title: System Context Diagrams (Level 1) +title: System context diagrams (level 1) --- -# System Context Diagrams (Level 1) +# System context diagrams (level 1) ## 1. Defining the Product Ecosystem Scope diff --git a/content/guides/c4-model/04-container-diagrams.md b/content/guides/c4-model/04-container-diagrams.md index c609f1d..66fb6bb 100644 --- a/content/guides/c4-model/04-container-diagrams.md +++ b/content/guides/c4-model/04-container-diagrams.md @@ -1,8 +1,8 @@ --- -title: Container Diagrams (Level 2) +title: Container diagrams (level 2) --- -# Container Diagrams (Level 2) +# Container diagrams (level 2) ## 1. End-to-End IoT System Architecture diff --git a/content/guides/c4-model/05-component-diagrams.md b/content/guides/c4-model/05-component-diagrams.md index 4795fb3..0207184 100644 --- a/content/guides/c4-model/05-component-diagrams.md +++ b/content/guides/c4-model/05-component-diagrams.md @@ -1,8 +1,8 @@ --- -title: Component Diagrams (Level 3) +title: Component diagrams (level 3) --- -# Component Diagrams (Level 3) +# Component diagrams (level 3) ## 1. Decomposing Containers into Components diff --git a/content/guides/c4-model/06-structurizr-dsl-reference.md b/content/guides/c4-model/06-structurizr-dsl-reference.md index 8332734..d51d0df 100644 --- a/content/guides/c4-model/06-structurizr-dsl-reference.md +++ b/content/guides/c4-model/06-structurizr-dsl-reference.md @@ -1,8 +1,8 @@ --- -title: Structurizr DSL Reference for Connected Systems +title: Structurizr DSL reference for connected systems --- -# Structurizr DSL Reference for Connected Systems +# Structurizr DSL reference for connected systems ## 1. Why Structurizr DSL for IoT Architectures? diff --git a/content/guides/c4-model/07-deployment-and-dynamics.md b/content/guides/c4-model/07-deployment-and-dynamics.md index 60e9073..7945d62 100644 --- a/content/guides/c4-model/07-deployment-and-dynamics.md +++ b/content/guides/c4-model/07-deployment-and-dynamics.md @@ -1,8 +1,8 @@ --- -title: "Deployment, Tips & Tricks, and Anti-Patterns" +title: Deployment, tips and anti-patterns --- -# Deployment, Tips & Tricks, and Anti-Patterns +# Deployment, tips and anti-patterns ## 1. Physical Deployment and Hardware Topology diff --git a/content/guides/cybersecurity/01-threat-modeling-foundations.md b/content/guides/cybersecurity/01-threat-modeling-foundations.md index 8904abd..9a0574b 100644 --- a/content/guides/cybersecurity/01-threat-modeling-foundations.md +++ b/content/guides/cybersecurity/01-threat-modeling-foundations.md @@ -1,8 +1,8 @@ --- -title: Threat Modelling Foundations +title: Threat modelling foundations --- -# Threat Modelling Foundations +# Threat modelling foundations Threat modelling is a structured engineering process for identifying potential security threats, vulnerabilities, and attack vectors in a system before hardware is manufactured or software is deployed to production. diff --git a/content/guides/cybersecurity/02-hardware-and-silicon-security.md b/content/guides/cybersecurity/02-hardware-and-silicon-security.md index a61938f..72c8790 100644 --- a/content/guides/cybersecurity/02-hardware-and-silicon-security.md +++ b/content/guides/cybersecurity/02-hardware-and-silicon-security.md @@ -1,8 +1,8 @@ --- -title: Hardware and Silicon Security +title: Hardware and silicon security --- -# Hardware and Silicon Security +# Hardware and silicon security Software and firmware security guarantees are meaningless if the underlying silicon and circuit board can be compromised. Hardware security forms the immovable anchor of the entire security architecture—known as the **Hardware Root of Trust (RoT)**. diff --git a/content/guides/cybersecurity/03-transport-and-network-security.md b/content/guides/cybersecurity/03-transport-and-network-security.md index 03878aa..f271479 100644 --- a/content/guides/cybersecurity/03-transport-and-network-security.md +++ b/content/guides/cybersecurity/03-transport-and-network-security.md @@ -1,8 +1,8 @@ --- -title: Transport and Network Security +title: Transport and network security --- -# Transport and Network Security +# Transport and network security Edge devices transmit mission-critical telemetry and receive remote actuation commands over public, unmonitored networks (cellular 4G/5G, Wi-Fi, Ethernet, LoRaWAN, satellite). Network communication must assume an untrusted transport medium vulnerable to eavesdropping, packet modification, and man-in-the-middle (MitM) interception. diff --git a/content/guides/cybersecurity/04-secure-firmware-updates-ota.md b/content/guides/cybersecurity/04-secure-firmware-updates-ota.md index 1df7b07..9fa6a99 100644 --- a/content/guides/cybersecurity/04-secure-firmware-updates-ota.md +++ b/content/guides/cybersecurity/04-secure-firmware-updates-ota.md @@ -1,8 +1,8 @@ --- -title: "Secure Firmware Updates & OTA" +title: Secure firmware updates and OTA --- -# Secure Firmware Updates & OTA +# Secure firmware updates and OTA Over-the-Air (OTA) firmware updates are the single most critical capability in connected systems engineering. Without reliable, secure OTA update mechanisms, a newly discovered zero-day vulnerability in an RTOS or crypto library renders an entire deployed fleet permanently exposed, potentially necessitating costly physical recalls. diff --git a/content/guides/cybersecurity/05-standards-and-compliance.md b/content/guides/cybersecurity/05-standards-and-compliance.md index 544f02a..e0e9f8c 100644 --- a/content/guides/cybersecurity/05-standards-and-compliance.md +++ b/content/guides/cybersecurity/05-standards-and-compliance.md @@ -1,8 +1,8 @@ --- -title: "Standards & Regulatory Compliance" +title: Standards and regulatory compliance --- -# Standards & Regulatory Compliance +# Standards and regulatory compliance Connected systems and IoT engineering have transitioned from an era of voluntary best-practice recommendations into a regime of strict, legally binding statutory regulations. Failure to comply with international product security standards now carries severe penalties, including market bans, mandatory product recalls, and multi-million pound fines. diff --git a/content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md b/content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md index 2f02ba3..e3ff22d 100644 --- a/content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md +++ b/content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md @@ -1,8 +1,8 @@ --- -title: The IoT Testing Pyramid +title: The IoT testing pyramid --- -# The IoT Testing Pyramid +# The IoT testing pyramid In traditional web development, testing takes place within standardized, homogeneous virtual machines or container environments. In embedded systems and IoT engineering, software execution is inextricably linked to analog electronics, peripheral bus timing, radio link instability, battery degradation, and environmental extremes. diff --git a/content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md b/content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md index 2f1d023..8b9993f 100644 --- a/content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md +++ b/content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md @@ -1,8 +1,8 @@ --- -title: Host-Based Firmware Testing +title: Host-based firmware testing --- -# Host-Based Firmware Testing +# Host-based firmware testing Testing firmware directly on physical target microcontrollers slows development: flashing via SWD/JTAG takes seconds, setting hardware breakpoints disrupts real-time timers, and automated test runners require specialized physical racks. By decoupling application logic from physical silicon registers, engineering teams can execute thousands of unit tests natively on developer workstations and standard cloud CI runners in seconds. diff --git a/content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md b/content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md index 3c4082b..1a9cd7e 100644 --- a/content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md +++ b/content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md @@ -1,8 +1,8 @@ --- -title: "QEMU & Virtual Hardware Simulation" +title: QEMU and virtual hardware simulation --- -# QEMU & Virtual Hardware Simulation +# QEMU and virtual hardware simulation Host-based unit tests check pure algorithms and state machines. But they cannot run the real ARM Cortex-M binary, test real FreeRTOS context switches, or check how the code handles peripheral interrupts. Conversely, relying exclusively on physical hardware test benches for system integration creates severe bottlenecks in automated continuous integration (CI) pipelines. diff --git a/content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md b/content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md index e5f8d9b..ff1a173 100644 --- a/content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md +++ b/content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md @@ -1,8 +1,8 @@ --- -title: "HIL Bench Design & Automation" +title: HIL bench design and automation --- -# HIL Bench Design & Automation +# HIL bench design and automation While virtual simulators validate logic and scheduling, they cannot detect subtle analog race conditions, crystal oscillator tolerances, radio transmitter harmonics, physical battery droop, or PCB layout flaws. Verifying embedded products before mass manufacturing requires an automated **Hardware-in-the-Loop (HIL)** test bench executing test suites on production-grade silicon. diff --git a/content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md b/content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md index fbe348d..deb9547 100644 --- a/content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md +++ b/content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md @@ -1,8 +1,8 @@ --- -title: "Network Simulation & Chaos Testing" +title: Network simulation and chaos testing --- -# Network Simulation & Chaos Testing +# Network simulation and chaos testing Connected devices in the field face hostile physical and network conditions. Cellular towers drop connections without TCP FIN packets, and deep basements weaken radio signals to the noise floor. Ageing batteries produce large voltage dips during radio bursts. Testing firmware only under clean laboratory conditions guarantees catastrophic failures when deployed across thousands of customer sites. diff --git a/content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md b/content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md index 5153c3c..29a9388 100644 --- a/content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md +++ b/content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md @@ -1,8 +1,8 @@ --- -title: "Device Tiers & Hardware Architecture" +title: Device tiers and hardware architecture --- -# Device Tiers & Hardware Architecture +# Device tiers and hardware architecture Selecting the appropriate silicon architecture, memory hierarchy, and peripheral interconnects forms the foundation of any connected device engineering programme. Inadequate compute capacity prevents future security updates, while over-specifying hardware inflates bill-of-materials (BOM) cost and accelerates battery drain. diff --git a/content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md b/content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md index 9196e0a..45a0496 100644 --- a/content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md +++ b/content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md @@ -1,8 +1,8 @@ --- -title: "Connectivity & Protocol Trade-Offs" +title: Connectivity and protocol trade-offs --- -# Connectivity & Protocol Trade-Offs +# Connectivity and protocol trade-offs Connected endpoints and edge gateways rely on wireless and wired communication protocols to exchange telemetry, receive configuration updates, and report critical alarms. Selecting the optimal combination of physical layer (PHY), medium access control (MAC), transport, and application layer protocols dictates network scalability, battery longevity, and operational data expenditure. diff --git a/content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md b/content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md index 2fb5031..afebb03 100644 --- a/content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md +++ b/content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md @@ -1,8 +1,8 @@ --- -title: "Power Architecture & Duty-Cycling" +title: Power architecture and duty cycling --- -# Power Architecture & Duty-Cycling +# Power architecture and duty cycling Designing power architectures for connected devices requires balancing peak pulse requirements, sleep quiescent leakage, supply voltage ranges, and thermal dissipation. Whether an endpoint relies on a decade-long primary lithium cell, ambient solar energy harvesting, or Power-over-Ethernet (PoE), power architecture dictates system reliability and field operating life. diff --git a/content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md b/content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md index 659a50e..e4ac190 100644 --- a/content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md +++ b/content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md @@ -1,8 +1,8 @@ --- -title: "Edge Storage & Local Resilience" +title: Edge storage and local resilience --- -# Edge Storage & Local Resilience +# Edge storage and local resilience Connected devices deployed across harsh field environments encounter unexpected power interruptions, dead battery cutoffs, network brownouts, and physical shocks. Microcontrollers cannot assume clean shutdowns. A device may lose power while committing a database record, writing a telemetry batch or applying a firmware update. Its non-volatile storage must then recover deterministically on reboot, without human intervention. diff --git a/content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md b/content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md index 128b4dd..b7bd26c 100644 --- a/content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md +++ b/content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md @@ -1,8 +1,8 @@ --- -title: "Edge Intelligence & Processing" +title: Edge intelligence and processing --- -# Edge Intelligence & Processing +# Edge intelligence and processing As edge devices become equipped with higher-performance microcontrollers and digital signal processing (DSP) extensions, transmitting raw, uncompressed sensor streams to the cloud becomes both economically unviable and technically inefficient. Transmitting high-frequency vibration signals (such as 10 kHz accelerometer samples) over cellular or satellite networks would deplete battery budgets and incur enormous cellular data costs. diff --git a/content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md b/content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md index 2ba1417..f90642e 100644 --- a/content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md +++ b/content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md @@ -1,8 +1,8 @@ --- -title: Zero-Touch Device Onboarding +title: Zero-touch device onboarding --- -# Zero-Touch Device Onboarding +# Zero-touch device onboarding Deploying connected devices at fleet scale makes manual on-site configuration, keyboard credential entry, or technician pairing economically unviable. An installation technician mounting an asset tracker, air quality monitor, or industrial sensor should simply apply power, close the enclosure, and walk away. diff --git a/content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md b/content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md index 7e82f56..b753344 100644 --- a/content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md +++ b/content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md @@ -1,8 +1,8 @@ --- -title: Scalable Telemetry Ingestion +title: Scalable telemetry ingestion --- -# Scalable Telemetry Ingestion +# Scalable telemetry ingestion When an IoT fleet grows from ten thousand to one million devices, the telemetry pipeline must absorb millions of concurrent TCP connections and millions of messages per second. It must also survive the thundering herd of reconnections after a network outage ends. A naive cloud architecture that writes directly to relational databases will collapse under connection limits and disk I/O bottlenecks. diff --git a/content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md b/content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md index 3ac5551..8e16c9c 100644 --- a/content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md +++ b/content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md @@ -1,8 +1,8 @@ --- -title: "Digital Twins & State Reconciliation" +title: Digital twins and state reconciliation --- -# Digital Twins & State Reconciliation +# Digital twins and state reconciliation In large-scale IoT fleets, physical devices operate under intermittent connectivity, while enterprise web consoles, mobile applications, and scheduling microservices require continuous, instant read-and-write access to device settings. Directly issuing synchronous HTTP or RPC requests to physical field hardware fails because devices are frequently asleep, out of coverage, or executing high-priority sensing routines. diff --git a/content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md b/content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md index 508023d..606f32a 100644 --- a/content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md +++ b/content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md @@ -1,8 +1,8 @@ --- -title: Fleet-Scale OTA Update Campaigns +title: Fleet-scale OTA update campaigns --- -# Fleet-Scale OTA Update Campaigns +# Fleet-scale OTA update campaigns Firmware Over-The-Air (FOTA) updates represent both the most critical operational capability and the single highest-risk procedure in connected device engineering. A bug in cloud software can be rolled back within seconds by an SRE squad. A flawed firmware update dispatched globally can simultaneously brick an entire fleet of field-deployed hardware, requiring catastrophic physical recalls. diff --git a/content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md b/content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md index e36f55c..d10d92e 100644 --- a/content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md +++ b/content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md @@ -1,8 +1,8 @@ --- -title: "Fleet Observability & Remote Diagnostics" +title: Fleet observability and remote diagnostics --- -# Fleet Observability & Remote Diagnostics +# Fleet observability and remote diagnostics Maintaining high reliability across a geographically dispersed fleet of connected devices requires proactive observability. When a field device silently drops connections, exhausts its battery prematurely, or encounters memory corruption, operations teams must detect the failure pattern before end users experience outages. diff --git a/content/guides/scaling-architecture/01-advice-process.md b/content/guides/scaling-architecture/01-advice-process.md index c6f4aad..68e8dd2 100644 --- a/content/guides/scaling-architecture/01-advice-process.md +++ b/content/guides/scaling-architecture/01-advice-process.md @@ -1,8 +1,8 @@ --- -title: The Advice Process +title: The advice process --- -# The Advice Process +# The advice process The foundational engine of conversational architecture is the **Advice Process**. Adapted from organizational governance models and pioneered in software engineering by Andrew Harmel-Law, the Advice Process replaces hierarchical approval chains with empowered peer consultation. diff --git a/content/guides/scaling-architecture/02-alignment-mechanisms.md b/content/guides/scaling-architecture/02-alignment-mechanisms.md index 8a85dca..27bcd4e 100644 --- a/content/guides/scaling-architecture/02-alignment-mechanisms.md +++ b/content/guides/scaling-architecture/02-alignment-mechanisms.md @@ -1,8 +1,8 @@ --- -title: The Four Alignment Mechanisms +title: The four alignment mechanisms --- -# The Four Alignment Mechanisms +# The four alignment mechanisms To prevent decentralized decision-making from fracturing into architectural fragmentation, the Advice Process MUST be anchored by four interconnected alignment and learning mechanisms: diff --git a/content/radar/languages-and-frameworks.md b/content/radar/languages-and-frameworks.md index b7091ae..b16d8ea 100644 --- a/content/radar/languages-and-frameworks.md +++ b/content/radar/languages-and-frameworks.md @@ -1,8 +1,8 @@ --- -title: Languages and Frameworks +title: Languages and frameworks --- -# Languages and Frameworks +# Languages and frameworks This quadrant covers core programming languages, schema definition languages, and data serialisation formats used across our embedded firmware, edge gateways, and cloud platforms. diff --git a/content/radar/methods-and-patterns.md b/content/radar/methods-and-patterns.md index 304edb9..25ccb00 100644 --- a/content/radar/methods-and-patterns.md +++ b/content/radar/methods-and-patterns.md @@ -1,8 +1,8 @@ --- -title: Methods and Patterns +title: Methods and patterns --- -# Methods and Patterns +# Methods and patterns This quadrant covers software architecture styles, engineering methodologies, regulatory security standards, and operational quality practices. diff --git a/content/radar/platforms-and-operations.md b/content/radar/platforms-and-operations.md index c8d5566..bcd83ae 100644 --- a/content/radar/platforms-and-operations.md +++ b/content/radar/platforms-and-operations.md @@ -1,8 +1,8 @@ --- -title: Platforms and Operations +title: Platforms and operations --- -# Platforms and Operations +# Platforms and operations This quadrant covers real-time operating systems, embedded build distributions, container runtimes, cloud infrastructure platforms, and messaging protocols. diff --git a/content/radar/tools-and-utilities.md b/content/radar/tools-and-utilities.md index 8dcd523..fd8fc8f 100644 --- a/content/radar/tools-and-utilities.md +++ b/content/radar/tools-and-utilities.md @@ -1,8 +1,8 @@ --- -title: Tools and Utilities +title: Tools and utilities --- -# Tools and Utilities +# Tools and utilities This quadrant covers development environments, diagram engines, static analysis linters, compilers, and local database engines. From 11486fe1663a070b56b6d32cdcec614d2ac900bd Mon Sep 17 00:00:00 2001 From: Mark Bacon Date: Mon, 19 Oct 2026 12:56:41 +0100 Subject: [PATCH 2/4] Checklists: show each one as Markdown to copy, as well as formatted Every checklist keeps its ticked-box form and now also gives the same list as a Markdown block, to paste into an issue, a pull request or a review record. - Templates: one block per checklist page, after its last checklist, with the section headings. - Guidelines: a block after each guideline's checklist, and one per guideline on the combined page. Co-Authored-By: Claude Opus 5.5 --- content/guidelines/ai-agent-usage.md | 20 + content/guidelines/architecture-principles.md | 10 + content/guidelines/checklists.md | 498 ++++++++++++++++++ content/guidelines/coding-standard.md | 18 + .../competence-tooling-and-onboarding.md | 19 + .../components-reuse-and-variants.md | 19 + content/guidelines/decision-records.md | 22 + .../guidelines/defects-and-technical-debt.md | 19 + content/guidelines/documentation-as-code.md | 20 + content/guidelines/guidelines-governance.md | 20 + .../guidelines/interfaces-and-co-design.md | 16 + .../logging-debug-and-diagnostics.md | 25 + .../guidelines/observability-and-telemetry.md | 18 + .../guidelines/pipelines-and-quality-gates.md | 22 + .../planning-delivery-and-improvement.md | 20 + .../guidelines/pull-requests-and-review.md | 31 ++ .../quality-policy-and-attributes.md | 14 + .../release-update-and-production.md | 21 + .../requirements-and-traceability.md | 19 + .../guidelines/research-and-prototyping.md | 18 + .../safety-regulatory-and-certification.md | 19 + .../security-and-data-protection.md | 20 + .../guidelines/technology-and-third-party.md | 17 + .../testing-principles-and-strategy.md | 21 + .../guidelines/values-and-ways-of-working.md | 17 + .../version-control-and-versioning.md | 21 + .../architecture-review-checklist.md | 38 ++ content/templates/code-review-checklist.md | 102 ++++ content/templates/debugging-checklist.md | 46 ++ content/templates/defect-report-checklist.md | 21 + content/templates/definition-of-done.md | 22 + content/templates/definition-of-ready.md | 13 + content/templates/design-review-checklist.md | 70 +++ 33 files changed, 1296 insertions(+) diff --git a/content/guidelines/ai-agent-usage.md b/content/guidelines/ai-agent-usage.md index 916b99f..2ed94d3 100644 --- a/content/guidelines/ai-agent-usage.md +++ b/content/guidelines/ai-agent-usage.md @@ -113,6 +113,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14) - [ ] Agent-written documentation is checked by a human against the code or design (AGT-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] `AGENTS.md` exists at the repository root with commands, conventions, boundaries and definition of done (AGT-01, AGT-02) +- [ ] Agent changes follow the same commit, PR, review and CI rules as human changes (AGT-03) +- [ ] A human approves every agent-authored change, and agents never approve or merge their own work (AGT-04) +- [ ] Agent boundaries are protected by CODEOWNERS or branch protection (AGT-05) +- [ ] AI-assisted commits carry an `Assisted-by:` trailer (AGT-06) +- [ ] The submitter understands and can explain every line submitted (AGT-07) +- [ ] An approved-tools register lists each tool and the data classes it may receive (AGT-08) +- [ ] Agents run local checks first and the PR includes the evidence (AGT-09) +- [ ] Large agent diffs are split or accompanied by a summary of intent and risk (AGT-10) +- [ ] Agent-generated tests are reviewed for whether they verify requirements (AGT-11) +- [ ] Shared prompts, agent configuration and skills are versioned and reviewed (AGT-12) +- [ ] Licence and provenance of generated code is handled under the technology guideline (AGT-13) +- [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14) +- [ ] Agent-written documentation is checked by a human against the code or design (AGT-15) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/architecture-principles.md b/content/guidelines/architecture-principles.md index 4d0a04e..66ac20f 100644 --- a/content/guidelines/architecture-principles.md +++ b/content/guidelines/architecture-principles.md @@ -70,3 +70,13 @@ Automated Pipeline Enforcement (CI Check / Architecture Review / ADR) - [ ] ADRs and RFCs cite business principle IDs (PRN-01) - [ ] Deviations from business principles are recorded in ADRs with trade-off rationale (PRN-02) - [ ] Automated architecture rules (budgets, dependency direction) run in CI pipeline (PRN-04) + +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Active business principles are selected from [Business Principles](business-principles.md) for the product (PRN-05) +- [ ] ADRs and RFCs cite business principle IDs (PRN-01) +- [ ] Deviations from business principles are recorded in ADRs with trade-off rationale (PRN-02) +- [ ] Automated architecture rules (budgets, dependency direction) run in CI pipeline (PRN-04) +``` + diff --git a/content/guidelines/checklists.md b/content/guidelines/checklists.md index 0bbca81..7db6bdc 100644 --- a/content/guidelines/checklists.md +++ b/content/guidelines/checklists.md @@ -36,6 +36,26 @@ Profile: Standard. Owner: Architecture group. - [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15) - [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Guidelines live in `docs/guidelines/`, one file per guideline, named `eg-nnn-short-title.md` (GOV-13) +- [ ] Every guideline has front matter with id, title, status, owner, version and review-by (GOV-01) +- [ ] Every guideline follows the standard template and states how compliance is checked (GOV-02, GOV-04) +- [ ] Rules have stable IDs and RFC 2119 keywords, with a rationale where it is not obvious (GOV-03) +- [ ] Each guideline is short enough to read in one sitting, with examples where they help (GOV-05, GOV-11) +- [ ] Changes are made by PR with owner and practitioner approval, and by RFC when material (GOV-06, GOV-07) +- [ ] Review-by dates are checked by CI and no guideline is overdue (GOV-08) +- [ ] Exceptions are recorded with owner, scope, reason and expiry (GOV-09) +- [ ] Deprecated guidelines are kept with a pointer to their replacement (GOV-10) +- [ ] Guideline versions follow semantic versioning (GOV-12) +- [ ] The index is generated from front matter (GOV-13) +- [ ] Each guideline has an accountable owner who handles questions and exception requests (GOV-14) +- [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15) +- [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16) +``` + + ## [EG-002 Engineering values and ways of working](values-and-ways-of-working.md) Profile: Full. Owner: Engineering manager. @@ -52,6 +72,23 @@ Profile: Full. Owner: Engineering manager. - [ ] Changes are small enough to review within one working day (VAL-11) - [ ] Raising a risk, disagreement or mistake is treated as expected behaviour (VAL-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Values are published and used as tie-breakers (VAL-01) +- [ ] Every component, pipeline, rig and tool has a named owner in CODEOWNERS or the ownership register (VAL-02) +- [ ] The decision rights table is current (VAL-03) +- [ ] Escalation steps and time limits are agreed, and decisions are committed to once made (VAL-04, VAL-05) +- [ ] Decisions, agreements and meeting outcomes are written down within one working day (VAL-06) +- [ ] Each component has an owning site and a deputy at another site (VAL-07) +- [ ] Cross-site agreements cover overlap hours, response time and the handover note (VAL-08) +- [ ] All sites use the same tools and conventions, and variants have an ADR (VAL-09) +- [ ] Work status is visible in the tracker and pipeline (VAL-10) +- [ ] Changes are small enough to review within one working day (VAL-11) +- [ ] Raising a risk, disagreement or mistake is treated as expected behaviour (VAL-12) +``` + + ## [EG-003 Quality policy and quality attributes](quality-policy-and-attributes.md) Profile: Standard. Owner: Test and quality lead. @@ -65,6 +102,20 @@ Profile: Standard. Owner: Test and quality lead. - [ ] Each release has quality evidence in its evidence pack (QUA-07) - [ ] The model and objectives are reviewed annually using field data (QUA-08) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A one-page quality policy is published (QUA-01) +- [ ] A quality attribute model exists with definitions and example measures (QUA-02) +- [ ] Each product has a ranked quality attribute profile, approved by the architecture lead and product owner (QUA-03) +- [ ] Quality attributes are stated as measurable scenarios in requirements (QUA-04) +- [ ] An NFR catalogue exists and requirements are selected from it (QUA-05) +- [ ] There is no separate quality phase, the gates are the quality controls (QUA-06) +- [ ] Each release has quality evidence in its evidence pack (QUA-07) +- [ ] The model and objectives are reviewed annually using field data (QUA-08) +``` + + ## [EG-004 Documentation as code and terminology](documentation-as-code.md) Profile: Starter. Owner: Build and tooling lead. @@ -84,6 +135,26 @@ Profile: Starter. Owner: Build and tooling lead. - [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14) - [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Documents are plain-text Markdown in the repository and linted (DOC-01, DOC-02) +- [ ] Documentation changes go through PR like code (DOC-03) +- [ ] Changes to behaviour, interfaces, configuration and build steps update docs in the same PR (DOC-04) +- [ ] Diagrams are Mermaid or PlantUML source (DOC-05) +- [ ] Every document has front matter with owner, status and review date (DOC-06) +- [ ] CI builds the docs, fails on broken links and lint errors, and publishes versioned docs with each release (DOC-07) +- [ ] The minimum document set exists: README, CONTRIBUTING, `AGENTS.md`, architecture overview, build and test instructions, `docs/adr/` (DOC-08) +- [ ] Generated docs are generated and never hand-edited (DOC-09) +- [ ] Documents state their question and audience, and are split by purpose (DOC-10) +- [ ] Writing is plain British English with the conclusion first (DOC-11) +- [ ] A single glossary exists and terms are used consistently (DOC-12) +- [ ] Naming conventions are followed for files, IDs and components (DOC-13) +- [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14) +- [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15) +``` + + ## [EG-005 AI agent usage](ai-agent-usage.md) Profile: Starter. Owner: Build and tooling lead and Security lead. @@ -103,6 +174,26 @@ Profile: Starter. Owner: Build and tooling lead and Security lead. - [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14) - [ ] Agent-written documentation is checked by a human against the code or design (AGT-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] `AGENTS.md` exists at the repository root with commands, conventions, boundaries and definition of done (AGT-01, AGT-02) +- [ ] Agent changes follow the same commit, PR, review and CI rules as human changes (AGT-03) +- [ ] A human approves every agent-authored change, and agents never approve or merge their own work (AGT-04) +- [ ] Agent boundaries are protected by CODEOWNERS or branch protection (AGT-05) +- [ ] AI-assisted commits carry an `Assisted-by:` trailer (AGT-06) +- [ ] The submitter understands and can explain every line submitted (AGT-07) +- [ ] An approved-tools register lists each tool and the data classes it may receive (AGT-08) +- [ ] Agents run local checks first and the PR includes the evidence (AGT-09) +- [ ] Large agent diffs are split or accompanied by a summary of intent and risk (AGT-10) +- [ ] Agent-generated tests are reviewed for whether they verify requirements (AGT-11) +- [ ] Shared prompts, agent configuration and skills are versioned and reviewed (AGT-12) +- [ ] Licence and provenance of generated code is handled under the technology guideline (AGT-13) +- [ ] `AGENTS.md` names CP-02, CP-16 and CP-20 (AGT-14) +- [ ] Agent-written documentation is checked by a human against the code or design (AGT-15) +``` + + ## [EG-006 Requirements and traceability](requirements-and-traceability.md) Profile: Standard. Owner: Systems engineering lead. @@ -121,6 +212,25 @@ Profile: Standard. Owner: Systems engineering lead. - [ ] Regulatory and security requirements are captured as requirements (REQ-12) - [ ] Work items link to a requirement or defect, or state their justification (REQ-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Requirement levels and allocation rules are defined (REQ-01) +- [ ] Each requirement is atomic, unambiguous, feasible, necessary, consistent and verifiable, with one verification method (REQ-02) +- [ ] Requirements are stored as text in the repository with stable `REQ--` IDs (REQ-03) +- [ ] Each requirement has a rationale, parent, owner and status (REQ-04) +- [ ] Requirements are baselined by tag at each release (REQ-05) +- [ ] IDs are referenced in commit footers, PRs and test names (REQ-06) +- [ ] Every approved requirement is allocated, implemented and verified, and every test traces to a requirement (REQ-07) +- [ ] The pipeline generates a trace report with gap gates (REQ-08) +- [ ] A requirement change triggers a change impact check (REQ-09) +- [ ] Requirements are reviewed by author, implementer and verifier before approval (REQ-10) +- [ ] Non-functional requirements are selected from the NFR catalogue (REQ-11) +- [ ] Regulatory and security requirements are captured as requirements (REQ-12) +- [ ] Work items link to a requirement or defect, or state their justification (REQ-13) +``` + + ## [EG-007 Architecture principles](architecture-principles.md) Profile: Standard. Owner: Architecture group. @@ -135,6 +245,21 @@ Profile: Standard. Owner: Architecture group. - [ ] Flash, RAM, CPU, power and latency budgets are allocated and tracked (AP-06) - [ ] Diagnosis, security, fail-safe behaviour and lifecycle are designed in from the start (AP-08 to AP-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Principles are reviewed and adopted for the product, and changed only by RFC (PRN-05) +- [ ] ADRs and RFCs cite the principles that drove them (PRN-01) +- [ ] Decisions that go against a principle say so and record the consequences (PRN-02) +- [ ] The precedence order is applied, and tailored per quality profile where needed (PRN-03, PRN-06) +- [ ] Dependency direction, budgets and interface compatibility are checked in CI (PRN-04) +- [ ] Layers are defined and no application code touches hardware directly (AP-02) +- [ ] Silicon, SDKs and protocols sit behind interfaces we own (AP-03) +- [ ] Flash, RAM, CPU, power and latency budgets are allocated and tracked (AP-06) +- [ ] Diagnosis, security, fail-safe behaviour and lifecycle are designed in from the start (AP-08 to AP-11) +``` + + ## [EG-008 Decision records: RFCs and ADRs](decision-records.md) Profile: Standard. Owner: Architecture group. @@ -156,6 +281,28 @@ Profile: Standard. Owner: Architecture group. - [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11) - [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] ADRs live in `docs/adr/`, are numbered and use the template (ADR-01, ADR-02) +- [ ] ADRs are proposed by PR and merged as `accepted` (ADR-03) +- [ ] Accepted ADRs are immutable apart from status and links, and superseding ADRs point back (ADR-04) +- [ ] At least two options and the reasons for rejection are recorded (ADR-05) +- [ ] Consequences and verification are stated (ADR-06) +- [ ] ADRs link to requirements, principles, RFCs and PRs, and commits use the `ADR:` footer (ADR-07) +- [ ] ADRs are written before or during implementation, and retrospective ones are marked (ADR-08) +- [ ] A decision log index is generated (ADR-09) +- [ ] RFCs are used for guideline changes, cross-team interfaces, major tools and release changes (RFC-01) +- [ ] RFCs are stored in `docs/rfc/`, proposed by PR, short, and discussed in writing by default (RFC-02, RFC-09, RFC-10) +- [ ] Each RFC names an author, sponsor, affected teams, comment period and decision date (RFC-03, RFC-04) +- [ ] Affected teams are notified explicitly (RFC-05) +- [ ] Each RFC covers problem, goals, proposal, alternatives, impact, risks and open questions (RFC-06) +- [ ] Outcome and rationale are recorded and ADRs created (RFC-07, RFC-08) +- [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11) +- [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12) +``` + + ## [EG-009 Interfaces and hardware and software co-design](interfaces-and-co-design.md) Profile: Standard. Owner: Architecture group. @@ -171,6 +318,22 @@ Profile: Standard. Owner: Architecture group. - [ ] Cross-site interface changes are announced with lead time (INT-10) - [ ] Vendor documents are version-controlled or cited by exact version (INT-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Every interface has an owner and a specification in the repository (INT-01, INT-02) +- [ ] Machine-readable definitions generate code and docs, with no hand-maintained copies (INT-03) +- [ ] Interfaces are versioned, a compatibility matrix is kept, and breaking changes go through RFC (INT-04) +- [ ] Contract tests run on both sides in CI (INT-05) +- [ ] The hardware interface agreement is versioned and firmware headers are generated where possible (INT-06) +- [ ] Hardware changes are reviewed for firmware impact and recorded in the bill of materials (INT-07) +- [ ] An errata register is maintained (INT-08) +- [ ] A bring-up plan and emulation exist for new hardware (INT-09) +- [ ] Cross-site interface changes are announced with lead time (INT-10) +- [ ] Vendor documents are version-controlled or cited by exact version (INT-11) +``` + + ## [EG-010 Components, reuse and variants](components-reuse-and-variants.md) Profile: Full. Owner: Architecture group. @@ -189,6 +352,25 @@ Profile: Full. Owner: Architecture group. - [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12) - [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A component register lists every component with owner, repository, version, status and consumers (COM-01) +- [ ] Every component has a named owner and deputy (COM-02) +- [ ] Consumers depend on released, pinned versions and never on branches or unreleased commits (COM-03) +- [ ] Interfaces follow the interface guideline and versions follow semantic versioning (COM-04) +- [ ] The register is checked before building or copying, and forks are recorded in an ADR (COM-05) +- [ ] Consumers do not patch components locally, and contribute changes through the owner (COM-06) +- [ ] Changes affecting several consumers are assessed for impact, with migration guidance and deprecation notice (COM-07) +- [ ] Each component builds and tests on its own and publishes versioned artefacts (COM-08) +- [ ] Variation is expressed through documented variation points, and supported variants are recorded (COM-09) +- [ ] Each product's bill of materials lists component versions (COM-10) +- [ ] Supported combinations are tested and recorded in the compatibility matrix, and kept few (COM-11) +- [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12) +- [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13) +``` + + ## [EG-011 Technology selection and third-party components](technology-and-third-party.md) Profile: Standard. Owner: Architecture group. @@ -205,6 +387,23 @@ Profile: Standard. Owner: Architecture group. - [ ] Toolchain versions are pinned in containers and listed in the radar (TEC-10) - [ ] End-of-life dates are monitored (TEC-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A technology radar exists with adopt, trial, assess and hold (TEC-01) +- [ ] New dependencies and tools have an evaluation recorded in an ADR (TEC-02) +- [ ] A licence policy lists approved and prohibited licences (TEC-03) +- [ ] A manifest of third-party components exists and an SBOM is produced per release (TEC-04) +- [ ] Versions are pinned and checksums verified (TEC-05) +- [ ] Vendor SDKs are wrapped behind our interfaces and patches are tracked (TEC-06) +- [ ] Dependency updates are proposed automatically, with security patch times (TEC-07) +- [ ] Each dependency has an owner, and critical ones have an exit strategy (TEC-08) +- [ ] AI-generated code is checked for licence and provenance (TEC-09) +- [ ] Toolchain versions are pinned in containers and listed in the radar (TEC-10) +- [ ] End-of-life dates are monitored (TEC-11) +``` + + ## [EG-012 Coding principles](coding-principles.md) Profile: Starter. Owner: Firmware lead. @@ -221,6 +420,23 @@ Profile: Starter. Owner: Firmware lead. - [ ] Warnings are treated as errors (CP-15) - [ ] Assumptions are stated and questions raised before implementing (CP-20) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] The coding standard derives from the principles and cites them (CPR-01) +- [ ] Review comments cite principle or rule IDs (CPR-02) +- [ ] Deviations are recorded in the code and in the deviation log (CPR-03) +- [ ] Principles that a tool can check are enforced in CI (CPR-04) +- [ ] Changes are the minimum needed and every changed line traces to the request (CP-02, CP-16) +- [ ] Wrong code is hard to write: distinct types, `const`, narrow interfaces (CP-04) +- [ ] Input is validated at boundaries and invariants are asserted (CP-05) +- [ ] There is no silent failure and every error path is defined (CP-06) +- [ ] Resource use is bounded and undefined behaviour is avoided (CP-07, CP-08) +- [ ] Warnings are treated as errors (CP-15) +- [ ] Assumptions are stated and questions raised before implementing (CP-20) +``` + + ## [EG-013 Coding standard](coding-standard.md) Profile: Standard. Owner: Firmware lead. @@ -238,6 +454,24 @@ Profile: Standard. Owner: Firmware lead. - [ ] A quick reference, review checklist and agent rule list exist (COD-11) - [ ] Scripts and tooling code also have a proportionate standard (COD-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] There is one coding standard per language in use, with rule IDs that cite principles (COD-01) +- [ ] Language version, subset and compiler are specified (COD-02) +- [ ] The standard covers every required topic or says why not (COD-03) +- [ ] The formatter is configured in the repository and checked in CI (COD-04) +- [ ] Static analysis is configured and pinned, warnings are errors, and suppressions are justified and audited (COD-05) +- [ ] Rules are classified mandatory, required or advisory, with a deviation log (COD-06) +- [ ] Each rule has a rationale, examples and a checking tool (COD-07) +- [ ] Compiler flags are standardised and identical locally and in CI (COD-08) +- [ ] A legacy baseline is tracked and there is no drive-by reformatting (COD-09) +- [ ] The standard is reviewed annually through RFC (COD-10) +- [ ] A quick reference, review checklist and agent rule list exist (COD-11) +- [ ] Scripts and tooling code also have a proportionate standard (COD-12) +``` + + ## [EG-014 Version control, commits and versioning](version-control-and-versioning.md) Profile: Starter. Owner: Build and tooling lead. @@ -258,6 +492,27 @@ Profile: Starter. Owner: Build and tooling lead. - [ ] The team understands git well enough to use it safely (VCS-14) - [ ] Commit subjects are imperative and short, and bodies say why (VCS-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Git is the single source of truth, the structure is documented, and no secrets or build outputs are committed (VCS-01) +- [ ] Branching is trunk-based with short-lived, correctly named branches (VCS-02) +- [ ] Commits follow Conventional Commits with scopes mapped to components (VCS-03) +- [ ] Breaking changes use `!` and a `BREAKING CHANGE:` footer (VCS-04) +- [ ] Footers carry `Refs:`, `ADR:` and `Assisted-by:` where relevant (VCS-05) +- [ ] Commits are atomic and buildable (VCS-06) +- [ ] A commit-msg hook and a CI lint enforce the format (VCS-07) +- [ ] `main` has linear history and shared branches are never force-pushed (VCS-08) +- [ ] Semantic versioning is defined for the product (VCS-09) +- [ ] The version comes from the tag, is injected by the build and is never hand-edited (VCS-10) +- [ ] Release tags are annotated, signed and immutable (VCS-11) +- [ ] Version bump, changelog and release notes are generated from commits (VCS-12) +- [ ] Back-ports use `cherry-pick -x` onto supported release branches (VCS-13) +- [ ] The team understands git well enough to use it safely (VCS-14) +- [ ] Commit subjects are imperative and short, and bodies say why (VCS-15) +``` + + ## [EG-015 Pull requests and code review](pull-requests-and-review.md) Profile: Standard. Owner: Firmware lead. @@ -278,6 +533,27 @@ Profile: Standard. Owner: Firmware lead. - [ ] PR links are kept as review evidence (PRR-14) - [ ] Architecture review is not a routine PR requirement, and other PRs are reviewed by component owners (PRR-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] All changes to protected branches go through PR with no direct pushes (PRR-01) +- [ ] PR titles follow Conventional Commits (PRR-02) +- [ ] PR descriptions follow the template (PRR-03) +- [ ] PRs have one purpose and stay around 400 changed lines or fewer, excluding generated files (PRR-04) +- [ ] CODEOWNERS define required reviewers, with two for safety, security and certified areas (PRR-05) +- [ ] Reviewers are not the author and understand the area, and agents do not approve (PRR-06) +- [ ] Required checks pass before human review (PRR-07) +- [ ] Reviewers use the review focus for the change type (PRR-08) +- [ ] First response is within one working day and stale PRs are escalated (PRR-09) +- [ ] Comments are labelled and cite rule IDs (PRR-10) +- [ ] Blocking comments are resolved and stale approvals dismissed (PRR-11) +- [ ] Draft and stacked PRs are used where helpful, with documented order (PRR-12) +- [ ] PRs merge by squash and branches are deleted (PRR-13) +- [ ] PR links are kept as review evidence (PRR-14) +- [ ] Architecture review is not a routine PR requirement, and other PRs are reviewed by component owners (PRR-15) +``` + + ## [EG-016 Pipelines and quality gates](pipelines-and-quality-gates.md) Profile: Standard. Owner: Build and tooling lead. @@ -299,6 +575,28 @@ Profile: Standard. Owner: Build and tooling lead. - [ ] Pipeline duration, queue time and failure reasons are monitored (PIP-15) - [ ] Credentials are least-privilege and short-lived, and release signing uses the two-person rule (PIP-16) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] The pipeline is defined as code, with logic in scripts that run locally by the same command (PIP-01) +- [ ] Toolchains are pinned in versioned container images and builds are hermetic (PIP-02) +- [ ] Reproducibility is verified periodically (PIP-03) +- [ ] Stages are ordered for fast feedback and stages 1 to 4 finish within ten minutes (PIP-04) +- [ ] Artefacts are built once, promoted and stored immutably with metadata (PIP-05) +- [ ] Gates are defined by branch type (PIP-06) +- [ ] Mandatory gate content is present: warnings, analysis, budgets, coverage, docs, trace, licence and SBOM, secrets (PIP-07) +- [ ] Gates cannot be bypassed without a recorded exception (PIP-08) +- [ ] Flaky tests are quarantined within one working day (PIP-09) +- [ ] The policy is revert first, and `main` is restored within one working day (PIP-10) +- [ ] The pipeline has an owner, a rotation and service levels (PIP-11) +- [ ] SBOM, signed artefacts and provenance are produced per release (PIP-12) +- [ ] Repository settings and required checks are held as code (PIP-13) +- [ ] Shared HIL rigs are accessed through the pipeline (PIP-14) +- [ ] Pipeline duration, queue time and failure reasons are monitored (PIP-15) +- [ ] Credentials are least-privilege and short-lived, and release signing uses the two-person rule (PIP-16) +``` + + ## [EG-017 Testing principles and strategy](testing-principles-and-strategy.md) Profile: Standard. Owner: Test and quality lead. @@ -319,6 +617,27 @@ Profile: Standard. Owner: Test and quality lead. - [ ] Exploratory testing is planned and time-boxed, with findings recorded (TST-14) - [ ] No failing test is skipped or deleted to pass a gate (TST-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A test strategy exists per product with levels, entry and exit criteria, tools and environments (TST-01) +- [ ] Testing is weighted towards host-level tests (TST-02) +- [ ] Test names or metadata carry requirement IDs (TST-03) +- [ ] Coverage is measured with thresholds and a ratchet, and requirement coverage is reported (TST-04) +- [ ] Simulators and test doubles are maintained and validated against hardware (TST-05) +- [ ] Negative tests and fault injection cover parsers, comms, update, storage and security (TST-06) +- [ ] Every fixed defect has a regression test and the suite runs on every merge to `main` (TST-07) +- [ ] Test data and fixtures are versioned (TST-08) +- [ ] Rigs are managed as products (TST-09) +- [ ] Results are archived per release and linked to requirements (TST-10) +- [ ] Non-functional tests run nightly or continuously (TST-11) +- [ ] Verification of high-risk requirements is independent of the author (TST-12) +- [ ] Upgrade and rollback are tested from all supported versions (TST-13) +- [ ] Exploratory testing is planned and time-boxed, with findings recorded (TST-14) +- [ ] No failing test is skipped or deleted to pass a gate (TST-15) +``` + + ## [EG-018 Defect and technical debt management](defects-and-technical-debt.md) Profile: Standard. Owner: Test and quality lead. @@ -337,6 +656,25 @@ Profile: Standard. Owner: Test and quality lead. - [ ] Suppressions and deviations are tracked as debt (DEF-12) - [ ] Metrics are used for improvement and not for ranking individuals (DEF-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] All defects are in the tracker with the required fields (DEF-01) +- [ ] Severity uses the agreed definitions, with priority set separately (DEF-02) +- [ ] New defects are triaged within two working days (DEF-03) +- [ ] The lifecycle is followed, verification is by someone else and closure needs a regression test (DEF-04) +- [ ] Root cause analysis is done for severity 1 and 2 defects and escapes (DEF-05) +- [ ] Each escape asks which gate should have caught it (DEF-06) +- [ ] Commits reference defects and release notes list fixes and known issues (DEF-07) +- [ ] A field defect route exists, with reproduction and release manager notification (DEF-08) +- [ ] Technical debt is recorded with label, impact, estimate and owner (DEF-09) +- [ ] Capacity is reserved for debt and old debt is reviewed (DEF-10) +- [ ] Deliberate debt has a repayment plan and expiry (DEF-11) +- [ ] Suppressions and deviations are tracked as debt (DEF-12) +- [ ] Metrics are used for improvement and not for ranking individuals (DEF-13) +``` + + ## [EG-019 Logging, debug and fault diagnostics](logging-debug-and-diagnostics.md) Profile: Standard. Owner: Firmware lead. @@ -361,6 +699,31 @@ Profile: Standard. Owner: Firmware lead. - [ ] A procedure turns a field dump into a local reproduction, which becomes a test (DBG-10) - [ ] Trace and timing tools are approved and the cost of instrumentation is documented (DBG-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Logging purposes are separated, each with its own levels and retention (LOG-01) +- [ ] Log levels are defined and DEBUG and TRACE are off in production (LOG-02) +- [ ] There is one logging facility, no ad-hoc printf, and every record has a module ID and severity (LOG-03) +- [ ] The format is compact, structured and machine-parseable, with an off-target decoder if needed (LOG-04) +- [ ] A versioned event and fault code registry has an owner (LOG-05) +- [ ] Logging cost is budgeted, non-blocking and rate-limited (LOG-06) +- [ ] Persistent logs are wear-aware (LOG-07) +- [ ] Logs contain no secrets or personal data (LOG-08) +- [ ] Messages say what happened with context, and there is no logging in tight loops (LOG-09) +- [ ] Log decoding tools are versioned with the firmware (LOG-10) +- [ ] A standard debug setup is documented per platform and starts with one command (DBG-01) +- [ ] Debug and production builds are defined, debug builds are never released, and production interfaces are locked (DBG-02) +- [ ] Every fault path has defined behaviour, recorded in an ADR (DBG-03) +- [ ] Assertions guard invariants, have defined production behaviour and no side effects (DBG-04) +- [ ] The reset reason is captured at every boot (DBG-05) +- [ ] The crash dump format is defined, a build ID is embedded and symbols are archived per release (DBG-06, DBG-07) +- [ ] Runtime diagnostics exist and the watchdog design is reviewed (DBG-08, DBG-09) +- [ ] A procedure turns a field dump into a local reproduction, which becomes a test (DBG-10) +- [ ] Trace and timing tools are approved and the cost of instrumentation is documented (DBG-11) +``` + + ## [EG-020 Observability and telemetry](observability-and-telemetry.md) Profile: Full. Owner: Platform lead. @@ -378,6 +741,24 @@ Profile: Full. Owner: Platform lead. - [ ] Lab and HIL environments emit the same telemetry (OBS-11) - [ ] Data quality checks are in place (OBS-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Observability requirements are defined per product (OBS-01) +- [ ] The telemetry schema is versioned, owned and follows naming conventions (OBS-02) +- [ ] Every record carries device, firmware, hardware, configuration and time context (OBS-03) +- [ ] Bandwidth, battery, storage and cost budgets exist with a sampling policy (OBS-04) +- [ ] Data minimisation, classification and retention are applied (OBS-05) +- [ ] Transport handles offline buffering, ordering, de-duplication and loss detection (OBS-06) +- [ ] Backend, dashboards and alerts are defined as code (OBS-07) +- [ ] Health indicators and objectives are defined, and every alert has an owner, runbook and action (OBS-08, OBS-13) +- [ ] Rollouts are gated by telemetry with automatic halt criteria (OBS-09) +- [ ] Field insights are reviewed monthly and fed into triage and tests (OBS-10) +- [ ] Lab and HIL environments emit the same telemetry (OBS-11) +- [ ] Data quality checks are in place (OBS-12) +``` + + ## [EG-021 Release, update and production](release-update-and-production.md) Profile: Standard. Owner: Release manager. @@ -398,6 +779,27 @@ Profile: Standard. Owner: Release manager. - [ ] Artefacts, symbols and toolchains are retained for the supported life (REL-16) - [ ] A post-release review is held (REL-17) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Release stages, roles and a checklist are defined in the repository (REL-01) +- [ ] The candidate is a tagged commit built once, and that artefact is promoted (REL-02) +- [ ] Release criteria are met: gates, no open severity 1 or 2, trace, NFRs, budgets, docs, SBOM, security, regulatory (REL-03) +- [ ] The evidence pack is generated automatically and retained (REL-04) +- [ ] Release notes are generated from commits and defects (REL-05) +- [ ] A bill of materials defines each baseline (REL-06) +- [ ] A compatibility matrix and supported upgrade paths are maintained (REL-07) +- [ ] The update mechanism is recorded in an ADR: authenticated, atomic, power-fail safe, with rollback and a downgrade policy (REL-08) +- [ ] Rollouts are staged with health gates and the ability to halt (REL-09) +- [ ] Upgrade and rollback are tested from supported versions (REL-10) +- [ ] A hotfix process is defined (REL-11) +- [ ] A support and end-of-life policy is published (REL-12) +- [ ] Production programming and provisioning are controlled, with feedback, unit traceability and secure key injection (REL-13, REL-14, REL-15) +- [ ] Artefacts, symbols and toolchains are retained for the supported life (REL-16) +- [ ] A post-release review is held (REL-17) +``` + + ## [EG-022 Security and data protection](security-and-data-protection.md) Profile: Starter. Owner: Security lead. @@ -417,6 +819,26 @@ Profile: Starter. Owner: Security lead. - [ ] Debug and manufacturing interfaces are protected in production (SEC-13) - [ ] A security incident procedure is defined (SEC-14) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Security requirements and a threat model exist and are updated on architecture change (SEC-01) +- [ ] The security architecture covers trust boundaries, secure boot, encrypted comms, secure update, protected storage and debug protection (SEC-02) +- [ ] Only approved cryptography and vetted libraries are used (SEC-03) +- [ ] Key hierarchy, protected signing, provisioning, rotation and revocation are documented (SEC-04) +- [ ] No secrets are in source, and scanning runs pre-commit and in CI (SEC-05) +- [ ] Secure coding rules and security-focused review apply, and parsers are fuzzed (SEC-06) +- [ ] Security testing is performed and findings are tracked (SEC-07) +- [ ] Vulnerability intake, disclosure policy, patch times and SBOM monitoring exist (SEC-08) +- [ ] Supply chain controls are in place (SEC-09) +- [ ] A data classification scheme has handling rules, including for AI tools (SEC-10) +- [ ] Privacy by design, retention and impact assessment are applied where needed (SEC-11) +- [ ] Access is least-privilege with multi-factor authentication and quarterly review (SEC-12) +- [ ] Debug and manufacturing interfaces are protected in production (SEC-13) +- [ ] A security incident procedure is defined (SEC-14) +``` + + ## [EG-023 Safety, regulatory and certification](safety-regulatory-and-certification.md) Profile: Full. Owner: Regulatory lead. @@ -435,6 +857,25 @@ Profile: Full. Owner: Regulatory lead. - [ ] Technical files are maintained as docs as code (REG-12) - [ ] Compliance training is recorded (REG-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Applicable standards and regulations are identified in a compliance register (REG-01) +- [ ] The register maps obligations to requirements, evidence, owner and status (REG-02) +- [ ] Regulatory obligations are captured as requirements and traced (REG-03) +- [ ] Evidence is produced by the pipeline into the evidence pack (REG-04) +- [ ] Changes to certified items have a change impact assessment (REG-05) +- [ ] The certified baseline is recorded and regulated software is separated where applicable (REG-06) +- [ ] The safety lifecycle is followed where an integrity level applies (REG-07) +- [ ] Tools for certified builds are qualified or validated and frozen (REG-08) +- [ ] Records are retained, audits held annually and findings tracked (REG-09) +- [ ] Test house and notified body contact is owned by a named person (REG-10) +- [ ] Regulatory changes are reviewed quarterly (REG-11) +- [ ] Technical files are maintained as docs as code (REG-12) +- [ ] Compliance training is recorded (REG-13) +``` + + ## [EG-024 Planning, delivery and improvement](planning-delivery-and-improvement.md) Profile: Full. Owner: Engineering manager. @@ -454,6 +895,26 @@ Profile: Full. Owner: Engineering manager. - [ ] Friction with a guideline is raised as an issue or RFC (PLN-13) - [ ] Status is derived from tracker and pipeline data (PLN-14) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Work is planned in time-boxed iterations or flow with a visible backlog, and every item is traceable (PLN-01) +- [ ] A Definition of Ready exists per work item type (PLN-02) +- [ ] A Definition of Done exists per type and the PR template reflects it (PLN-03) +- [ ] Estimates are ranges and forecasts state confidence (PLN-04) +- [ ] A risk register is maintained and reviewed fortnightly (PLN-05) +- [ ] Dependencies are recorded with an owner and need-by date (PLN-06) +- [ ] Escalation thresholds are defined (PLN-07) +- [ ] Capacity is reserved for support, debt and improvement (PLN-08) +- [ ] A small metric set is tracked and not used to rank individuals (PLN-09) +- [ ] Retrospectives are held and actions are tracked (PLN-10) +- [ ] Blameless postmortems follow severity 1 and 2 escapes, failed releases, outages and security incidents (PLN-11) +- [ ] Improvements are first-class backlog items (PLN-12) +- [ ] Friction with a guideline is raised as an issue or RFC (PLN-13) +- [ ] Status is derived from tracker and pipeline data (PLN-14) +``` + + ## [EG-025 Research, prototyping and experiments](research-and-prototyping.md) Profile: Standard. Owner: Research lead. @@ -471,6 +932,24 @@ Profile: Standard. Owner: Research lead. - [ ] Findings are shared with the team (RSH-11) - [ ] Agent use in prototypes follows the same boundaries (RSH-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Work is classified as exploratory or production, with a question and a time-box (RSH-01) +- [ ] Exploratory code lives in designated locations and is excluded from release builds (RSH-02) +- [ ] Exemptions are understood and the non-negotiables are kept: no secrets, licences, data rules, version control, a working build (RSH-03) +- [ ] Prototype code is never copied into the product and the graduation checklist is used (RSH-04) +- [ ] An experiment record captures question, method, setup, results, conclusion and next step (RSH-05) +- [ ] Experiments are reproducible (RSH-06) +- [ ] Each exploration ends with a decision to stop, extend or graduate (RSH-07) +- [ ] The maturity level is stated (RSH-08) +- [ ] Prototypes are reviewed at the end of the time-box and unowned ones archived after 90 days (RSH-09) +- [ ] Lab equipment and boards are recorded with an owner (RSH-10) +- [ ] Findings are shared with the team (RSH-11) +- [ ] Agent use in prototypes follows the same boundaries (RSH-12) +``` + + ## [EG-026 Competence, tooling and onboarding](competence-tooling-and-onboarding.md) Profile: Full. Owner: Engineering manager. @@ -488,3 +967,22 @@ Profile: Full. Owner: Engineering manager. - [ ] Key areas are known at two or more sites (CMP-11) - [ ] The team is trained in safe and effective use of AI agents (CMP-12) - [ ] New tools are introduced with training and a radar update (CMP-13) + +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A competence matrix covers languages, RTOS, platforms, protocols, tools, domains, security and test (CMP-01) +- [ ] Single-person areas are tracked as risks (CMP-02) +- [ ] Expected depth per tool is defined and used in training (CMP-03) +- [ ] Each tool and domain area has a champion and a how-to page (CMP-04) +- [ ] Domain experts and deputies are named and primers written (CMP-05) +- [ ] An onboarding path is documented and the environment is set up in under one day (CMP-06) +- [ ] Environment setup is tested in CI (CMP-07) +- [ ] An annual training plan has protected learning time (CMP-08) +- [ ] Knowledge sharing is regular and sessions are recorded (CMP-09) +- [ ] Rationale is captured in ADRs and docs, and a handover checklist exists for leavers (CMP-10) +- [ ] Key areas are known at two or more sites (CMP-11) +- [ ] The team is trained in safe and effective use of AI agents (CMP-12) +- [ ] New tools are introduced with training and a radar update (CMP-13) +``` + diff --git a/content/guidelines/coding-standard.md b/content/guidelines/coding-standard.md index 26651bb..18b101c 100644 --- a/content/guidelines/coding-standard.md +++ b/content/guidelines/coding-standard.md @@ -87,6 +87,24 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] A quick reference, review checklist and agent rule list exist (COD-11) - [ ] Scripts and tooling code also have a proportionate standard (COD-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] There is one coding standard per language in use, with rule IDs that cite principles (COD-01) +- [ ] Language version, subset and compiler are specified (COD-02) +- [ ] The standard covers every required topic or says why not (COD-03) +- [ ] The formatter is configured in the repository and checked in CI (COD-04) +- [ ] Static analysis is configured and pinned, warnings are errors, and suppressions are justified and audited (COD-05) +- [ ] Rules are classified mandatory, required or advisory, with a deviation log (COD-06) +- [ ] Each rule has a rationale, examples and a checking tool (COD-07) +- [ ] Compiler flags are standardised and identical locally and in CI (COD-08) +- [ ] A legacy baseline is tracked and there is no drive-by reformatting (COD-09) +- [ ] The standard is reviewed annually through RFC (COD-10) +- [ ] A quick reference, review checklist and agent rule list exist (COD-11) +- [ ] Scripts and tooling code also have a proportionate standard (COD-12) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/competence-tooling-and-onboarding.md b/content/guidelines/competence-tooling-and-onboarding.md index ed63247..fc2117e 100644 --- a/content/guidelines/competence-tooling-and-onboarding.md +++ b/content/guidelines/competence-tooling-and-onboarding.md @@ -81,6 +81,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] The team is trained in safe and effective use of AI agents (CMP-12) - [ ] New tools are introduced with training and a radar update (CMP-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A competence matrix covers languages, RTOS, platforms, protocols, tools, domains, security and test (CMP-01) +- [ ] Single-person areas are tracked as risks (CMP-02) +- [ ] Expected depth per tool is defined and used in training (CMP-03) +- [ ] Each tool and domain area has a champion and a how-to page (CMP-04) +- [ ] Domain experts and deputies are named and primers written (CMP-05) +- [ ] An onboarding path is documented and the environment is set up in under one day (CMP-06) +- [ ] Environment setup is tested in CI (CMP-07) +- [ ] An annual training plan has protected learning time (CMP-08) +- [ ] Knowledge sharing is regular and sessions are recorded (CMP-09) +- [ ] Rationale is captured in ADRs and docs, and a handover checklist exists for leavers (CMP-10) +- [ ] Key areas are known at two or more sites (CMP-11) +- [ ] The team is trained in safe and effective use of AI agents (CMP-12) +- [ ] New tools are introduced with training and a radar update (CMP-13) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/components-reuse-and-variants.md b/content/guidelines/components-reuse-and-variants.md index 0ebcf93..546bea8 100644 --- a/content/guidelines/components-reuse-and-variants.md +++ b/content/guidelines/components-reuse-and-variants.md @@ -92,6 +92,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12) - [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A component register lists every component with owner, repository, version, status and consumers (COM-01) +- [ ] Every component has a named owner and deputy (COM-02) +- [ ] Consumers depend on released, pinned versions and never on branches or unreleased commits (COM-03) +- [ ] Interfaces follow the interface guideline and versions follow semantic versioning (COM-04) +- [ ] The register is checked before building or copying, and forks are recorded in an ADR (COM-05) +- [ ] Consumers do not patch components locally, and contribute changes through the owner (COM-06) +- [ ] Changes affecting several consumers are assessed for impact, with migration guidance and deprecation notice (COM-07) +- [ ] Each component builds and tests on its own and publishes versioned artefacts (COM-08) +- [ ] Variation is expressed through documented variation points, and supported variants are recorded (COM-09) +- [ ] Each product's bill of materials lists component versions (COM-10) +- [ ] Supported combinations are tested and recorded in the compatibility matrix, and kept few (COM-11) +- [ ] Transfer, deprecation and retirement are recorded and communicated (COM-12) +- [ ] Consumers report through the owner's tracker and severity 1 and 2 defects are visible to all consumers (COM-13) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/decision-records.md b/content/guidelines/decision-records.md index abacb1b..a542af7 100644 --- a/content/guidelines/decision-records.md +++ b/content/guidelines/decision-records.md @@ -141,6 +141,28 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11) - [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] ADRs live in `docs/adr/`, are numbered and use the template (ADR-01, ADR-02) +- [ ] ADRs are proposed by PR and merged as `accepted` (ADR-03) +- [ ] Accepted ADRs are immutable apart from status and links, and superseding ADRs point back (ADR-04) +- [ ] At least two options and the reasons for rejection are recorded (ADR-05) +- [ ] Consequences and verification are stated (ADR-06) +- [ ] ADRs link to requirements, principles, RFCs and PRs, and commits use the `ADR:` footer (ADR-07) +- [ ] ADRs are written before or during implementation, and retrospective ones are marked (ADR-08) +- [ ] A decision log index is generated (ADR-09) +- [ ] RFCs are used for guideline changes, cross-team interfaces, major tools and release changes (RFC-01) +- [ ] RFCs are stored in `docs/rfc/`, proposed by PR, short, and discussed in writing by default (RFC-02, RFC-09, RFC-10) +- [ ] Each RFC names an author, sponsor, affected teams, comment period and decision date (RFC-03, RFC-04) +- [ ] Affected teams are notified explicitly (RFC-05) +- [ ] Each RFC covers problem, goals, proposal, alternatives, impact, risks and open questions (RFC-06) +- [ ] Outcome and rationale are recorded and ADRs created (RFC-07, RFC-08) +- [ ] An architecture forum meets on a fixed cadence and every RFC is decided, or deferred with a reason, by its decision date (RFC-11) +- [ ] Architecture review is limited to architecturally significant changes, and other decisions belong to component owners (RFC-12) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/defects-and-technical-debt.md b/content/guidelines/defects-and-technical-debt.md index 46cd8e3..00680b1 100644 --- a/content/guidelines/defects-and-technical-debt.md +++ b/content/guidelines/defects-and-technical-debt.md @@ -75,6 +75,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Suppressions and deviations are tracked as debt (DEF-12) - [ ] Metrics are used for improvement and not for ranking individuals (DEF-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] All defects are in the tracker with the required fields (DEF-01) +- [ ] Severity uses the agreed definitions, with priority set separately (DEF-02) +- [ ] New defects are triaged within two working days (DEF-03) +- [ ] The lifecycle is followed, verification is by someone else and closure needs a regression test (DEF-04) +- [ ] Root cause analysis is done for severity 1 and 2 defects and escapes (DEF-05) +- [ ] Each escape asks which gate should have caught it (DEF-06) +- [ ] Commits reference defects and release notes list fixes and known issues (DEF-07) +- [ ] A field defect route exists, with reproduction and release manager notification (DEF-08) +- [ ] Technical debt is recorded with label, impact, estimate and owner (DEF-09) +- [ ] Capacity is reserved for debt and old debt is reviewed (DEF-10) +- [ ] Deliberate debt has a repayment plan and expiry (DEF-11) +- [ ] Suppressions and deviations are tracked as debt (DEF-12) +- [ ] Metrics are used for improvement and not for ranking individuals (DEF-13) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/documentation-as-code.md b/content/guidelines/documentation-as-code.md index 0aaa5b1..b394163 100644 --- a/content/guidelines/documentation-as-code.md +++ b/content/guidelines/documentation-as-code.md @@ -100,6 +100,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14) - [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Documents are plain-text Markdown in the repository and linted (DOC-01, DOC-02) +- [ ] Documentation changes go through PR like code (DOC-03) +- [ ] Changes to behaviour, interfaces, configuration and build steps update docs in the same PR (DOC-04) +- [ ] Diagrams are Mermaid or PlantUML source (DOC-05) +- [ ] Every document has front matter with owner, status and review date (DOC-06) +- [ ] CI builds the docs, fails on broken links and lint errors, and publishes versioned docs with each release (DOC-07) +- [ ] The minimum document set exists: README, CONTRIBUTING, `AGENTS.md`, architecture overview, build and test instructions, `docs/adr/` (DOC-08) +- [ ] Generated docs are generated and never hand-edited (DOC-09) +- [ ] Documents state their question and audience, and are split by purpose (DOC-10) +- [ ] Writing is plain British English with the conclusion first (DOC-11) +- [ ] A single glossary exists and terms are used consistently (DOC-12) +- [ ] Naming conventions are followed for files, IDs and components (DOC-13) +- [ ] Approval is PR approval unless a regulation requires a signature record (DOC-14) +- [ ] Documents are structured with headings, front matter and IDs so people and agents can navigate them (DOC-15) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/guidelines-governance.md b/content/guidelines/guidelines-governance.md index 1f88532..df068b8 100644 --- a/content/guidelines/guidelines-governance.md +++ b/content/guidelines/guidelines-governance.md @@ -96,6 +96,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15) - [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Guidelines live in `docs/guidelines/`, one file per guideline, named `eg-nnn-short-title.md` (GOV-13) +- [ ] Every guideline has front matter with id, title, status, owner, version and review-by (GOV-01) +- [ ] Every guideline follows the standard template and states how compliance is checked (GOV-02, GOV-04) +- [ ] Rules have stable IDs and RFC 2119 keywords, with a rationale where it is not obvious (GOV-03) +- [ ] Each guideline is short enough to read in one sitting, with examples where they help (GOV-05, GOV-11) +- [ ] Changes are made by PR with owner and practitioner approval, and by RFC when material (GOV-06, GOV-07) +- [ ] Review-by dates are checked by CI and no guideline is overdue (GOV-08) +- [ ] Exceptions are recorded with owner, scope, reason and expiry (GOV-09) +- [ ] Deprecated guidelines are kept with a pointer to their replacement (GOV-10) +- [ ] Guideline versions follow semantic versioning (GOV-12) +- [ ] The index is generated from front matter (GOV-13) +- [ ] Each guideline has an accountable owner who handles questions and exception requests (GOV-14) +- [ ] Core rules are marked and applied identically across products, and all other rules are tailored only through the product profile (GOV-15) +- [ ] Each product has a conformance profile recording applicability, thresholds, exceptions, components and toolchain (GOV-16) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/interfaces-and-co-design.md b/content/guidelines/interfaces-and-co-design.md index cd81b11..2a8b635 100644 --- a/content/guidelines/interfaces-and-co-design.md +++ b/content/guidelines/interfaces-and-co-design.md @@ -78,6 +78,22 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Cross-site interface changes are announced with lead time (INT-10) - [ ] Vendor documents are version-controlled or cited by exact version (INT-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Every interface has an owner and a specification in the repository (INT-01, INT-02) +- [ ] Machine-readable definitions generate code and docs, with no hand-maintained copies (INT-03) +- [ ] Interfaces are versioned, a compatibility matrix is kept, and breaking changes go through RFC (INT-04) +- [ ] Contract tests run on both sides in CI (INT-05) +- [ ] The hardware interface agreement is versioned and firmware headers are generated where possible (INT-06) +- [ ] Hardware changes are reviewed for firmware impact and recorded in the bill of materials (INT-07) +- [ ] An errata register is maintained (INT-08) +- [ ] A bring-up plan and emulation exist for new hardware (INT-09) +- [ ] Cross-site interface changes are announced with lead time (INT-10) +- [ ] Vendor documents are version-controlled or cited by exact version (INT-11) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/logging-debug-and-diagnostics.md b/content/guidelines/logging-debug-and-diagnostics.md index 8a1c173..5c145d8 100644 --- a/content/guidelines/logging-debug-and-diagnostics.md +++ b/content/guidelines/logging-debug-and-diagnostics.md @@ -95,6 +95,31 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] A procedure turns a field dump into a local reproduction, which becomes a test (DBG-10) - [ ] Trace and timing tools are approved and the cost of instrumentation is documented (DBG-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Logging purposes are separated, each with its own levels and retention (LOG-01) +- [ ] Log levels are defined and DEBUG and TRACE are off in production (LOG-02) +- [ ] There is one logging facility, no ad-hoc printf, and every record has a module ID and severity (LOG-03) +- [ ] The format is compact, structured and machine-parseable, with an off-target decoder if needed (LOG-04) +- [ ] A versioned event and fault code registry has an owner (LOG-05) +- [ ] Logging cost is budgeted, non-blocking and rate-limited (LOG-06) +- [ ] Persistent logs are wear-aware (LOG-07) +- [ ] Logs contain no secrets or personal data (LOG-08) +- [ ] Messages say what happened with context, and there is no logging in tight loops (LOG-09) +- [ ] Log decoding tools are versioned with the firmware (LOG-10) +- [ ] A standard debug setup is documented per platform and starts with one command (DBG-01) +- [ ] Debug and production builds are defined, debug builds are never released, and production interfaces are locked (DBG-02) +- [ ] Every fault path has defined behaviour, recorded in an ADR (DBG-03) +- [ ] Assertions guard invariants, have defined production behaviour and no side effects (DBG-04) +- [ ] The reset reason is captured at every boot (DBG-05) +- [ ] The crash dump format is defined, a build ID is embedded and symbols are archived per release (DBG-06, DBG-07) +- [ ] Runtime diagnostics exist and the watchdog design is reviewed (DBG-08, DBG-09) +- [ ] A procedure turns a field dump into a local reproduction, which becomes a test (DBG-10) +- [ ] Trace and timing tools are approved and the cost of instrumentation is documented (DBG-11) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/observability-and-telemetry.md b/content/guidelines/observability-and-telemetry.md index 8bc9f0c..c5dd00a 100644 --- a/content/guidelines/observability-and-telemetry.md +++ b/content/guidelines/observability-and-telemetry.md @@ -74,6 +74,24 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Lab and HIL environments emit the same telemetry (OBS-11) - [ ] Data quality checks are in place (OBS-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Observability requirements are defined per product (OBS-01) +- [ ] The telemetry schema is versioned, owned and follows naming conventions (OBS-02) +- [ ] Every record carries device, firmware, hardware, configuration and time context (OBS-03) +- [ ] Bandwidth, battery, storage and cost budgets exist with a sampling policy (OBS-04) +- [ ] Data minimisation, classification and retention are applied (OBS-05) +- [ ] Transport handles offline buffering, ordering, de-duplication and loss detection (OBS-06) +- [ ] Backend, dashboards and alerts are defined as code (OBS-07) +- [ ] Health indicators and objectives are defined, and every alert has an owner, runbook and action (OBS-08, OBS-13) +- [ ] Rollouts are gated by telemetry with automatic halt criteria (OBS-09) +- [ ] Field insights are reviewed monthly and fed into triage and tests (OBS-10) +- [ ] Lab and HIL environments emit the same telemetry (OBS-11) +- [ ] Data quality checks are in place (OBS-12) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/pipelines-and-quality-gates.md b/content/guidelines/pipelines-and-quality-gates.md index 8b86a2d..a1e7fc7 100644 --- a/content/guidelines/pipelines-and-quality-gates.md +++ b/content/guidelines/pipelines-and-quality-gates.md @@ -94,6 +94,28 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Pipeline duration, queue time and failure reasons are monitored (PIP-15) - [ ] Credentials are least-privilege and short-lived, and release signing uses the two-person rule (PIP-16) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] The pipeline is defined as code, with logic in scripts that run locally by the same command (PIP-01) +- [ ] Toolchains are pinned in versioned container images and builds are hermetic (PIP-02) +- [ ] Reproducibility is verified periodically (PIP-03) +- [ ] Stages are ordered for fast feedback and stages 1 to 4 finish within ten minutes (PIP-04) +- [ ] Artefacts are built once, promoted and stored immutably with metadata (PIP-05) +- [ ] Gates are defined by branch type (PIP-06) +- [ ] Mandatory gate content is present: warnings, analysis, budgets, coverage, docs, trace, licence and SBOM, secrets (PIP-07) +- [ ] Gates cannot be bypassed without a recorded exception (PIP-08) +- [ ] Flaky tests are quarantined within one working day (PIP-09) +- [ ] The policy is revert first, and `main` is restored within one working day (PIP-10) +- [ ] The pipeline has an owner, a rotation and service levels (PIP-11) +- [ ] SBOM, signed artefacts and provenance are produced per release (PIP-12) +- [ ] Repository settings and required checks are held as code (PIP-13) +- [ ] Shared HIL rigs are accessed through the pipeline (PIP-14) +- [ ] Pipeline duration, queue time and failure reasons are monitored (PIP-15) +- [ ] Credentials are least-privilege and short-lived, and release signing uses the two-person rule (PIP-16) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/planning-delivery-and-improvement.md b/content/guidelines/planning-delivery-and-improvement.md index 57b4a1e..5171a40 100644 --- a/content/guidelines/planning-delivery-and-improvement.md +++ b/content/guidelines/planning-delivery-and-improvement.md @@ -97,6 +97,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Friction with a guideline is raised as an issue or RFC (PLN-13) - [ ] Status is derived from tracker and pipeline data (PLN-14) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Work is planned in time-boxed iterations or flow with a visible backlog, and every item is traceable (PLN-01) +- [ ] A Definition of Ready exists per work item type (PLN-02) +- [ ] A Definition of Done exists per type and the PR template reflects it (PLN-03) +- [ ] Estimates are ranges and forecasts state confidence (PLN-04) +- [ ] A risk register is maintained and reviewed fortnightly (PLN-05) +- [ ] Dependencies are recorded with an owner and need-by date (PLN-06) +- [ ] Escalation thresholds are defined (PLN-07) +- [ ] Capacity is reserved for support, debt and improvement (PLN-08) +- [ ] A small metric set is tracked and not used to rank individuals (PLN-09) +- [ ] Retrospectives are held and actions are tracked (PLN-10) +- [ ] Blameless postmortems follow severity 1 and 2 escapes, failed releases, outages and security incidents (PLN-11) +- [ ] Improvements are first-class backlog items (PLN-12) +- [ ] Friction with a guideline is raised as an issue or RFC (PLN-13) +- [ ] Status is derived from tracker and pipeline data (PLN-14) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/pull-requests-and-review.md b/content/guidelines/pull-requests-and-review.md index 56d055c..e3424b2 100644 --- a/content/guidelines/pull-requests-and-review.md +++ b/content/guidelines/pull-requests-and-review.md @@ -76,6 +76,16 @@ Ensure that no change reaches a protected branch without independent review and - [ ] Certified or regulated area touched (EG-023) ``` +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Documentation updated +- [ ] Breaking change flagged +- [ ] AI assistance disclosed (Assisted-by) +- [ ] Certified or regulated area touched (EG-023) +``` + + ## Compliance | Rule | Checked by | @@ -106,6 +116,27 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] PR links are kept as review evidence (PRR-14) - [ ] Architecture review is not a routine PR requirement, and other PRs are reviewed by component owners (PRR-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] All changes to protected branches go through PR with no direct pushes (PRR-01) +- [ ] PR titles follow Conventional Commits (PRR-02) +- [ ] PR descriptions follow the template (PRR-03) +- [ ] PRs have one purpose and stay around 400 changed lines or fewer, excluding generated files (PRR-04) +- [ ] CODEOWNERS define required reviewers, with two for safety, security and certified areas (PRR-05) +- [ ] Reviewers are not the author and understand the area, and agents do not approve (PRR-06) +- [ ] Required checks pass before human review (PRR-07) +- [ ] Reviewers use the review focus for the change type (PRR-08) +- [ ] First response is within one working day and stale PRs are escalated (PRR-09) +- [ ] Comments are labelled and cite rule IDs (PRR-10) +- [ ] Blocking comments are resolved and stale approvals dismissed (PRR-11) +- [ ] Draft and stacked PRs are used where helpful, with documented order (PRR-12) +- [ ] PRs merge by squash and branches are deleted (PRR-13) +- [ ] PR links are kept as review evidence (PRR-14) +- [ ] Architecture review is not a routine PR requirement, and other PRs are reviewed by component owners (PRR-15) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/quality-policy-and-attributes.md b/content/guidelines/quality-policy-and-attributes.md index 0543f19..ee3abc3 100644 --- a/content/guidelines/quality-policy-and-attributes.md +++ b/content/guidelines/quality-policy-and-attributes.md @@ -85,6 +85,20 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Each release has quality evidence in its evidence pack (QUA-07) - [ ] The model and objectives are reviewed annually using field data (QUA-08) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A one-page quality policy is published (QUA-01) +- [ ] A quality attribute model exists with definitions and example measures (QUA-02) +- [ ] Each product has a ranked quality attribute profile, approved by the architecture lead and product owner (QUA-03) +- [ ] Quality attributes are stated as measurable scenarios in requirements (QUA-04) +- [ ] An NFR catalogue exists and requirements are selected from it (QUA-05) +- [ ] There is no separate quality phase, the gates are the quality controls (QUA-06) +- [ ] Each release has quality evidence in its evidence pack (QUA-07) +- [ ] The model and objectives are reviewed annually using field data (QUA-08) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/release-update-and-production.md b/content/guidelines/release-update-and-production.md index 6b8faf2..1bb0ee8 100644 --- a/content/guidelines/release-update-and-production.md +++ b/content/guidelines/release-update-and-production.md @@ -85,6 +85,27 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Artefacts, symbols and toolchains are retained for the supported life (REL-16) - [ ] A post-release review is held (REL-17) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Release stages, roles and a checklist are defined in the repository (REL-01) +- [ ] The candidate is a tagged commit built once, and that artefact is promoted (REL-02) +- [ ] Release criteria are met: gates, no open severity 1 or 2, trace, NFRs, budgets, docs, SBOM, security, regulatory (REL-03) +- [ ] The evidence pack is generated automatically and retained (REL-04) +- [ ] Release notes are generated from commits and defects (REL-05) +- [ ] A bill of materials defines each baseline (REL-06) +- [ ] A compatibility matrix and supported upgrade paths are maintained (REL-07) +- [ ] The update mechanism is recorded in an ADR: authenticated, atomic, power-fail safe, with rollback and a downgrade policy (REL-08) +- [ ] Rollouts are staged with health gates and the ability to halt (REL-09) +- [ ] Upgrade and rollback are tested from supported versions (REL-10) +- [ ] A hotfix process is defined (REL-11) +- [ ] A support and end-of-life policy is published (REL-12) +- [ ] Production programming and provisioning are controlled, with feedback, unit traceability and secure key injection (REL-13, REL-14, REL-15) +- [ ] Artefacts, symbols and toolchains are retained for the supported life (REL-16) +- [ ] A post-release review is held (REL-17) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/requirements-and-traceability.md b/content/guidelines/requirements-and-traceability.md index 21fba18..df0b61c 100644 --- a/content/guidelines/requirements-and-traceability.md +++ b/content/guidelines/requirements-and-traceability.md @@ -94,6 +94,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Regulatory and security requirements are captured as requirements (REQ-12) - [ ] Work items link to a requirement or defect, or state their justification (REQ-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Requirement levels and allocation rules are defined (REQ-01) +- [ ] Each requirement is atomic, unambiguous, feasible, necessary, consistent and verifiable, with one verification method (REQ-02) +- [ ] Requirements are stored as text in the repository with stable `REQ--` IDs (REQ-03) +- [ ] Each requirement has a rationale, parent, owner and status (REQ-04) +- [ ] Requirements are baselined by tag at each release (REQ-05) +- [ ] IDs are referenced in commit footers, PRs and test names (REQ-06) +- [ ] Every approved requirement is allocated, implemented and verified, and every test traces to a requirement (REQ-07) +- [ ] The pipeline generates a trace report with gap gates (REQ-08) +- [ ] A requirement change triggers a change impact check (REQ-09) +- [ ] Requirements are reviewed by author, implementer and verifier before approval (REQ-10) +- [ ] Non-functional requirements are selected from the NFR catalogue (REQ-11) +- [ ] Regulatory and security requirements are captured as requirements (REQ-12) +- [ ] Work items link to a requirement or defect, or state their justification (REQ-13) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/research-and-prototyping.md b/content/guidelines/research-and-prototyping.md index d90b2c2..d3e9f56 100644 --- a/content/guidelines/research-and-prototyping.md +++ b/content/guidelines/research-and-prototyping.md @@ -84,6 +84,24 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Findings are shared with the team (RSH-11) - [ ] Agent use in prototypes follows the same boundaries (RSH-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Work is classified as exploratory or production, with a question and a time-box (RSH-01) +- [ ] Exploratory code lives in designated locations and is excluded from release builds (RSH-02) +- [ ] Exemptions are understood and the non-negotiables are kept: no secrets, licences, data rules, version control, a working build (RSH-03) +- [ ] Prototype code is never copied into the product and the graduation checklist is used (RSH-04) +- [ ] An experiment record captures question, method, setup, results, conclusion and next step (RSH-05) +- [ ] Experiments are reproducible (RSH-06) +- [ ] Each exploration ends with a decision to stop, extend or graduate (RSH-07) +- [ ] The maturity level is stated (RSH-08) +- [ ] Prototypes are reviewed at the end of the time-box and unowned ones archived after 90 days (RSH-09) +- [ ] Lab equipment and boards are recorded with an owner (RSH-10) +- [ ] Findings are shared with the team (RSH-11) +- [ ] Agent use in prototypes follows the same boundaries (RSH-12) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/safety-regulatory-and-certification.md b/content/guidelines/safety-regulatory-and-certification.md index 0de0c28..a839d12 100644 --- a/content/guidelines/safety-regulatory-and-certification.md +++ b/content/guidelines/safety-regulatory-and-certification.md @@ -74,6 +74,25 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Technical files are maintained as docs as code (REG-12) - [ ] Compliance training is recorded (REG-13) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Applicable standards and regulations are identified in a compliance register (REG-01) +- [ ] The register maps obligations to requirements, evidence, owner and status (REG-02) +- [ ] Regulatory obligations are captured as requirements and traced (REG-03) +- [ ] Evidence is produced by the pipeline into the evidence pack (REG-04) +- [ ] Changes to certified items have a change impact assessment (REG-05) +- [ ] The certified baseline is recorded and regulated software is separated where applicable (REG-06) +- [ ] The safety lifecycle is followed where an integrity level applies (REG-07) +- [ ] Tools for certified builds are qualified or validated and frozen (REG-08) +- [ ] Records are retained, audits held annually and findings tracked (REG-09) +- [ ] Test house and notified body contact is owned by a named person (REG-10) +- [ ] Regulatory changes are reviewed quarterly (REG-11) +- [ ] Technical files are maintained as docs as code (REG-12) +- [ ] Compliance training is recorded (REG-13) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/security-and-data-protection.md b/content/guidelines/security-and-data-protection.md index c206be8..0714c62 100644 --- a/content/guidelines/security-and-data-protection.md +++ b/content/guidelines/security-and-data-protection.md @@ -90,6 +90,26 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Debug and manufacturing interfaces are protected in production (SEC-13) - [ ] A security incident procedure is defined (SEC-14) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Security requirements and a threat model exist and are updated on architecture change (SEC-01) +- [ ] The security architecture covers trust boundaries, secure boot, encrypted comms, secure update, protected storage and debug protection (SEC-02) +- [ ] Only approved cryptography and vetted libraries are used (SEC-03) +- [ ] Key hierarchy, protected signing, provisioning, rotation and revocation are documented (SEC-04) +- [ ] No secrets are in source, and scanning runs pre-commit and in CI (SEC-05) +- [ ] Secure coding rules and security-focused review apply, and parsers are fuzzed (SEC-06) +- [ ] Security testing is performed and findings are tracked (SEC-07) +- [ ] Vulnerability intake, disclosure policy, patch times and SBOM monitoring exist (SEC-08) +- [ ] Supply chain controls are in place (SEC-09) +- [ ] A data classification scheme has handling rules, including for AI tools (SEC-10) +- [ ] Privacy by design, retention and impact assessment are applied where needed (SEC-11) +- [ ] Access is least-privilege with multi-factor authentication and quarterly review (SEC-12) +- [ ] Debug and manufacturing interfaces are protected in production (SEC-13) +- [ ] A security incident procedure is defined (SEC-14) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/technology-and-third-party.md b/content/guidelines/technology-and-third-party.md index aa22811..d0cd764 100644 --- a/content/guidelines/technology-and-third-party.md +++ b/content/guidelines/technology-and-third-party.md @@ -74,6 +74,23 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Toolchain versions are pinned in containers and listed in the radar (TEC-10) - [ ] End-of-life dates are monitored (TEC-11) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A technology radar exists with adopt, trial, assess and hold (TEC-01) +- [ ] New dependencies and tools have an evaluation recorded in an ADR (TEC-02) +- [ ] A licence policy lists approved and prohibited licences (TEC-03) +- [ ] A manifest of third-party components exists and an SBOM is produced per release (TEC-04) +- [ ] Versions are pinned and checksums verified (TEC-05) +- [ ] Vendor SDKs are wrapped behind our interfaces and patches are tracked (TEC-06) +- [ ] Dependency updates are proposed automatically, with security patch times (TEC-07) +- [ ] Each dependency has an owner, and critical ones have an exit strategy (TEC-08) +- [ ] AI-generated code is checked for licence and provenance (TEC-09) +- [ ] Toolchain versions are pinned in containers and listed in the radar (TEC-10) +- [ ] End-of-life dates are monitored (TEC-11) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/testing-principles-and-strategy.md b/content/guidelines/testing-principles-and-strategy.md index 0b29da3..9b658a8 100644 --- a/content/guidelines/testing-principles-and-strategy.md +++ b/content/guidelines/testing-principles-and-strategy.md @@ -100,6 +100,27 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Exploratory testing is planned and time-boxed, with findings recorded (TST-14) - [ ] No failing test is skipped or deleted to pass a gate (TST-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] A test strategy exists per product with levels, entry and exit criteria, tools and environments (TST-01) +- [ ] Testing is weighted towards host-level tests (TST-02) +- [ ] Test names or metadata carry requirement IDs (TST-03) +- [ ] Coverage is measured with thresholds and a ratchet, and requirement coverage is reported (TST-04) +- [ ] Simulators and test doubles are maintained and validated against hardware (TST-05) +- [ ] Negative tests and fault injection cover parsers, comms, update, storage and security (TST-06) +- [ ] Every fixed defect has a regression test and the suite runs on every merge to `main` (TST-07) +- [ ] Test data and fixtures are versioned (TST-08) +- [ ] Rigs are managed as products (TST-09) +- [ ] Results are archived per release and linked to requirements (TST-10) +- [ ] Non-functional tests run nightly or continuously (TST-11) +- [ ] Verification of high-risk requirements is independent of the author (TST-12) +- [ ] Upgrade and rollback are tested from all supported versions (TST-13) +- [ ] Exploratory testing is planned and time-boxed, with findings recorded (TST-14) +- [ ] No failing test is skipped or deleted to pass a gate (TST-15) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/values-and-ways-of-working.md b/content/guidelines/values-and-ways-of-working.md index 6f2bbec..c51b448 100644 --- a/content/guidelines/values-and-ways-of-working.md +++ b/content/guidelines/values-and-ways-of-working.md @@ -93,6 +93,23 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] Changes are small enough to review within one working day (VAL-11) - [ ] Raising a risk, disagreement or mistake is treated as expected behaviour (VAL-12) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Values are published and used as tie-breakers (VAL-01) +- [ ] Every component, pipeline, rig and tool has a named owner in CODEOWNERS or the ownership register (VAL-02) +- [ ] The decision rights table is current (VAL-03) +- [ ] Escalation steps and time limits are agreed, and decisions are committed to once made (VAL-04, VAL-05) +- [ ] Decisions, agreements and meeting outcomes are written down within one working day (VAL-06) +- [ ] Each component has an owning site and a deputy at another site (VAL-07) +- [ ] Cross-site agreements cover overlap hours, response time and the handover note (VAL-08) +- [ ] All sites use the same tools and conventions, and variants have an ADR (VAL-09) +- [ ] Work status is visible in the tracker and pipeline (VAL-10) +- [ ] Changes are small enough to review within one working day (VAL-11) +- [ ] Raising a risk, disagreement or mistake is treated as expected behaviour (VAL-12) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/guidelines/version-control-and-versioning.md b/content/guidelines/version-control-and-versioning.md index a361e27..d39efd0 100644 --- a/content/guidelines/version-control-and-versioning.md +++ b/content/guidelines/version-control-and-versioning.md @@ -118,6 +118,27 @@ Tick an item when it is true for your project. Rule IDs point to the detail abov - [ ] The team understands git well enough to use it safely (VCS-14) - [ ] Commit subjects are imperative and short, and bodies say why (VCS-15) +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] Git is the single source of truth, the structure is documented, and no secrets or build outputs are committed (VCS-01) +- [ ] Branching is trunk-based with short-lived, correctly named branches (VCS-02) +- [ ] Commits follow Conventional Commits with scopes mapped to components (VCS-03) +- [ ] Breaking changes use `!` and a `BREAKING CHANGE:` footer (VCS-04) +- [ ] Footers carry `Refs:`, `ADR:` and `Assisted-by:` where relevant (VCS-05) +- [ ] Commits are atomic and buildable (VCS-06) +- [ ] A commit-msg hook and a CI lint enforce the format (VCS-07) +- [ ] `main` has linear history and shared branches are never force-pushed (VCS-08) +- [ ] Semantic versioning is defined for the product (VCS-09) +- [ ] The version comes from the tag, is injected by the build and is never hand-edited (VCS-10) +- [ ] Release tags are annotated, signed and immutable (VCS-11) +- [ ] Version bump, changelog and release notes are generated from commits (VCS-12) +- [ ] Back-ports use `cherry-pick -x` onto supported release branches (VCS-13) +- [ ] The team understands git well enough to use it safely (VCS-14) +- [ ] Commit subjects are imperative and short, and bodies say why (VCS-15) +``` + + ## Applying to personal projects and AI agents ### Personal projects diff --git a/content/templates/architecture-review-checklist.md b/content/templates/architecture-review-checklist.md index 4ba1900..3a047e9 100644 --- a/content/templates/architecture-review-checklist.md +++ b/content/templates/architecture-review-checklist.md @@ -89,6 +89,44 @@ An architecture passes when no item is unsatisfactory and every item that needs - [ ] **ARC-22 The environment is defined.** It names the processor, operating system or real-time operating system (RTOS) and version, toolchain, runtime dependencies and external services. - [ ] **ARC-23 Buy, build and open-source choices are justified.** Each records the licence, supplier health, total cost of ownership and how long it will be supported. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +### Vision and organisation +- [ ] **ARC-1 It gives a clear vision of the system.** The purpose, main capabilities, deployment context and guiding principles are stated well enough to steer the detailed design. +- [ ] **ARC-2 It is well organised.** It has a short overview, the background, the constraints and a structure that downstream designers can follow without guessing. Names are consistent throughout. +- [ ] **ARC-3 It allows for likely change.** The likely changes are named (a protocol, a cloud provider, a part that may go end of life), and stable interfaces keep each one contained. +- [ ] **ARC-4 It stays at the right level.** It defines boundaries, responsibilities and interface contracts, and leaves algorithms and screen layouts to the detailed design. +- [ ] **ARC-5 The views agree with each other.** Context, container, component and deployment views use the same names and the same message meanings across every interface. + +### Structure and decomposition +- [ ] **ARC-6 Data flow, control flow, the main elements and their interfaces are all shown.** It is clear which calls are synchronous and which are asynchronous, and where data is held. +- [ ] **ARC-7 Fine detail is left out.** Internal class structures and local state machines belong in the detailed design. +- [ ] **ARC-8 The top-level split is clean.** Each subsystem has one clear responsibility and few dependencies on the others. +- [ ] **ARC-9 It is as independent of technology as it can be.** Core logic does not depend on a framework, library or transport. Adapters or interfaces keep those at the edges. +- [ ] **ARC-10 It respects the constraints it cannot avoid.** It fits the flash, RAM, battery, bandwidth, message size and latency that the target has. +- [ ] **ARC-11 Alternatives were considered.** Each major choice records the options and why the others were rejected, usually as an [architecture decision record](adr.md). +- [ ] **ARC-12 Concerns are kept apart.** Domain logic, user interface, task scheduling and data management live in separate parts. If they do not, the design explains why. + +### Interfaces and quality attributes +- [ ] **ARC-13 External interfaces are defined and justified.** Machine and human interfaces have a formal description, such as OpenAPI, AsyncAPI, Protocol Buffers or a header file. Each states authentication, versioning and rate limits. +- [ ] **ARC-14 Robustness is specified.** Availability targets, recovery time, failover, watchdogs and degraded modes are stated and justified. +- [ ] **ARC-15 It is sensibly layered.** There are no circular dependencies between layers, and dependencies point towards the more stable, higher-level parts. +- [ ] **ARC-16 Coupling is low and cohesion is high.** Parts talk through narrow interfaces, and a change inside one part does not ripple into unrelated ones. +- [ ] **ARC-17 Every element has a resource budget.** Stack, heap, flash, CPU, energy per day, data per month and cloud cost all have a budget, as relevant. + +### Strategies +- [ ] **ARC-18 There is an input and output strategy.** It covers blocking and non-blocking I/O, buffering, direct memory access (DMA) where relevant, and what happens under back-pressure. +- [ ] **ARC-19 There is one error-handling strategy.** It defines error formats, retries with back-off and jitter, circuit breakers, and where failed messages go. + +### Project and lifecycle +- [ ] **ARC-20 It suits the delivery lifecycle.** It allows incremental delivery, automated builds and tests, independent deployment where needed, and safe roll-out of updates. +- [ ] **ARC-21 The system and business goals are stated,** and the architecture traces back to them. +- [ ] **ARC-22 The environment is defined.** It names the processor, operating system or real-time operating system (RTOS) and version, toolchain, runtime dependencies and external services. +- [ ] **ARC-23 Buy, build and open-source choices are justified.** Each records the licence, supplier health, total cost of ownership and how long it will be supported. +``` + + ## Review record Record the outcome of each review in a short, plain-text record kept with the design. diff --git a/content/templates/code-review-checklist.md b/content/templates/code-review-checklist.md index 430bd6b..5ab8a73 100644 --- a/content/templates/code-review-checklist.md +++ b/content/templates/code-review-checklist.md @@ -117,6 +117,108 @@ Let the tools do what tools do well. Formatting, warnings and most coding-standa - [ ] **C-2 Commits reference the ticket or requirement.** - [ ] **C-3 The pull request makes one change.** Unrelated fixes go in their own pull request. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +````markdown +## Before you start +- [ ] **R-1 The pull request says what changed and why,** and links the requirement or ticket. +- [ ] **R-2 CI has passed:** build, static analysis and tests. +- [ ] **R-3 The change is small enough to review properly.** If it is not, ask for it to be split. + +## Behaviour +- [ ] **F-1 The code matches the design and the requirements.** +- [ ] **F-2 It does what it should,** including at the edges: empty inputs, maximum sizes, the first and last items. +- [ ] **F-3 It does nothing it should not,** with no hidden side effects and no extra features. +- [ ] **F-4 It is as simple as it can be** while still doing the job. +- [ ] **F-5 It uses what already exists:** standard library functions, real-time operating system (RTOS) primitives, shared utilities, proven algorithms. +- [ ] **F-6 It uses sound patterns,** such as an explicit state machine instead of a tangle of flags, and no copied and pasted blocks. +- [ ] **F-7 Each function does one thing.** +- [ ] **F-8 Every variable is initialised before use,** and there are no unused variables or dead assignments. +- [ ] **F-9 Functions have a single exit** where the coding standard requires it, as MISRA C does. + +## Readability +- [ ] **S-1 It follows the team's style guide.** +- [ ] **S-2 Names say what things are,** and follow one convention. +- [ ] **S-3 File and function headers describe the intent,** not just the signature. +- [ ] **S-4 Comments explain why, not what.** Workarounds and temporary fixes say so and link a ticket. +- [ ] **S-5 There are no magic numbers.** Named constants, enumerations or configuration values replace them. +- [ ] **S-6 There is no dead code,** whether commented out or unreachable. +- [ ] **S-7 You could follow it without asking the author.** If you had to ask, the answer belongs in the code or a comment. +- [ ] **S-8 Readability has not been traded for an optimisation nobody measured.** + +## Structure +- [ ] **A-1 Functions are short** enough to read without scrolling back and forth. +- [ ] **A-2 Logic is reused, not duplicated.** +- [ ] **A-3 Global variables are avoided,** and every variable has the smallest scope it can. +- [ ] **A-4 Related code is grouped together,** in the same module or class. +- [ ] **A-5 Types are explicit and portable,** such as `int32_t` instead of `long`, and unsigned where a value cannot be negative. +- [ ] **A-6 Nesting is shallow.** There are no `if` statements nested more than two deep, and no `switch` inside a `switch`. +- [ ] **A-7 Values that might change are configuration,** not hard-coded. + +## Errors and defensive coding +- [ ] **E-1 Inputs are checked** for range, length, null and sign before use. +- [ ] **E-2 Errors are returned to the caller, and the caller handles them.** No error code is silently dropped. +- [ ] **E-3 Every `switch` has a `default`** that catches the unexpected. +- [ ] **E-4 Array indexes and pointers are bounds-checked.** +- [ ] **E-5 Arithmetic cannot overflow, underflow or truncate** without the code noticing. +- [ ] **E-6 Resources are released on every path,** including error paths: memory, locks, file handles and sockets. +- [ ] **E-7 It copes with failure around it:** a service that is down, a database write that fails, malformed data, a full queue. +- [ ] **E-8 Operations that may be retried are safe to retry.** +- [ ] **E-9 It behaves under load,** or the limits are stated. + +## Security +- [ ] **SEC-1 External input is validated,** from a serial port, a bus, Bluetooth, the network or a user, including its length. +- [ ] **SEC-2 Memory access is safe,** with no buffer overflows and no unchecked copies. +- [ ] **SEC-3 Injection is not possible,** for example database query injection, command injection or cross-site scripting. +- [ ] **SEC-4 Secrets are not in the code or the logs.** +- [ ] **SEC-5 Debug interfaces are disabled or protected in release builds,** such as debug probe ports and debug serial consoles. + +## Memory +- [ ] **M-1 Dynamic allocation is avoided,** or it is bounded and predictable. +- [ ] **M-2 Every allocation is checked for failure.** +- [ ] **M-3 Stack use is analysed,** and the worst case is recorded, especially in interrupts and any recursion. +- [ ] **M-4 Pointers are initialised and checked before use.** + +## Timing and concurrency +- [ ] **T-1 Worst-case timing is bounded.** There are no unbounded loops or recursion. +- [ ] **T-2 There are no race conditions.** Variables shared with an interrupt are `volatile`, and multi-byte values are read and written atomically. +- [ ] **T-3 Code called from more than one context is re-entrant and thread-safe.** +- [ ] **T-4 Interrupt handlers are short and never block,** and interrupts are not masked for long. +- [ ] **T-5 Interrupts pass work to tasks safely,** through queues, flags or notifications. +- [ ] **T-6 Shared resources are protected** by a mutex or semaphore, and priority inversion is avoided or handled. +- [ ] **T-7 Task priorities match how critical each task is.** +- [ ] **T-8 The watchdog is kicked only when every task is making progress,** not from a timer that runs whatever happens. + +## Hardware +- [ ] **H-1 Input and output operations leave the hardware in the right state.** +- [ ] **H-2 The interface timing meets the datasheet,** including setup, hold and minimum delays. +- [ ] **H-3 Multi-byte hardware registers cannot change while they are read or written.** +- [ ] **H-4 A reset puts the system in a known state.** +- [ ] **H-5 Brown-out and power loss are handled.** +- [ ] **H-6 Entering and leaving sleep is correct,** with timers and peripherals reconfigured. +- [ ] **H-7 Unused interrupt vectors go to an error handler.** +- [ ] **H-8 Non-volatile writes survive power loss,** for example by keeping two copies of each record in EEPROM (electrically erasable programmable read-only memory) or flash. + +## Logging +- [ ] **L-1 Logs record what someone will need to diagnose a problem,** including the values that matter. +- [ ] **L-2 Each message has the right level:** debug, info, warning or error. +- [ ] **L-3 A message makes sense on its own,** without the source code open beside it. +- [ ] **L-4 Logging is not excessive,** and nothing sensitive is logged. + +## Tests and tools +- [ ] **TST-1 New behaviour has tests,** and bug fixes have a test that failed before the fix. +- [ ] **TST-2 Modules can be tested on their own,** with hardware access and delays behind an interface that a test can replace. +- [ ] **TST-3 Coverage has been checked** for the changed code. +- [ ] **TST-4 Static analysis is clean,** or each finding it suppresses has a reason, against MISRA C, cppcheck or the team's ruleset. +- [ ] **TST-5 The build has no warnings,** with warnings enabled, and informational messages have been read. + +## Commits +- [ ] **C-1 Each commit message says what changed and why.** It follows the [commit conventions](pull-request-and-commits.md). +- [ ] **C-2 Commits reference the ticket or requirement.** +- [ ] **C-3 The pull request makes one change.** Unrelated fixes go in their own pull request. +```` + + ## Further reading Many of the embedded items follow the peer review checklist in Philip Koopman's *Better Embedded System Software* (Drumnadrochit Education, 2010). diff --git a/content/templates/debugging-checklist.md b/content/templates/debugging-checklist.md index c2d464b..f7e5268 100644 --- a/content/templates/debugging-checklist.md +++ b/content/templates/debugging-checklist.md @@ -52,6 +52,52 @@ To report a defect, or to close one, use the [defect report checklist](defect-re - [ ] **DBG-34 Look for the same mistake elsewhere** in the code. - [ ] **DBG-35 Run the full regression suite** before you call it done. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +````markdown +## Approach +- [ ] **DBG-1 Set a time limit for quick debugging.** When it runs out, stop poking and make a plan. +- [ ] **DBG-2 Check whether someone has already found it.** Search the tracker, the knowledge base and the recent commit history. +- [ ] **DBG-3 Use every tool you have:** the debugger and debug probe, compiler warnings, static analysis, sanitisers, trace and a logic analyser. +- [ ] **DBG-4 Assume the bug is in your code** until you have evidence that it is in the compiler, the operating system or the hardware. +- [ ] **DBG-5 Do not change code you do not understand** in the hope that the problem goes away. +- [ ] **DBG-6 Use more than one technique,** such as bisection, assertions, traces and comparing a good build with a bad one. +- [ ] **DBG-7 Ask for help** when you stop making progress. +- [ ] **DBG-8 Tell people early** if the investigation will take longer than planned. +- [ ] **DBG-9 Know when to step away** and come back with fresh eyes. +- [ ] **DBG-10 Check that the fix cures the cause,** not just the symptom you saw. +- [ ] **DBG-11 Write down what you learnt,** so nobody has to find it again. + +## Finding the fault +- [ ] **DBG-12 State a hypothesis** that explains what you see, before the next test run. +- [ ] **DBG-13 Shrink the test case** to the smallest set of steps that still fails. +- [ ] **DBG-14 Reproduce it in more than one way,** or under different conditions. +- [ ] **DBG-15 Gather more data** to choose between competing hypotheses: logs, registers, traces and captures. +- [ ] **DBG-16 Look at what does not fail.** It narrows the search as much as what does. +- [ ] **DBG-17 Think of other explanations** when your first idea does not hold up. +- [ ] **DBG-18 Narrow the search by halves,** with `git bisect` or by switching modules out. +- [ ] **DBG-19 Look at what changed recently** in the code, the configuration and the build. +- [ ] **DBG-20 Widen the search** when the symptom appears far from the cause, as it does with memory corruption. +- [ ] **DBG-21 Test the parts on their own,** adding them back one at a time. +- [ ] **DBG-22 Suspect the code that has had bugs before.** +- [ ] **DBG-23 Add logging and instrumentation** where a debugger would change the timing. +- [ ] **DBG-24 Check the usual suspects:** off-by-one errors, uninitialised variables, stack overflow, integer truncation and a missing `volatile`. +- [ ] **DBG-25 Explain the problem out loud,** line by line, to a colleague or a rubber duck. + +## Fixing it +- [ ] **DBG-26 Understand the cause before you edit anything.** +- [ ] **DBG-27 Confirm that the diagnosis explains every symptom,** not just some of them. +- [ ] **DBG-28 Write a test that fails** because of the bug, before you fix it. +- [ ] **DBG-29 Keep the evidence:** the failing build, the logs and the captures. +- [ ] **DBG-30 Fix the cause, not the symptom.** +- [ ] **DBG-31 Make one change at a time,** and test after each one. +- [ ] **DBG-32 Check the fix against the design and the coding standards,** and make sure it does not break anything that depends on the old behaviour. +- [ ] **DBG-33 Do not rush a fix out under pressure** without testing it. +- [ ] **DBG-34 Look for the same mistake elsewhere** in the code. +- [ ] **DBG-35 Run the full regression suite** before you call it done. +```` + + ## Further reading This checklist follows the debugging checklist in Steve McConnell's *Code Complete* (second edition, Microsoft Press, 2004). diff --git a/content/templates/defect-report-checklist.md b/content/templates/defect-report-checklist.md index 14884c7..ae3d692 100644 --- a/content/templates/defect-report-checklist.md +++ b/content/templates/defect-report-checklist.md @@ -110,3 +110,24 @@ Severity and priority are separate. Severity is how much damage the defect does, - [ ] **DR-5 The report lists the tests** that show the fix works, including the new regression test. - [ ] **DR-6 Commits and the pull request reference the defect,** so the fix can be traced both ways. - [ ] **DR-7 S1 and S2 defects in the field get a [postmortem](postmortem.md).** + +**As Markdown.** To copy it into an issue, a pull request or a review record: + +````markdown +## Raising a defect +- [ ] **DC-1 Describe the environment.** Give the hardware variant and revision, the firmware or software version with its commit, and the operating system or RTOS version. Include any non-default settings, build flags or feature flags, and the state the system was in before the failure. +- [ ] **DC-2 Reproduce it.** Retest until you have the exact steps in the right order. If it is intermittent, say how often it happens, for example "3 in 100 power cycles". Narrow down which part of the system is involved, using error codes and logs. +- [ ] **DC-3 Attach the evidence.** Include console logs, traces with their correlation IDs, logic analyser or network captures, crash dumps, register state and backtraces, and screenshots or recordings. +- [ ] **DC-4 Stick to the facts.** Say what happened and what you expected. Leave out guesses about the cause, opinions and blame. Use the headings in the template below. +- [ ] **DC-5 Set the severity, and let the product owner set the priority** (see below). + +## Closing a defect +- [ ] **DR-1 You understand the area you changed,** not just the line that failed. The [debugging checklist](debugging-checklist.md) helps here. +- [ ] **DR-2 The defect is classified,** as a requirement, design, architecture, integration or coding defect. The class shows where the process let it through. +- [ ] **DR-3 The report says what was wrong** with the old behaviour. +- [ ] **DR-4 The report says what changed** to fix it. +- [ ] **DR-5 The report lists the tests** that show the fix works, including the new regression test. +- [ ] **DR-6 Commits and the pull request reference the defect,** so the fix can be traced both ways. +- [ ] **DR-7 S1 and S2 defects in the field get a [postmortem](postmortem.md).** +```` + diff --git a/content/templates/definition-of-done.md b/content/templates/definition-of-done.md index a041104..c643b41 100644 --- a/content/templates/definition-of-done.md +++ b/content/templates/definition-of-done.md @@ -29,6 +29,28 @@ Add these when your product, domain or regulator needs them: - [ ] The customer or user has accepted the change. - [ ] New behaviour sits behind a feature flag, with a plan to remove the flag. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +````markdown +## Checklist +- [ ] **DoD-1 The code builds without warnings** on every target, with warnings enabled. +- [ ] **DoD-2 The developer has tested it.** Unit tests cover the change, including edge cases and error paths, and it has been run locally or on target. +- [ ] **DoD-3 It meets the acceptance criteria.** Someone other than the author has checked it against them and against the test scenarios. +- [ ] **DoD-4 It has been reviewed.** A peer has reviewed the change against the [code review checklist](code-review-checklist.md), and the comments are resolved. +- [ ] **DoD-5 It follows the coding standards** for formatting, naming and structure. +- [ ] **DoD-6 The CI pipeline passed.** The build, static analysis and automated tests all pass in CI, not just on a laptop. +- [ ] **DoD-7 The documentation is updated.** Design notes, interface specifications, user help and release notes match the change. +- [ ] **DoD-8 Technical debt is recorded.** Any shortcut or known problem has a ticket, or a note on the story that points to one. + +## Extra items to consider +- [ ] A security review is complete. +- [ ] Performance, memory or power measurements are within budget. +- [ ] Code coverage meets the agreed threshold. +- [ ] The customer or user has accepted the change. +- [ ] New behaviour sits behind a feature flag, with a plan to remove the flag. +```` + + ## Where to use it - In the pull request template, as the checklist the author ticks (see the [pull request template](pull-request-and-commits.md)). diff --git a/content/templates/definition-of-ready.md b/content/templates/definition-of-ready.md index 66602f8..663d2b5 100644 --- a/content/templates/definition-of-ready.md +++ b/content/templates/definition-of-ready.md @@ -18,6 +18,19 @@ The Definition of Ready is a gate, not a form to fill in. If the team keeps wavi - [ ] **DoR-6 Dependencies are resolved or planned.** Nothing outside the team blocks the item, or the blocker has an owner and a date. - [ ] **DoR-7 The story is Independent, Negotiable, Valuable, Estimable, Small and Testable (INVEST).** The table below explains each letter. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +- [ ] **DoR-1 The story is clear.** It says who wants what and why, in a sentence or two. "As a ... I want ... so that ..." is a good default. +- [ ] **DoR-2 Acceptance criteria are written and agreed.** Each one is a concrete pass or fail check, agreed by the product owner and the people who will build and test it. +- [ ] **DoR-3 The design is understood.** Where the item needs design work, the approach has been discussed and either written down or understood well enough to start. +- [ ] **DoR-4 The architecture is understood.** The services, interfaces, environments and decisions the item depends on are known, and it fits the system as it stands. +- [ ] **DoR-5 Non-functional requirements are stated.** Performance, security, reliability, power and compliance needs are written down where they apply. +- [ ] **DoR-6 Dependencies are resolved or planned.** Nothing outside the team blocks the item, or the blocker has an owner and a date. +- [ ] **DoR-7 The story is Independent, Negotiable, Valuable, Estimable, Small and Testable (INVEST).** The table below explains each letter. +``` + + ## The INVEST test INVEST is a quick test of whether a user story is well formed. diff --git a/content/templates/design-review-checklist.md b/content/templates/design-review-checklist.md index f67fc6d..bc817d0 100644 --- a/content/templates/design-review-checklist.md +++ b/content/templates/design-review-checklist.md @@ -84,6 +84,76 @@ For a whole system or a high-level design, use the [architecture review checklis - [ ] **SD-46 It is testable.** It has seams for stubs, test points and logging. - [ ] **SD-47 Static analysis and any code generation are part of the plan,** with traceability through the lifecycle. +**As Markdown.** To copy it into an issue, a pull request or a review record: + +```markdown +### General +- [ ] **SD-1 Each part of the design meets its own checklist.** Diagrams, models and descriptions are clear, accurate and use their notation correctly. +- [ ] **SD-2 It supports both the product goals and the project goals,** such as the commercial aim and the delivery date. +- [ ] **SD-3 It is feasible** with the technology, budget, schedule and skills available. +- [ ] **SD-4 Known risks are recorded,** technical and delivery risks alike, each with a mitigation or a plan. +- [ ] **SD-5 The notation suits the job,** for example sequence diagrams for interactions and state charts for modes. +- [ ] **SD-6 The formality matches the work.** A safety function needs more rigour than a test utility. +- [ ] **SD-7 Prototypes and earlier phases have fed back into the design.** +- [ ] **SD-8 Proven designs are reused** where they fit, such as existing drivers and frameworks. +- [ ] **SD-9 It is complete enough to start implementation** with confidence. + +### Design quality +- [ ] **SD-10 It has conceptual integrity.** The parts follow one set of ideas and fit together. +- [ ] **SD-11 It fits the target.** It works within the memory, CPU, hardware and environmental limits. +- [ ] **SD-12 It uses well-known techniques.** Anything unusual is there for a stated reason. +- [ ] **SD-13 It prefers simple to clever.** +- [ ] **SD-14 It is as simple as it can be while still doing the job.** +- [ ] **SD-15 It is lean.** Every part is needed, and nothing is there "just in case". +- [ ] **SD-16 The parts most likely to change are easy to change,** through low coupling, clear interfaces and modularity. +- [ ] **SD-17 Reusable parts are abstracted properly,** for example a hardware abstraction layer, a driver or a shared service. +- [ ] **SD-18 It could move to another platform** with reasonable effort, where that matters. +- [ ] **SD-19 Complexity is kept low,** for example the cyclomatic complexity of each module and function. +- [ ] **SD-20 Another engineer can hold it in their head.** +- [ ] **SD-21 It is robust** against bad inputs, timing variations and unexpected resets. + +### Traceability +- [ ] **SD-22 Every functional and non-functional requirement is addressed,** and each part of the design traces back to a requirement. +- [ ] **SD-23 There is no scope creep.** The design adds no features the requirements do not ask for. +- [ ] **SD-24 Requirement coverage is recorded,** in a traceability matrix where the project needs one. + +### Level of detail +- [ ] **SD-25 There is enough detail to hand over** for coding and for writing the test plan. +- [ ] **SD-26 Sequence diagrams, state machines and flowcharts are clear and complete.** + +### Completeness +- [ ] **SD-27 Assumptions, constraints, decisions and dependencies are all written down.** +- [ ] **SD-28 The uncertain or high-risk parts are called out,** each with a fallback or mitigation. +- [ ] **SD-29 Gaps and open points are visible,** with a reason and an owner for each. +- [ ] **SD-30 Reasonable alternatives were considered,** including not solving the problem in software at all. +- [ ] **SD-31 Trade-offs are explained,** such as performance against power, or memory against speed. + +### Consistency +- [ ] **SD-32 It matches the architecture above it** and what the modules around it expect. +- [ ] **SD-33 Issues deferred from earlier phases are dealt with.** +- [ ] **SD-34 Open points in the upstream requirements have been assessed.** +- [ ] **SD-35 It makes sense from the top down and from the bottom up.** +- [ ] **SD-36 It is consistent with similar modules,** for example those sharing a driver or a protocol. +- [ ] **SD-37 It works with the build, CI, test and deployment environments.** + +### Performance +- [ ] **SD-38 Timing, memory and throughput assumptions are written down.** +- [ ] **SD-39 The performance-critical paths have evidence behind them,** from a prototype, a benchmark or a design already proven in the same setting. + +### Maintainability +- [ ] **SD-40 Someone else could maintain it.** A new engineer could understand and change it without the author. +- [ ] **SD-41 Reused components are documented,** along with their effect on the design and on integration. +- [ ] **SD-42 Extension points are identified,** such as hooks and interfaces for likely additions. +- [ ] **SD-43 It will not decay quickly.** Tightly coupled areas, which tend to get worse with each change, are kept to a minimum. + +### Compliance, safety and testability +- [ ] **SD-44 It follows the standards that apply,** such as MISRA C, IEC 61508, ISO 26262 or the platform's own rules. +- [ ] **SD-45 Fault behaviour is designed.** Watchdog, brown-out, reset and fault modes are described. +- [ ] **SD-46 It is testable.** It has seams for stubs, test points and logging. +- [ ] **SD-47 Static analysis and any code generation are part of the plan,** with traceability through the lifecycle. +``` + + ## Further reading The structure of this checklist follows the design checklists in Steve McConnell's *Code Complete* (second edition, Microsoft Press, 2004), extended for embedded systems. From 690ae5260a8317b7846add70d5e586f3a18cf825 Mon Sep 17 00:00:00 2001 From: Mark Bacon Date: Mon, 19 Oct 2026 13:13:46 +0100 Subject: [PATCH 3/4] Navigation: group the sections, and the sections' pages, with redirects - The top of the navigation is four headings: Ways of working (Guidelines, Standards, Templates & Checklists, Firmitas), Learn (Primers, Guides, Handbook), Reference (Glossary, Tech Radar) and Blog. The radar chart is linked from the Tech Radar section instead of the top level. - Inside the sections, pages sit in groups, each with a short landing page: the guidelines in 'Using the guidelines' and their seven parts; the standards, guides and templates in their groups, with each multi-chapter guide inside its group; the primers by area. The source files do not move: py-doc's site_path places the pages. Word and PDF follow the same structure. - Redirects keep the 205 old page addresses working, and tarf.co.uk's redirects and the radar chart's links point at the pages' new places. - The home page shows a card for each section within the groups, with refreshed descriptions. Co-Authored-By: Claude Opus 5.5 --- content/guidelines/part-code-and-build.md | 17 + .../part-delivery-research-and-people.md | 15 + .../part-diagnostics-and-field-insight.md | 14 + content/guidelines/part-foundations.md | 17 + .../part-release-risk-and-compliance.md | 15 + ...rt-requirements-architecture-and-design.md | 18 + content/guidelines/part-verification.md | 14 + content/guidelines/using-the-guidelines.md | 19 + .../guides/group-architecture-and-design.md | 18 + content/guides/group-connected-devices.md | 16 + content/guides/group-engineering-practice.md | 17 + content/standards/group-coding.md | 15 + content/standards/group-connected-devices.md | 17 + .../standards/group-design-and-interfaces.md | 16 + content/templates/group-checklists.md | 19 + .../group-delivery-and-operations.md | 26 + .../group-requirements-design-and-testing.md | 19 + .../group-vision-and-architecture.md | 20 + py-doc.yml | 459 +++++++++--------- site/docs/radar-chart/index.md | 2 +- site/mkdocs.tarf.yml | 100 ++-- site/mkdocs.yml | 352 +++++++++++++- site/overrides/partials/cards.html | 13 +- 23 files changed, 961 insertions(+), 277 deletions(-) create mode 100644 content/guidelines/part-code-and-build.md create mode 100644 content/guidelines/part-delivery-research-and-people.md create mode 100644 content/guidelines/part-diagnostics-and-field-insight.md create mode 100644 content/guidelines/part-foundations.md create mode 100644 content/guidelines/part-release-risk-and-compliance.md create mode 100644 content/guidelines/part-requirements-architecture-and-design.md create mode 100644 content/guidelines/part-verification.md create mode 100644 content/guidelines/using-the-guidelines.md create mode 100644 content/guides/group-architecture-and-design.md create mode 100644 content/guides/group-connected-devices.md create mode 100644 content/guides/group-engineering-practice.md create mode 100644 content/standards/group-coding.md create mode 100644 content/standards/group-connected-devices.md create mode 100644 content/standards/group-design-and-interfaces.md create mode 100644 content/templates/group-checklists.md create mode 100644 content/templates/group-delivery-and-operations.md create mode 100644 content/templates/group-requirements-design-and-testing.md create mode 100644 content/templates/group-vision-and-architecture.md diff --git a/content/guidelines/part-code-and-build.md b/content/guidelines/part-code-and-build.md new file mode 100644 index 0000000..69b5127 --- /dev/null +++ b/content/guidelines/part-code-and-build.md @@ -0,0 +1,17 @@ +--- +title: Code and build +--- + +# Code and build + +Coding principles and standards, version control, pull requests and pipelines. + +| Page | +| --- | +| [Coding principles governance](coding-principles.md) | +| [Coding standard](coding-standard.md) | +| [Version control, commits and versioning](version-control-and-versioning.md) | +| [Pull requests and code review](pull-requests-and-review.md) | +| [Pipelines and quality gates](pipelines-and-quality-gates.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-delivery-research-and-people.md b/content/guidelines/part-delivery-research-and-people.md new file mode 100644 index 0000000..f67da60 --- /dev/null +++ b/content/guidelines/part-delivery-research-and-people.md @@ -0,0 +1,15 @@ +--- +title: Delivery, research and people +--- + +# Delivery, research and people + +Planning and delivery, research and prototyping, and competence and onboarding. + +| Page | +| --- | +| [Planning, delivery and improvement](planning-delivery-and-improvement.md) | +| [Research, prototyping and experiments](research-and-prototyping.md) | +| [Competence, tooling and onboarding](competence-tooling-and-onboarding.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-diagnostics-and-field-insight.md b/content/guidelines/part-diagnostics-and-field-insight.md new file mode 100644 index 0000000..c2c70bd --- /dev/null +++ b/content/guidelines/part-diagnostics-and-field-insight.md @@ -0,0 +1,14 @@ +--- +title: Diagnostics and field insight +--- + +# Diagnostics and field insight + +Logging, debug and diagnostics, and observability in the field. + +| Page | +| --- | +| [Logging, debug and fault diagnostics](logging-debug-and-diagnostics.md) | +| [Observability and telemetry](observability-and-telemetry.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-foundations.md b/content/guidelines/part-foundations.md new file mode 100644 index 0000000..a0d4361 --- /dev/null +++ b/content/guidelines/part-foundations.md @@ -0,0 +1,17 @@ +--- +title: Foundations +--- + +# Foundations + +Governance, values, quality, documentation and the use of AI agents. + +| Page | +| --- | +| [Guidelines governance](guidelines-governance.md) | +| [Engineering values and ways of working](values-and-ways-of-working.md) | +| [Quality policy and quality attributes](quality-policy-and-attributes.md) | +| [Documentation as code and terminology](documentation-as-code.md) | +| [AI agent usage](ai-agent-usage.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-release-risk-and-compliance.md b/content/guidelines/part-release-risk-and-compliance.md new file mode 100644 index 0000000..bf9744f --- /dev/null +++ b/content/guidelines/part-release-risk-and-compliance.md @@ -0,0 +1,15 @@ +--- +title: Release, risk and compliance +--- + +# Release, risk and compliance + +Releases and updates, security and data protection, and safety and regulation. + +| Page | +| --- | +| [Release, update and production](release-update-and-production.md) | +| [Security and data protection](security-and-data-protection.md) | +| [Safety, regulatory and certification](safety-regulatory-and-certification.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-requirements-architecture-and-design.md b/content/guidelines/part-requirements-architecture-and-design.md new file mode 100644 index 0000000..720b9d1 --- /dev/null +++ b/content/guidelines/part-requirements-architecture-and-design.md @@ -0,0 +1,18 @@ +--- +title: Requirements, architecture and design +--- + +# Requirements, architecture and design + +Requirements and traceability, architecture principles, decision records, interfaces, components and technology choices. + +| Page | +| --- | +| [Requirements and traceability](requirements-and-traceability.md) | +| [Architecture principles governance](architecture-principles.md) | +| [Decision records: RFCs and ADRs](decision-records.md) | +| [Interfaces and hardware and software co-design](interfaces-and-co-design.md) | +| [Components, reuse and variants](components-reuse-and-variants.md) | +| [Technology selection and third-party components](technology-and-third-party.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/part-verification.md b/content/guidelines/part-verification.md new file mode 100644 index 0000000..7e88b28 --- /dev/null +++ b/content/guidelines/part-verification.md @@ -0,0 +1,14 @@ +--- +title: Verification +--- + +# Verification + +Testing, and managing defects and technical debt. + +| Page | +| --- | +| [Testing principles and strategy](testing-principles-and-strategy.md) | +| [Defect and technical debt management](defects-and-technical-debt.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guidelines/using-the-guidelines.md b/content/guidelines/using-the-guidelines.md new file mode 100644 index 0000000..3485e27 --- /dev/null +++ b/content/guidelines/using-the-guidelines.md @@ -0,0 +1,19 @@ +--- +title: Using the guidelines +--- + +# Using the guidelines + +How to adopt the guidelines in an organisation, a team or a personal project, the rules that always apply, the principles behind them, and the checklists. + +| Page | +| --- | +| [Core rules](core-rules.md) | +| [Adopting the guidelines across several products](organisation-adoption.md) | +| [Using the guidelines on personal projects](personal-projects.md) | +| [Principles catalogue](principles-catalogue.md) | +| [Business and vertical principles](business-principles.md) | +| [Agent rules (condensed)](agent-rules.md) | +| [Combined checklists](checklists.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guides/group-architecture-and-design.md b/content/guides/group-architecture-and-design.md new file mode 100644 index 0000000..ddf8c48 --- /dev/null +++ b/content/guides/group-architecture-and-design.md @@ -0,0 +1,18 @@ +--- +title: Architecture and design +--- + +# Architecture and design + +Modelling and scaling architecture, and writing and reviewing designs and decisions. + +| Page | +| --- | +| [C4 modelling for IoT and connected systems](c4-model/index.md) | +| [Scaling the practice of architecture](scaling-architecture/index.md) | +| [Writing ADRs and RFCs](decision-records.md) | +| [Writing a high-level design](high-level-design.md) | +| [Writing a software design specification](software-design-specification.md) | +| [Running an architecture review board](architecture-review-board.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guides/group-connected-devices.md b/content/guides/group-connected-devices.md new file mode 100644 index 0000000..dd5020b --- /dev/null +++ b/content/guides/group-connected-devices.md @@ -0,0 +1,16 @@ +--- +title: Connected devices +--- + +# Connected devices + +Endpoint and gateway architecture, fleet operations, cyber security and hardware-in-the-loop testing. + +| Page | +| --- | +| [IoT endpoint and edge gateway architecture](iot-endpoint-and-gateway-architecture/index.md) | +| [IoT fleet operations, telemetry and digital twins](iot-fleet-operations/index.md) | +| [Cyber security and threat modelling for connected systems](cybersecurity/index.md) | +| [Hardware-in-the-loop and automated testing](hil-and-automated-testing/index.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/guides/group-engineering-practice.md b/content/guides/group-engineering-practice.md new file mode 100644 index 0000000..de97cc3 --- /dev/null +++ b/content/guides/group-engineering-practice.md @@ -0,0 +1,17 @@ +--- +title: Engineering practice +--- + +# Engineering practice + +Git, code review, requirements, defects and the way a team works. + +| Page | +| --- | +| [Git](git/index.md) | +| [Reviewing code](code-review.md) | +| [Agile requirements and user stories](agile-requirements-and-user-stories.md) | +| [Defect management and debugging](defect-management-and-debugging.md) | +| [Ways of working](ways-of-working/index.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/standards/group-coding.md b/content/standards/group-coding.md new file mode 100644 index 0000000..06111ef --- /dev/null +++ b/content/standards/group-coding.md @@ -0,0 +1,15 @@ +--- +title: Coding +--- + +# Coding + +How C and Python are written, and MISRA C. + +| Page | +| --- | +| [C coding standard](c-coding-standard.md) | +| [MISRA C](misra-c.md) | +| [Python for supporting tools](python.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/standards/group-connected-devices.md b/content/standards/group-connected-devices.md new file mode 100644 index 0000000..87056c0 --- /dev/null +++ b/content/standards/group-connected-devices.md @@ -0,0 +1,17 @@ +--- +title: Connected devices +--- + +# Connected devices + +What a field-deployed connected device must do: architecture, power, payloads, storage and manufacture. + +| Page | +| --- | +| [IoT device architecture principles](iot-device-architecture-principles.md) | +| [Battery budgeting and power profiling](iot-battery-budgeting.md) | +| [Constrained binary payloads](constrained-binary-payloads.md) | +| [Offline storage and synchronisation](iot-edge-offline-storage.md) | +| [Serialisation, provisioning and factory test](device-serialisation-and-factory-test.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/standards/group-design-and-interfaces.md b/content/standards/group-design-and-interfaces.md new file mode 100644 index 0000000..714f04a --- /dev/null +++ b/content/standards/group-design-and-interfaces.md @@ -0,0 +1,16 @@ +--- +title: Design and interfaces +--- + +# Design and interfaces + +Architecture principles, API design, identifiers and LwM2M objects. + +| Page | +| --- | +| [Software architecture principles](software-architecture-principles.md) | +| [API design and error handling](api-design.md) | +| [Unique identifiers](unique-identifiers.md) | +| [Designing LwM2M objects and resources](lwm2m-objects.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/templates/group-checklists.md b/content/templates/group-checklists.md new file mode 100644 index 0000000..2bc2b62 --- /dev/null +++ b/content/templates/group-checklists.md @@ -0,0 +1,19 @@ +--- +title: Checklists +--- + +# Checklists + +Checklists for the reviews and quality gates of a project. + +| Page | +| --- | +| [Definition of Ready](definition-of-ready.md) | +| [Definition of Done](definition-of-done.md) | +| [Architecture review checklist](architecture-review-checklist.md) | +| [Design review checklist](design-review-checklist.md) | +| [Code review checklist](code-review-checklist.md) | +| [Debugging checklist](debugging-checklist.md) | +| [Defect report checklist](defect-report-checklist.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/templates/group-delivery-and-operations.md b/content/templates/group-delivery-and-operations.md new file mode 100644 index 0000000..ce7cb25 --- /dev/null +++ b/content/templates/group-delivery-and-operations.md @@ -0,0 +1,26 @@ +--- +title: Delivery and operations +--- + +# Delivery and operations + +Templates for running a project, a team and a release. + +| Page | +| --- | +| [Systems engineering management plan](systems-engineering-management-plan.md) | +| [Team working agreement](team-working-agreement.md) | +| [Meeting minutes](meeting-minutes.md) | +| [Decision log](decision-log.md) | +| [Risk register](risk-register.md) | +| [Technical debt register](technical-debt-register.md) | +| [Release plan](release-plan.md) | +| [Software bill of materials](sbom.md) | +| [Pull requests and commits](pull-request-and-commits.md) | +| [Postmortem](postmortem.md) | +| [Lessons learned](lessons-learned.md) | +| [Task brief for an AI agent](agent-task-brief.md) | +| [AGENTS.md for AI agents](agents-md.md) | +| [Product conformance profile and component register](product-conformance-profile.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/templates/group-requirements-design-and-testing.md b/content/templates/group-requirements-design-and-testing.md new file mode 100644 index 0000000..0655b4e --- /dev/null +++ b/content/templates/group-requirements-design-and-testing.md @@ -0,0 +1,19 @@ +--- +title: Requirements, design and testing +--- + +# Requirements, design and testing + +Templates for requirements, interfaces, designs, experiments and tests. + +| Page | +| --- | +| [Requirements and quality scenarios](requirements.md) | +| [NFR scenario](nfr-scenario.md) | +| [Requirements traceability matrix](requirements-traceability-matrix.md) | +| [Interface specification](interface-specification.md) | +| [Software design specification](software-design-specification.md) | +| [Experiment record](experiment-record.md) | +| [Test plan](test-plan.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/content/templates/group-vision-and-architecture.md b/content/templates/group-vision-and-architecture.md new file mode 100644 index 0000000..b7cb014 --- /dev/null +++ b/content/templates/group-vision-and-architecture.md @@ -0,0 +1,20 @@ +--- +title: Vision and architecture +--- + +# Vision and architecture + +Templates for setting direction and describing an architecture. + +| Page | +| --- | +| [Project vision](project-vision.md) | +| [Architecture vision](architecture-vision.md) | +| [Architecture principles](architecture-principles.md) | +| [Architecture document](architecture-document.md) | +| [Architecture canvases](architecture-canvases.md) | +| [Crosscutting concerns](crosscutting-concerns.md) | +| [Architecture decision record](adr.md) | +| [Request for comments](rfc.md) | + +[[CAPTION:Table]] The pages in this group. diff --git a/py-doc.yml b/py-doc.yml index 98b7aab..572c285 100644 --- a/py-doc.yml +++ b/py-doc.yml @@ -14,124 +14,137 @@ outputs: # in site/docs/blog/ for MkDocs Material's blog plugin. documents: guidelines: - # Guidelines (from EngineeringProcess): the overview and core rules, the 26 guidelines in number order, - # then the principles, adoption, personal-project, agent and checklist pages. + # Guidelines (from EngineeringProcess): how to use them, then the guidelines in their seven parts. Each group's + # landing page is a chapter, and its pages are sections of it (heading_offset 1); on the site each is a group. sources: - content/guidelines/index.md - - content/guidelines/core-rules.md - - content/guidelines/guidelines-governance.md - - content/guidelines/values-and-ways-of-working.md - - content/guidelines/quality-policy-and-attributes.md - - content/guidelines/documentation-as-code.md - - content/guidelines/ai-agent-usage.md - - content/guidelines/requirements-and-traceability.md - - content/guidelines/architecture-principles.md - - content/guidelines/decision-records.md - - content/guidelines/interfaces-and-co-design.md - - content/guidelines/components-reuse-and-variants.md - - content/guidelines/technology-and-third-party.md - - content/guidelines/coding-principles.md - - content/guidelines/coding-standard.md - - content/guidelines/version-control-and-versioning.md - - content/guidelines/pull-requests-and-review.md - - content/guidelines/pipelines-and-quality-gates.md - - content/guidelines/testing-principles-and-strategy.md - - content/guidelines/defects-and-technical-debt.md - - content/guidelines/logging-debug-and-diagnostics.md - - content/guidelines/observability-and-telemetry.md - - content/guidelines/release-update-and-production.md - - content/guidelines/security-and-data-protection.md - - content/guidelines/safety-regulatory-and-certification.md - - content/guidelines/planning-delivery-and-improvement.md - - content/guidelines/research-and-prototyping.md - - content/guidelines/competence-tooling-and-onboarding.md - - content/guidelines/principles-catalogue.md - - content/guidelines/business-principles.md - - content/guidelines/organisation-adoption.md - - content/guidelines/personal-projects.md - - content/guidelines/agent-rules.md - - content/guidelines/checklists.md + - {file: content/guidelines/using-the-guidelines.md, site_path: using-the-guidelines/index, page_break: true} + - {file: content/guidelines/core-rules.md, site_path: using-the-guidelines/core-rules, heading_offset: 1} + - {file: content/guidelines/organisation-adoption.md, site_path: using-the-guidelines/organisation-adoption, heading_offset: 1} + - {file: content/guidelines/personal-projects.md, site_path: using-the-guidelines/personal-projects, heading_offset: 1} + - {file: content/guidelines/principles-catalogue.md, site_path: using-the-guidelines/principles-catalogue, heading_offset: 1} + - {file: content/guidelines/business-principles.md, site_path: using-the-guidelines/business-principles, heading_offset: 1} + - {file: content/guidelines/agent-rules.md, site_path: using-the-guidelines/agent-rules, heading_offset: 1} + - {file: content/guidelines/checklists.md, site_path: using-the-guidelines/checklists, heading_offset: 1} + - {file: content/guidelines/part-foundations.md, site_path: foundations/index, page_break: true} + - {file: content/guidelines/guidelines-governance.md, site_path: foundations/guidelines-governance, heading_offset: 1} + - {file: content/guidelines/values-and-ways-of-working.md, site_path: foundations/values-and-ways-of-working, heading_offset: 1} + - {file: content/guidelines/quality-policy-and-attributes.md, site_path: foundations/quality-policy-and-attributes, heading_offset: 1} + - {file: content/guidelines/documentation-as-code.md, site_path: foundations/documentation-as-code, heading_offset: 1} + - {file: content/guidelines/ai-agent-usage.md, site_path: foundations/ai-agent-usage, heading_offset: 1} + - {file: content/guidelines/part-requirements-architecture-and-design.md, site_path: requirements-architecture-and-design/index, page_break: true} + - {file: content/guidelines/requirements-and-traceability.md, site_path: requirements-architecture-and-design/requirements-and-traceability, heading_offset: 1} + - {file: content/guidelines/architecture-principles.md, site_path: requirements-architecture-and-design/architecture-principles, heading_offset: 1} + - {file: content/guidelines/decision-records.md, site_path: requirements-architecture-and-design/decision-records, heading_offset: 1} + - {file: content/guidelines/interfaces-and-co-design.md, site_path: requirements-architecture-and-design/interfaces-and-co-design, heading_offset: 1} + - {file: content/guidelines/components-reuse-and-variants.md, site_path: requirements-architecture-and-design/components-reuse-and-variants, heading_offset: 1} + - {file: content/guidelines/technology-and-third-party.md, site_path: requirements-architecture-and-design/technology-and-third-party, heading_offset: 1} + - {file: content/guidelines/part-code-and-build.md, site_path: code-and-build/index, page_break: true} + - {file: content/guidelines/coding-principles.md, site_path: code-and-build/coding-principles, heading_offset: 1} + - {file: content/guidelines/coding-standard.md, site_path: code-and-build/coding-standard, heading_offset: 1} + - {file: content/guidelines/version-control-and-versioning.md, site_path: code-and-build/version-control-and-versioning, heading_offset: 1} + - {file: content/guidelines/pull-requests-and-review.md, site_path: code-and-build/pull-requests-and-review, heading_offset: 1} + - {file: content/guidelines/pipelines-and-quality-gates.md, site_path: code-and-build/pipelines-and-quality-gates, heading_offset: 1} + - {file: content/guidelines/part-verification.md, site_path: verification/index, page_break: true} + - {file: content/guidelines/testing-principles-and-strategy.md, site_path: verification/testing-principles-and-strategy, heading_offset: 1} + - {file: content/guidelines/defects-and-technical-debt.md, site_path: verification/defects-and-technical-debt, heading_offset: 1} + - {file: content/guidelines/part-diagnostics-and-field-insight.md, site_path: diagnostics-and-field-insight/index, page_break: true} + - {file: content/guidelines/logging-debug-and-diagnostics.md, site_path: diagnostics-and-field-insight/logging-debug-and-diagnostics, heading_offset: 1} + - {file: content/guidelines/observability-and-telemetry.md, site_path: diagnostics-and-field-insight/observability-and-telemetry, heading_offset: 1} + - {file: content/guidelines/part-release-risk-and-compliance.md, site_path: release-risk-and-compliance/index, page_break: true} + - {file: content/guidelines/release-update-and-production.md, site_path: release-risk-and-compliance/release-update-and-production, heading_offset: 1} + - {file: content/guidelines/security-and-data-protection.md, site_path: release-risk-and-compliance/security-and-data-protection, heading_offset: 1} + - {file: content/guidelines/safety-regulatory-and-certification.md, site_path: release-risk-and-compliance/safety-regulatory-and-certification, heading_offset: 1} + - {file: content/guidelines/part-delivery-research-and-people.md, site_path: delivery-research-and-people/index, page_break: true} + - {file: content/guidelines/planning-delivery-and-improvement.md, site_path: delivery-research-and-people/planning-delivery-and-improvement, heading_offset: 1} + - {file: content/guidelines/research-and-prototyping.md, site_path: delivery-research-and-people/research-and-prototyping, heading_offset: 1} + - {file: content/guidelines/competence-tooling-and-onboarding.md, site_path: delivery-research-and-people/competence-tooling-and-onboarding, heading_offset: 1} outputs: {docx: {}, pdf: {}} standards: - # Standards (from technical-documentation's specialised GU- documents): coding, design and interfaces, - # then connected devices. + # Standards: coding, design and interfaces, then connected devices, each a group with its own landing page. sources: - content/standards/index.md - - content/standards/c-coding-standard.md - - content/standards/misra-c.md - - content/standards/python.md - - content/standards/software-architecture-principles.md - - content/standards/api-design.md - - content/standards/unique-identifiers.md - - content/standards/lwm2m-objects.md - - content/standards/iot-device-architecture-principles.md - - content/standards/iot-battery-budgeting.md - - content/standards/constrained-binary-payloads.md - - content/standards/iot-edge-offline-storage.md - - content/standards/device-serialisation-and-factory-test.md + - {file: content/standards/group-coding.md, site_path: coding/index, page_break: true} + - {file: content/standards/c-coding-standard.md, site_path: coding/c-coding-standard, heading_offset: 1} + - {file: content/standards/misra-c.md, site_path: coding/misra-c, heading_offset: 1} + - {file: content/standards/python.md, site_path: coding/python, heading_offset: 1} + - {file: content/standards/group-design-and-interfaces.md, site_path: design-and-interfaces/index, page_break: true} + - {file: content/standards/software-architecture-principles.md, site_path: design-and-interfaces/software-architecture-principles, heading_offset: 1} + - {file: content/standards/api-design.md, site_path: design-and-interfaces/api-design, heading_offset: 1} + - {file: content/standards/unique-identifiers.md, site_path: design-and-interfaces/unique-identifiers, heading_offset: 1} + - {file: content/standards/lwm2m-objects.md, site_path: design-and-interfaces/lwm2m-objects, heading_offset: 1} + - {file: content/standards/group-connected-devices.md, site_path: connected-devices/index, page_break: true} + - {file: content/standards/iot-device-architecture-principles.md, site_path: connected-devices/iot-device-architecture-principles, heading_offset: 1} + - {file: content/standards/iot-battery-budgeting.md, site_path: connected-devices/iot-battery-budgeting, heading_offset: 1} + - {file: content/standards/constrained-binary-payloads.md, site_path: connected-devices/constrained-binary-payloads, heading_offset: 1} + - {file: content/standards/iot-edge-offline-storage.md, site_path: connected-devices/iot-edge-offline-storage, heading_offset: 1} + - {file: content/standards/device-serialisation-and-factory-test.md, site_path: connected-devices/device-serialisation-and-factory-test, heading_offset: 1} outputs: {docx: {}, pdf: {}} guides: - # Guides: each guide is a chapter, and a guide's numbered files are its sections (heading_offset 1). - # On the site each guide keeps its folder. + # Guides: architecture and design, connected devices, engineering practice, then the deep dives. A guide with + # chapters nests inside its group (its chapters at heading_offset 2). sources: - content/guides/index.md - - {file: content/guides/c4-model/index.md, page_break: true} - - {file: content/guides/c4-model/01-c4-model-foundations.md, heading_offset: 1} - - {file: content/guides/c4-model/02-diagrams-as-code-tooling.md, heading_offset: 1} - - {file: content/guides/c4-model/03-system-context.md, heading_offset: 1} - - {file: content/guides/c4-model/04-container-diagrams.md, heading_offset: 1} - - {file: content/guides/c4-model/05-component-diagrams.md, heading_offset: 1} - - {file: content/guides/c4-model/06-structurizr-dsl-reference.md, heading_offset: 1} - - {file: content/guides/c4-model/07-deployment-and-dynamics.md, heading_offset: 1} - - {file: content/guides/cybersecurity/index.md, page_break: true} - - {file: content/guides/cybersecurity/01-threat-modeling-foundations.md, heading_offset: 1} - - {file: content/guides/cybersecurity/02-hardware-and-silicon-security.md, heading_offset: 1} - - {file: content/guides/cybersecurity/03-transport-and-network-security.md, heading_offset: 1} - - {file: content/guides/cybersecurity/04-secure-firmware-updates-ota.md, heading_offset: 1} - - {file: content/guides/cybersecurity/05-standards-and-compliance.md, heading_offset: 1} - - {file: content/guides/iot-endpoint-and-gateway-architecture/index.md, page_break: true} - - {file: content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md, heading_offset: 1} - - {file: content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md, heading_offset: 1} - - {file: content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md, heading_offset: 1} - - {file: content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md, heading_offset: 1} - - {file: content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md, heading_offset: 1} - - {file: content/guides/iot-fleet-operations/index.md, page_break: true} - - {file: content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md, heading_offset: 1} - - {file: content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md, heading_offset: 1} - - {file: content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md, heading_offset: 1} - - {file: content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md, heading_offset: 1} - - {file: content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md, heading_offset: 1} - - {file: content/guides/hil-and-automated-testing/index.md, page_break: true} - - {file: content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md, heading_offset: 1} - - {file: content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md, heading_offset: 1} - - {file: content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md, heading_offset: 1} - - {file: content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md, heading_offset: 1} - - {file: content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md, heading_offset: 1} - - {file: content/guides/scaling-architecture/index.md, page_break: true} - - {file: content/guides/scaling-architecture/01-advice-process.md, heading_offset: 1} - - {file: content/guides/scaling-architecture/02-alignment-mechanisms.md, heading_offset: 1} - - {file: content/guides/git/index.md, page_break: true} - - {file: content/guides/git/01-how-git-works.md, heading_offset: 1} - - {file: content/guides/git/02-branching-strategies.md, heading_offset: 1} - - {file: content/guides/git/03-choosing-a-version-control-system.md, heading_offset: 1} - - {file: content/guides/ways-of-working/index.md, page_break: true} - - {file: content/guides/ways-of-working/01-working-agreements.md, heading_offset: 1} - - {file: content/guides/ways-of-working/02-onboarding.md, heading_offset: 1} - - {file: content/guides/ways-of-working/03-development-process.md, heading_offset: 1} - - {file: content/guides/ways-of-working/04-ci-cd.md, heading_offset: 1} - - {file: content/guides/ways-of-working/05-documentation-standards.md, heading_offset: 1} - - {file: content/guides/ways-of-working/06-architecture-and-design-documentation.md, heading_offset: 1} - - {file: content/guides/ways-of-working/07-documentation-and-modelling-tools.md, heading_offset: 1} - - {file: content/guides/ways-of-working/08-metrics-and-feedback.md, heading_offset: 1} - - {file: content/guides/decision-records.md, page_break: true} - - {file: content/guides/software-design-specification.md, page_break: true} - - {file: content/guides/high-level-design.md, page_break: true} - - {file: content/guides/architecture-review-board.md, page_break: true} - - {file: content/guides/agile-requirements-and-user-stories.md, page_break: true} - - {file: content/guides/code-review.md, page_break: true} - - {file: content/guides/defect-management-and-debugging.md, page_break: true} + - {file: content/guides/group-architecture-and-design.md, site_path: architecture-and-design/index, page_break: true} + - {file: content/guides/c4-model/index.md, site_path: architecture-and-design/c4-model/index, heading_offset: 1} + - {file: content/guides/c4-model/01-c4-model-foundations.md, site_path: architecture-and-design/c4-model/01-c4-model-foundations, heading_offset: 2} + - {file: content/guides/c4-model/02-diagrams-as-code-tooling.md, site_path: architecture-and-design/c4-model/02-diagrams-as-code-tooling, heading_offset: 2} + - {file: content/guides/c4-model/03-system-context.md, site_path: architecture-and-design/c4-model/03-system-context, heading_offset: 2} + - {file: content/guides/c4-model/04-container-diagrams.md, site_path: architecture-and-design/c4-model/04-container-diagrams, heading_offset: 2} + - {file: content/guides/c4-model/05-component-diagrams.md, site_path: architecture-and-design/c4-model/05-component-diagrams, heading_offset: 2} + - {file: content/guides/c4-model/06-structurizr-dsl-reference.md, site_path: architecture-and-design/c4-model/06-structurizr-dsl-reference, heading_offset: 2} + - {file: content/guides/c4-model/07-deployment-and-dynamics.md, site_path: architecture-and-design/c4-model/07-deployment-and-dynamics, heading_offset: 2} + - {file: content/guides/scaling-architecture/index.md, site_path: architecture-and-design/scaling-architecture/index, heading_offset: 1} + - {file: content/guides/scaling-architecture/01-advice-process.md, site_path: architecture-and-design/scaling-architecture/01-advice-process, heading_offset: 2} + - {file: content/guides/scaling-architecture/02-alignment-mechanisms.md, site_path: architecture-and-design/scaling-architecture/02-alignment-mechanisms, heading_offset: 2} + - {file: content/guides/decision-records.md, site_path: architecture-and-design/decision-records, heading_offset: 1} + - {file: content/guides/high-level-design.md, site_path: architecture-and-design/high-level-design, heading_offset: 1} + - {file: content/guides/software-design-specification.md, site_path: architecture-and-design/software-design-specification, heading_offset: 1} + - {file: content/guides/architecture-review-board.md, site_path: architecture-and-design/architecture-review-board, heading_offset: 1} + - {file: content/guides/group-connected-devices.md, site_path: connected-devices/index, page_break: true} + - {file: content/guides/iot-endpoint-and-gateway-architecture/index.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/index, heading_offset: 1} + - {file: content/guides/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/01-device-tiers-and-hardware-architecture, heading_offset: 2} + - {file: content/guides/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/02-connectivity-and-protocol-tradeoffs, heading_offset: 2} + - {file: content/guides/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/03-power-architecture-and-duty-cycling, heading_offset: 2} + - {file: content/guides/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/04-edge-storage-and-local-resilience, heading_offset: 2} + - {file: content/guides/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing.md, site_path: connected-devices/iot-endpoint-and-gateway-architecture/05-edge-intelligence-and-processing, heading_offset: 2} + - {file: content/guides/iot-fleet-operations/index.md, site_path: connected-devices/iot-fleet-operations/index, heading_offset: 1} + - {file: content/guides/iot-fleet-operations/01-zero-touch-device-onboarding.md, site_path: connected-devices/iot-fleet-operations/01-zero-touch-device-onboarding, heading_offset: 2} + - {file: content/guides/iot-fleet-operations/02-scalable-telemetry-ingestion.md, site_path: connected-devices/iot-fleet-operations/02-scalable-telemetry-ingestion, heading_offset: 2} + - {file: content/guides/iot-fleet-operations/03-digital-twins-and-state-reconciliation.md, site_path: connected-devices/iot-fleet-operations/03-digital-twins-and-state-reconciliation, heading_offset: 2} + - {file: content/guides/iot-fleet-operations/04-fleet-scale-ota-campaigns.md, site_path: connected-devices/iot-fleet-operations/04-fleet-scale-ota-campaigns, heading_offset: 2} + - {file: content/guides/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics.md, site_path: connected-devices/iot-fleet-operations/05-fleet-observability-and-remote-diagnostics, heading_offset: 2} + - {file: content/guides/cybersecurity/index.md, site_path: connected-devices/cybersecurity/index, heading_offset: 1} + - {file: content/guides/cybersecurity/01-threat-modeling-foundations.md, site_path: connected-devices/cybersecurity/01-threat-modeling-foundations, heading_offset: 2} + - {file: content/guides/cybersecurity/02-hardware-and-silicon-security.md, site_path: connected-devices/cybersecurity/02-hardware-and-silicon-security, heading_offset: 2} + - {file: content/guides/cybersecurity/03-transport-and-network-security.md, site_path: connected-devices/cybersecurity/03-transport-and-network-security, heading_offset: 2} + - {file: content/guides/cybersecurity/04-secure-firmware-updates-ota.md, site_path: connected-devices/cybersecurity/04-secure-firmware-updates-ota, heading_offset: 2} + - {file: content/guides/cybersecurity/05-standards-and-compliance.md, site_path: connected-devices/cybersecurity/05-standards-and-compliance, heading_offset: 2} + - {file: content/guides/hil-and-automated-testing/index.md, site_path: connected-devices/hil-and-automated-testing/index, heading_offset: 1} + - {file: content/guides/hil-and-automated-testing/01-the-iot-testing-pyramid.md, site_path: connected-devices/hil-and-automated-testing/01-the-iot-testing-pyramid, heading_offset: 2} + - {file: content/guides/hil-and-automated-testing/02-host-based-firmware-testing.md, site_path: connected-devices/hil-and-automated-testing/02-host-based-firmware-testing, heading_offset: 2} + - {file: content/guides/hil-and-automated-testing/03-qemu-virtual-hardware-simulation.md, site_path: connected-devices/hil-and-automated-testing/03-qemu-virtual-hardware-simulation, heading_offset: 2} + - {file: content/guides/hil-and-automated-testing/04-hil-bench-design-and-automation.md, site_path: connected-devices/hil-and-automated-testing/04-hil-bench-design-and-automation, heading_offset: 2} + - {file: content/guides/hil-and-automated-testing/05-network-simulation-and-chaos-testing.md, site_path: connected-devices/hil-and-automated-testing/05-network-simulation-and-chaos-testing, heading_offset: 2} + - {file: content/guides/group-engineering-practice.md, site_path: engineering-practice/index, page_break: true} + - {file: content/guides/git/index.md, site_path: engineering-practice/git/index, heading_offset: 1} + - {file: content/guides/git/01-how-git-works.md, site_path: engineering-practice/git/01-how-git-works, heading_offset: 2} + - {file: content/guides/git/02-branching-strategies.md, site_path: engineering-practice/git/02-branching-strategies, heading_offset: 2} + - {file: content/guides/git/03-choosing-a-version-control-system.md, site_path: engineering-practice/git/03-choosing-a-version-control-system, heading_offset: 2} + - {file: content/guides/code-review.md, site_path: engineering-practice/code-review, heading_offset: 1} + - {file: content/guides/agile-requirements-and-user-stories.md, site_path: engineering-practice/agile-requirements-and-user-stories, heading_offset: 1} + - {file: content/guides/defect-management-and-debugging.md, site_path: engineering-practice/defect-management-and-debugging, heading_offset: 1} + - {file: content/guides/ways-of-working/index.md, site_path: engineering-practice/ways-of-working/index, heading_offset: 1} + - {file: content/guides/ways-of-working/01-working-agreements.md, site_path: engineering-practice/ways-of-working/01-working-agreements, heading_offset: 2} + - {file: content/guides/ways-of-working/02-onboarding.md, site_path: engineering-practice/ways-of-working/02-onboarding, heading_offset: 2} + - {file: content/guides/ways-of-working/03-development-process.md, site_path: engineering-practice/ways-of-working/03-development-process, heading_offset: 2} + - {file: content/guides/ways-of-working/04-ci-cd.md, site_path: engineering-practice/ways-of-working/04-ci-cd, heading_offset: 2} + - {file: content/guides/ways-of-working/05-documentation-standards.md, site_path: engineering-practice/ways-of-working/05-documentation-standards, heading_offset: 2} + - {file: content/guides/ways-of-working/06-architecture-and-design-documentation.md, site_path: engineering-practice/ways-of-working/06-architecture-and-design-documentation, heading_offset: 2} + - {file: content/guides/ways-of-working/07-documentation-and-modelling-tools.md, site_path: engineering-practice/ways-of-working/07-documentation-and-modelling-tools, heading_offset: 2} + - {file: content/guides/ways-of-working/08-metrics-and-feedback.md, site_path: engineering-practice/ways-of-working/08-metrics-and-feedback, heading_offset: 2} - {file: content/guides/deep-dives/index.md, page_break: true} - {file: content/guides/deep-dives/cbor.md, heading_offset: 1} - {file: content/guides/deep-dives/coap.md, heading_offset: 1} @@ -161,80 +174,79 @@ documents: outputs: {docx: {}, pdf: {}} primers: - # Primers (the old Tech 101s): the overview, then one page per area, each followed by its - # primers. The primers sit one heading level below their area in the Word and PDF files. + # Primers (the old Tech 101s): the overview, then one group per area, led by the area's page. sources: - content/primers/index.md - - {file: content/primers/architecture.md, page_break: true} - - {file: content/primers/architecture-decision-records.md, heading_offset: 1} - - {file: content/primers/c4-model.md, heading_offset: 1} - - {file: content/primers/design-principles.md, heading_offset: 1} - - {file: content/primers/design-patterns.md, heading_offset: 1} - - {file: content/primers/anti-patterns.md, heading_offset: 1} - - {file: content/primers/hexagonal-architecture.md, heading_offset: 1} - - {file: content/primers/domain-driven-design.md, heading_offset: 1} - - {file: content/primers/event-driven-architecture.md, heading_offset: 1} - - {file: content/primers/modular-monolith-vs-microservices.md, heading_offset: 1} - - {file: content/primers/digital-twins-and-device-shadows.md, heading_offset: 1} - - {file: content/primers/distributed-systems.md, page_break: true} - - {file: content/primers/cap-and-pacelc.md, heading_offset: 1} - - {file: content/primers/consistency-models.md, heading_offset: 1} - - {file: content/primers/idempotency.md, heading_offset: 1} - - {file: content/primers/saga-pattern.md, heading_offset: 1} - - {file: content/primers/apis-and-data.md, page_break: true} - - {file: content/primers/rest-apis.md, heading_offset: 1} - - {file: content/primers/openapi-and-asyncapi.md, heading_offset: 1} - - {file: content/primers/data-formats.md, heading_offset: 1} - - {file: content/primers/cbor.md, heading_offset: 1} - - {file: content/primers/cloud.md, page_break: true} - - {file: content/primers/cicd-pipelines.md, heading_offset: 1} - - {file: content/primers/infrastructure-as-code.md, heading_offset: 1} - - {file: content/primers/serverless-computing.md, heading_offset: 1} - - {file: content/primers/kafka-event-streaming.md, heading_offset: 1} - - {file: content/primers/iot-on-google-cloud.md, heading_offset: 1} - - {file: content/primers/iot-and-embedded.md, page_break: true} - - {file: content/primers/embedded-systems-design.md, heading_offset: 1} - - {file: content/primers/rtos-and-freertos.md, heading_offset: 1} - - {file: content/primers/finite-state-machines.md, heading_offset: 1} - - {file: content/primers/interrupts-and-dma.md, heading_offset: 1} - - {file: content/primers/watchdog-timers.md, heading_offset: 1} - - {file: content/primers/bootloaders.md, heading_offset: 1} - - {file: content/primers/mqtt.md, heading_offset: 1} - - {file: content/primers/coap.md, heading_offset: 1} - - {file: content/primers/lwm2m.md, heading_offset: 1} - - {file: content/primers/cellular-lpwan.md, heading_offset: 1} - - {file: content/primers/firmware-over-the-air.md, heading_offset: 1} - - {file: content/primers/edge-computing-for-iot.md, heading_offset: 1} - - {file: content/primers/hardware-in-the-loop-testing.md, heading_offset: 1} - - {file: content/primers/security.md, page_break: true} - - {file: content/primers/cryptography-basics.md, heading_offset: 1} - - {file: content/primers/pki-and-certificates.md, heading_offset: 1} - - {file: content/primers/tls-and-dtls.md, heading_offset: 1} - - {file: content/primers/post-quantum-cryptography.md, heading_offset: 1} - - {file: content/primers/secure-coding-practices.md, heading_offset: 1} - - {file: content/primers/owasp-top-10.md, heading_offset: 1} - - {file: content/primers/oauth-and-oidc.md, heading_offset: 1} - - {file: content/primers/zero-trust-architecture.md, heading_offset: 1} - - {file: content/primers/etsi-en-303-645.md, heading_offset: 1} - - {file: content/primers/iso-30141.md, heading_offset: 1} - - {file: content/primers/methods-and-delivery.md, page_break: true} - - {file: content/primers/sdlc-models.md, heading_offset: 1} - - {file: content/primers/agile-development.md, heading_offset: 1} - - {file: content/primers/scrum-vs-kanban.md, heading_offset: 1} - - {file: content/primers/event-storming.md, heading_offset: 1} - - {file: content/primers/lightweight-architecture-evaluations.md, heading_offset: 1} - - {file: content/primers/testing-strategies.md, heading_offset: 1} - - {file: content/primers/code-review.md, heading_offset: 1} - - {file: content/primers/technical-debt.md, heading_offset: 1} - - {file: content/primers/docs-as-code.md, heading_offset: 1} - - {file: content/primers/root-cause-analysis.md, heading_offset: 1} - - {file: content/primers/programming-and-tools.md, page_break: true} - - {file: content/primers/git-best-practices.md, heading_offset: 1} - - {file: content/primers/static-code-analysis.md, heading_offset: 1} - - {file: content/primers/plantuml-and-mermaid.md, heading_offset: 1} - - {file: content/primers/python-for-automation.md, heading_offset: 1} - - {file: content/primers/rust-for-systems.md, heading_offset: 1} - - {file: content/primers/terminal-modernisation.md, heading_offset: 1} + - {file: content/primers/architecture.md, site_path: architecture/index, page_break: true} + - {file: content/primers/architecture-decision-records.md, site_path: architecture/architecture-decision-records, heading_offset: 1} + - {file: content/primers/c4-model.md, site_path: architecture/c4-model, heading_offset: 1} + - {file: content/primers/design-principles.md, site_path: architecture/design-principles, heading_offset: 1} + - {file: content/primers/design-patterns.md, site_path: architecture/design-patterns, heading_offset: 1} + - {file: content/primers/anti-patterns.md, site_path: architecture/anti-patterns, heading_offset: 1} + - {file: content/primers/hexagonal-architecture.md, site_path: architecture/hexagonal-architecture, heading_offset: 1} + - {file: content/primers/domain-driven-design.md, site_path: architecture/domain-driven-design, heading_offset: 1} + - {file: content/primers/event-driven-architecture.md, site_path: architecture/event-driven-architecture, heading_offset: 1} + - {file: content/primers/modular-monolith-vs-microservices.md, site_path: architecture/modular-monolith-vs-microservices, heading_offset: 1} + - {file: content/primers/digital-twins-and-device-shadows.md, site_path: architecture/digital-twins-and-device-shadows, heading_offset: 1} + - {file: content/primers/distributed-systems.md, site_path: distributed-systems/index, page_break: true} + - {file: content/primers/cap-and-pacelc.md, site_path: distributed-systems/cap-and-pacelc, heading_offset: 1} + - {file: content/primers/consistency-models.md, site_path: distributed-systems/consistency-models, heading_offset: 1} + - {file: content/primers/idempotency.md, site_path: distributed-systems/idempotency, heading_offset: 1} + - {file: content/primers/saga-pattern.md, site_path: distributed-systems/saga-pattern, heading_offset: 1} + - {file: content/primers/apis-and-data.md, site_path: apis-and-data/index, page_break: true} + - {file: content/primers/rest-apis.md, site_path: apis-and-data/rest-apis, heading_offset: 1} + - {file: content/primers/openapi-and-asyncapi.md, site_path: apis-and-data/openapi-and-asyncapi, heading_offset: 1} + - {file: content/primers/data-formats.md, site_path: apis-and-data/data-formats, heading_offset: 1} + - {file: content/primers/cbor.md, site_path: apis-and-data/cbor, heading_offset: 1} + - {file: content/primers/cloud.md, site_path: cloud/index, page_break: true} + - {file: content/primers/cicd-pipelines.md, site_path: cloud/cicd-pipelines, heading_offset: 1} + - {file: content/primers/infrastructure-as-code.md, site_path: cloud/infrastructure-as-code, heading_offset: 1} + - {file: content/primers/serverless-computing.md, site_path: cloud/serverless-computing, heading_offset: 1} + - {file: content/primers/kafka-event-streaming.md, site_path: cloud/kafka-event-streaming, heading_offset: 1} + - {file: content/primers/iot-on-google-cloud.md, site_path: cloud/iot-on-google-cloud, heading_offset: 1} + - {file: content/primers/iot-and-embedded.md, site_path: iot-and-embedded/index, page_break: true} + - {file: content/primers/embedded-systems-design.md, site_path: iot-and-embedded/embedded-systems-design, heading_offset: 1} + - {file: content/primers/rtos-and-freertos.md, site_path: iot-and-embedded/rtos-and-freertos, heading_offset: 1} + - {file: content/primers/finite-state-machines.md, site_path: iot-and-embedded/finite-state-machines, heading_offset: 1} + - {file: content/primers/interrupts-and-dma.md, site_path: iot-and-embedded/interrupts-and-dma, heading_offset: 1} + - {file: content/primers/watchdog-timers.md, site_path: iot-and-embedded/watchdog-timers, heading_offset: 1} + - {file: content/primers/bootloaders.md, site_path: iot-and-embedded/bootloaders, heading_offset: 1} + - {file: content/primers/mqtt.md, site_path: iot-and-embedded/mqtt, heading_offset: 1} + - {file: content/primers/coap.md, site_path: iot-and-embedded/coap, heading_offset: 1} + - {file: content/primers/lwm2m.md, site_path: iot-and-embedded/lwm2m, heading_offset: 1} + - {file: content/primers/cellular-lpwan.md, site_path: iot-and-embedded/cellular-lpwan, heading_offset: 1} + - {file: content/primers/firmware-over-the-air.md, site_path: iot-and-embedded/firmware-over-the-air, heading_offset: 1} + - {file: content/primers/edge-computing-for-iot.md, site_path: iot-and-embedded/edge-computing-for-iot, heading_offset: 1} + - {file: content/primers/hardware-in-the-loop-testing.md, site_path: iot-and-embedded/hardware-in-the-loop-testing, heading_offset: 1} + - {file: content/primers/security.md, site_path: security/index, page_break: true} + - {file: content/primers/cryptography-basics.md, site_path: security/cryptography-basics, heading_offset: 1} + - {file: content/primers/pki-and-certificates.md, site_path: security/pki-and-certificates, heading_offset: 1} + - {file: content/primers/tls-and-dtls.md, site_path: security/tls-and-dtls, heading_offset: 1} + - {file: content/primers/post-quantum-cryptography.md, site_path: security/post-quantum-cryptography, heading_offset: 1} + - {file: content/primers/secure-coding-practices.md, site_path: security/secure-coding-practices, heading_offset: 1} + - {file: content/primers/owasp-top-10.md, site_path: security/owasp-top-10, heading_offset: 1} + - {file: content/primers/oauth-and-oidc.md, site_path: security/oauth-and-oidc, heading_offset: 1} + - {file: content/primers/zero-trust-architecture.md, site_path: security/zero-trust-architecture, heading_offset: 1} + - {file: content/primers/etsi-en-303-645.md, site_path: security/etsi-en-303-645, heading_offset: 1} + - {file: content/primers/iso-30141.md, site_path: security/iso-30141, heading_offset: 1} + - {file: content/primers/methods-and-delivery.md, site_path: methods-and-delivery/index, page_break: true} + - {file: content/primers/sdlc-models.md, site_path: methods-and-delivery/sdlc-models, heading_offset: 1} + - {file: content/primers/agile-development.md, site_path: methods-and-delivery/agile-development, heading_offset: 1} + - {file: content/primers/scrum-vs-kanban.md, site_path: methods-and-delivery/scrum-vs-kanban, heading_offset: 1} + - {file: content/primers/event-storming.md, site_path: methods-and-delivery/event-storming, heading_offset: 1} + - {file: content/primers/lightweight-architecture-evaluations.md, site_path: methods-and-delivery/lightweight-architecture-evaluations, heading_offset: 1} + - {file: content/primers/testing-strategies.md, site_path: methods-and-delivery/testing-strategies, heading_offset: 1} + - {file: content/primers/code-review.md, site_path: methods-and-delivery/code-review, heading_offset: 1} + - {file: content/primers/technical-debt.md, site_path: methods-and-delivery/technical-debt, heading_offset: 1} + - {file: content/primers/docs-as-code.md, site_path: methods-and-delivery/docs-as-code, heading_offset: 1} + - {file: content/primers/root-cause-analysis.md, site_path: methods-and-delivery/root-cause-analysis, heading_offset: 1} + - {file: content/primers/programming-and-tools.md, site_path: programming-and-tools/index, page_break: true} + - {file: content/primers/git-best-practices.md, site_path: programming-and-tools/git-best-practices, heading_offset: 1} + - {file: content/primers/static-code-analysis.md, site_path: programming-and-tools/static-code-analysis, heading_offset: 1} + - {file: content/primers/plantuml-and-mermaid.md, site_path: programming-and-tools/plantuml-and-mermaid, heading_offset: 1} + - {file: content/primers/python-for-automation.md, site_path: programming-and-tools/python-for-automation, heading_offset: 1} + - {file: content/primers/rust-for-systems.md, site_path: programming-and-tools/rust-for-systems, heading_offset: 1} + - {file: content/primers/terminal-modernisation.md, site_path: programming-and-tools/terminal-modernisation, heading_offset: 1} outputs: {docx: {}, pdf: {}} reference: @@ -279,46 +291,50 @@ documents: outputs: {docx: {}, pdf: {}} templates: - # Templates & Checklists: the checklists first, then the templates. Files that tools read - # (YAML, the commit-msg hook, the canvases) are in content/templates/files/. + # Templates & Checklists: the checklists, then the templates by stage, each a group with its own landing page. + # Files that tools read are in content/templates/files/. sources: - content/templates/index.md - - content/templates/definition-of-ready.md - - content/templates/definition-of-done.md - - content/templates/architecture-review-checklist.md - - content/templates/design-review-checklist.md - - content/templates/code-review-checklist.md - - content/templates/debugging-checklist.md - - content/templates/defect-report-checklist.md - - content/templates/project-vision.md - - content/templates/architecture-vision.md - - content/templates/architecture-principles.md - - content/templates/architecture-document.md - - content/templates/architecture-canvases.md - - content/templates/crosscutting-concerns.md - - content/templates/adr.md - - content/templates/rfc.md - - content/templates/requirements.md - - content/templates/nfr-scenario.md - - content/templates/requirements-traceability-matrix.md - - content/templates/interface-specification.md - - content/templates/software-design-specification.md - - content/templates/experiment-record.md - - content/templates/test-plan.md - - content/templates/systems-engineering-management-plan.md - - content/templates/team-working-agreement.md - - content/templates/meeting-minutes.md - - content/templates/decision-log.md - - content/templates/risk-register.md - - content/templates/technical-debt-register.md - - content/templates/release-plan.md - - content/templates/sbom.md - - content/templates/pull-request-and-commits.md - - content/templates/postmortem.md - - content/templates/lessons-learned.md - - content/templates/agent-task-brief.md - - content/templates/agents-md.md - - content/templates/product-conformance-profile.md + - {file: content/templates/group-checklists.md, site_path: checklists/index, page_break: true} + - {file: content/templates/definition-of-ready.md, site_path: checklists/definition-of-ready, heading_offset: 1} + - {file: content/templates/definition-of-done.md, site_path: checklists/definition-of-done, heading_offset: 1} + - {file: content/templates/architecture-review-checklist.md, site_path: checklists/architecture-review-checklist, heading_offset: 1} + - {file: content/templates/design-review-checklist.md, site_path: checklists/design-review-checklist, heading_offset: 1} + - {file: content/templates/code-review-checklist.md, site_path: checklists/code-review-checklist, heading_offset: 1} + - {file: content/templates/debugging-checklist.md, site_path: checklists/debugging-checklist, heading_offset: 1} + - {file: content/templates/defect-report-checklist.md, site_path: checklists/defect-report-checklist, heading_offset: 1} + - {file: content/templates/group-vision-and-architecture.md, site_path: vision-and-architecture/index, page_break: true} + - {file: content/templates/project-vision.md, site_path: vision-and-architecture/project-vision, heading_offset: 1} + - {file: content/templates/architecture-vision.md, site_path: vision-and-architecture/architecture-vision, heading_offset: 1} + - {file: content/templates/architecture-principles.md, site_path: vision-and-architecture/architecture-principles, heading_offset: 1} + - {file: content/templates/architecture-document.md, site_path: vision-and-architecture/architecture-document, heading_offset: 1} + - {file: content/templates/architecture-canvases.md, site_path: vision-and-architecture/architecture-canvases, heading_offset: 1} + - {file: content/templates/crosscutting-concerns.md, site_path: vision-and-architecture/crosscutting-concerns, heading_offset: 1} + - {file: content/templates/adr.md, site_path: vision-and-architecture/adr, heading_offset: 1} + - {file: content/templates/rfc.md, site_path: vision-and-architecture/rfc, heading_offset: 1} + - {file: content/templates/group-requirements-design-and-testing.md, site_path: requirements-design-and-testing/index, page_break: true} + - {file: content/templates/requirements.md, site_path: requirements-design-and-testing/requirements, heading_offset: 1} + - {file: content/templates/nfr-scenario.md, site_path: requirements-design-and-testing/nfr-scenario, heading_offset: 1} + - {file: content/templates/requirements-traceability-matrix.md, site_path: requirements-design-and-testing/requirements-traceability-matrix, heading_offset: 1} + - {file: content/templates/interface-specification.md, site_path: requirements-design-and-testing/interface-specification, heading_offset: 1} + - {file: content/templates/software-design-specification.md, site_path: requirements-design-and-testing/software-design-specification, heading_offset: 1} + - {file: content/templates/experiment-record.md, site_path: requirements-design-and-testing/experiment-record, heading_offset: 1} + - {file: content/templates/test-plan.md, site_path: requirements-design-and-testing/test-plan, heading_offset: 1} + - {file: content/templates/group-delivery-and-operations.md, site_path: delivery-and-operations/index, page_break: true} + - {file: content/templates/systems-engineering-management-plan.md, site_path: delivery-and-operations/systems-engineering-management-plan, heading_offset: 1} + - {file: content/templates/team-working-agreement.md, site_path: delivery-and-operations/team-working-agreement, heading_offset: 1} + - {file: content/templates/meeting-minutes.md, site_path: delivery-and-operations/meeting-minutes, heading_offset: 1} + - {file: content/templates/decision-log.md, site_path: delivery-and-operations/decision-log, heading_offset: 1} + - {file: content/templates/risk-register.md, site_path: delivery-and-operations/risk-register, heading_offset: 1} + - {file: content/templates/technical-debt-register.md, site_path: delivery-and-operations/technical-debt-register, heading_offset: 1} + - {file: content/templates/release-plan.md, site_path: delivery-and-operations/release-plan, heading_offset: 1} + - {file: content/templates/sbom.md, site_path: delivery-and-operations/sbom, heading_offset: 1} + - {file: content/templates/pull-request-and-commits.md, site_path: delivery-and-operations/pull-request-and-commits, heading_offset: 1} + - {file: content/templates/postmortem.md, site_path: delivery-and-operations/postmortem, heading_offset: 1} + - {file: content/templates/lessons-learned.md, site_path: delivery-and-operations/lessons-learned, heading_offset: 1} + - {file: content/templates/agent-task-brief.md, site_path: delivery-and-operations/agent-task-brief, heading_offset: 1} + - {file: content/templates/agents-md.md, site_path: delivery-and-operations/agents-md, heading_offset: 1} + - {file: content/templates/product-conformance-profile.md, site_path: delivery-and-operations/product-conformance-profile, heading_offset: 1} outputs: {docx: {}, pdf: {}} radar: @@ -399,11 +415,14 @@ site: dir: site # Only the sections that have moved in are published. Add each section here when its pull request # merges; until then its placeholder page stays off both sites. - documents: [guidelines, standards, guides, handbook, primers, radar, glossary, templates, firmitas] + documents: [guidelines, standards, templates, firmitas, primers, guides, handbook, glossary, radar] downloads: [pdf, docx] targets: github: mkdocs.yml # https://markbac.github.io/, personal home page tarf: mkdocs.tarf.yml # https://tarf.co.uk/, the tarf home page - pages: # pages of our own, after the sections in the navigation - Tech Radar chart: radar-chart/index.md - Blog: blog/index.md + groups: # the top of the navigation: four headings over the sections + Ways of working: [guidelines, standards, templates, firmitas] + Learn: [primers, guides, handbook] + Reference: [glossary, radar] + pages: # pages of our own, after the sections in the navigation. The radar chart and + Blog: blog/index.md # the blog's All posts page are linked from their sections rather than listed here. diff --git a/site/docs/radar-chart/index.md b/site/docs/radar-chart/index.md index ad75947..baab23a 100644 --- a/site/docs/radar-chart/index.md +++ b/site/docs/radar-chart/index.md @@ -611,7 +611,7 @@ Welcome to our **Interactive Technology Radar**. This responsive living map visu