diff --git a/content/templates/adr.md b/content/templates/adr.md new file mode 100644 index 0000000..58f39d6 --- /dev/null +++ b/content/templates/adr.md @@ -0,0 +1,65 @@ +--- +title: Architecture decision record +--- + +# Architecture decision record + +An architecture decision record (ADR) captures one significant decision: the problem, the options, the choice and what follows from it. Write one when a decision is hard to reverse, affects more than one component, or will puzzle someone who joins the project later. Michael Nygard [described the idea](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) in 2011, and most ADR formats, this one included, descend from his. + +- Keep each record short, usually one page, and about one decision. +- Store records in the repository beside the code, for example in `docs/adr/`, numbered in order: `0007-use-cbor-for-telemetry.md`. +- Never edit an accepted record to change the decision. Write a new one that supersedes it, and link the two. +- When a decision needs wide discussion first, write a [request for comments](rfc.md), and record the outcome as an ADR. + +## Template + +```markdown +--- +id: ADR-0000 +title: Short imperative title, for example "Use CBOR for telemetry payloads" +status: proposed # proposed | accepted | rejected | deprecated | superseded +date: YYYY-MM-DD +deciders: [names or roles] +requirements: [REQ-...] +principles: [AP-...] +rfc: # RFC-0000, if one led to this decision +supersedes: # ADR-0000 +superseded-by: # ADR-0000 +--- + +# ADR-0000: Short imperative title + +## Context + +What is the problem, and why does it need a decision now? Describe the +forces at work: technical, commercial, regulatory and schedule. + +## Decision drivers + +- The things that matter most in choosing, for example power budget, + team skills or time to market. + +## Options considered + +1. **Option A.** Summary. Pros. Cons. +2. **Option B.** Summary. Pros. Cons. +3. **Do nothing.** What happens if we do not decide. + +## Decision + +We will do X, because Y. + +## Consequences + +- Good: what becomes easier. +- Bad: what becomes harder, and what we accept as a result. +- Follow-up: actions, other decisions or documents to update. + +## Verification + +How we will know the decision is working, and when we will check. + +## Related + +Links to requirements, other ADRs, RFCs and designs. +``` diff --git a/content/templates/agent-task-brief.md b/content/templates/agent-task-brief.md new file mode 100644 index 0000000..7bd9d7f --- /dev/null +++ b/content/templates/agent-task-brief.md @@ -0,0 +1,54 @@ +--- +title: Task brief for an AI agent +--- + +# Task brief for an AI agent + +An AI coding agent does better work with a short, specific brief than with a long conversation. The brief below gives it a goal, the boundaries, a definition of done and the points where it must stop and ask. It also says what to report, so a person can review the result quickly. + +Standing rules, such as build commands, folders it must not touch and coding conventions, belong in the repository's `AGENTS.md` (or the agent's own instruction file). The brief covers only this task. + +## Template + +```markdown +# Task: short title + +## Goal + +One or two sentences: the outcome wanted, and why. + +## Requirement and context + +- Requirement IDs: REQ-... +- Related ADRs: ADR-... +- Files or areas in scope: + +## Constraints + +- Do not touch (as well as the boundaries in AGENTS.md): +- Keep the change as small as it can be. Do not refactor beyond the task. +- Prefer the simple solution. State any assumption rather than guess. + +## Definition of done + +- Build, tests and lint pass locally, using the commands in AGENTS.md. +- Tests added or updated, and named after the requirement IDs. +- Documentation updated. +- Commits and pull request follow the conventions, with `Refs:` and + `Assisted-by:` trailers. + +## Ask first if + +- The change needs a new dependency, an interface change or an ADR. +- A requirement is missing, unclear or contradicts another. +- Anything touches a boundary listed in AGENTS.md. + +## Report back + +- What you did and why. +- Assumptions you made. +- Risks and anything left undone. +- Evidence: test and analysis output. +``` + +Review the agent's work as you would a colleague's: against the [code review checklist](code-review-checklist.md), with the same bar for tests and evidence. diff --git a/content/templates/architecture-canvases.md b/content/templates/architecture-canvases.md new file mode 100644 index 0000000..965d21b --- /dev/null +++ b/content/templates/architecture-canvases.md @@ -0,0 +1,27 @@ +--- +title: Architecture canvases +--- + +# Architecture canvases + +A canvas fits the essentials of an architecture on one page, to fill in together at a whiteboard or on a shared screen. It is not a replacement for the [architecture document](architecture-document.md). It is a quick way to start one, or to explain a system in a meeting. + +Both canvases here come from the [arc42 canvas project](https://canvas.arc42.org/). They are licensed under [Creative Commons Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/), and the files keep their authors' names and licence. If you change them and share the result, keep the attribution and the same licence. + +## Architecture Inception Canvas + +Use it at the start of a project, before there is much to document. The team fills it in together to agree what they are building, for whom, and what will shape the architecture. Its boxes cover the business case and context, a functional overview and the top three quality goals. Others hold the organisational and technical constraints, the known challenges and risks, and the architectural hypotheses that follow. Gaps that show up on the canvas are the questions to answer next. + +Downloads: [draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.drawio) · [PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.pptx) + +## Architecture Communication Canvas + +Use it to explain an existing system to someone new, such as a new team member, a stakeholder or a reviewer. On one page it gives the system's value, its key stakeholders, its core functions and its business context. It also shows the main components and technologies, the quality requirements, the decisions that shaped the system, and its risks and missing information. + +Downloads: [draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.drawio) · [PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.pptx) + +## Tips + +- Fill it in with the team, not alone. The conversation is worth more than the finished page. +- Use sticky notes or short phrases. If a box needs a paragraph, it needs a section in the architecture document. +- Date the canvas, and redo it when the architecture changes rather than patching the old one. diff --git a/content/templates/architecture-document.md b/content/templates/architecture-document.md new file mode 100644 index 0000000..1080bf7 --- /dev/null +++ b/content/templates/architecture-document.md @@ -0,0 +1,131 @@ +--- +title: Architecture document +--- + +# Architecture document + +An architecture document explains how a system is built and why. It is for the people who will build, test, operate and change the system, so it should answer their questions and stop. Start small: a context diagram, the quality goals and the main decisions are worth more than a hundred pages nobody reads. + +## Outline + +The outline below follows [arc42](https://arc42.org/), a free template for architecture documentation by Gernot Starke and Peter Hruschka. Its twelve sections are a checklist of what a reader might need. Leave out a section that has nothing to say, but keep the numbering, so readers always know where to look. The [arc42 documentation](https://docs.arc42.org/) explains each section, with examples. The official templates, in many formats and languages, are on the arc42 site. + +[[CAPTION:Table]] The twelve sections of an architecture document. + +| Section | What it answers | +|---------|-----------------| +| 1 Introduction and goals | What the system is for, its main features, the top three to five quality goals, and who the stakeholders are | +| 2 Constraints | What the team must work within: technical, organisational, regulatory and conventions | +| 3 Context and scope | What is inside the system and what is outside, and every external interface, both in business terms and in technical terms | +| 4 Solution strategy | The handful of fundamental decisions that shape everything else, and how they meet the quality goals | +| 5 Building block view | How the system is split into parts, level by level, and what each part is responsible for | +| 6 Runtime view | How the parts work together in the important scenarios, including start-up and failure | +| 7 Deployment view | Which hardware, networks and environments the parts run on | +| 8 Cross-cutting concepts | Rules that apply across many parts: security, logging, error handling, persistence, configuration | +| 9 Architecture decisions | The significant decisions, usually as links to [architecture decision records](adr.md) | +| 10 Quality requirements | The quality goals made measurable, as [quality scenarios](requirements.md#quality-scenario) | +| 11 Risks and technical debt | What could go wrong, and what we already know needs fixing | +| 12 Glossary | The domain and technical terms, so everyone uses the same words | + +Review the document with the [architecture review checklist](architecture-review-checklist.md). + +## C4 diagrams + +The [C4 model](https://c4model.com/), by Simon Brown, draws a system at four levels of zoom: system context, containers, components and code. Sections 3, 5 and 7 of the outline map onto its context, container and deployment diagrams. Most systems need only the first two levels. + +### C4 in PlantUML + +[C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) adds C4 shapes to PlantUML. Its standard library ships with PlantUML, so `!include ` needs no download. Copy this starter and replace the names. + +[[CAPTION:Figure]] +```plantuml caption="A system context diagram drawn with C4-PlantUML" +@startuml +!include +title System context: sensor platform + +Person(installer, "Installer", "Fits and commissions sensors") +System(platform, "Sensor platform", "Collects readings and manages devices") +System_Ext(network, "Mobile network", "NB-IoT and LTE-M") +System_Ext(erp, "Customer ERP", "Bills customers from readings") + +Rel(installer, platform, "Commissions devices with", "mobile app") +Rel(platform, network, "Sends readings over") +Rel(platform, erp, "Sends daily readings to", "HTTPS") +@enduml +``` + +[[CAPTION:Figure]] +```plantuml caption="A container diagram drawn with C4-PlantUML" +@startuml +!include +title Containers: sensor platform + +Person(installer, "Installer") +System_Boundary(platform, "Sensor platform") { + Container(device, "Sensor firmware", "C, Zephyr", "Measures and reports") + Container(ingest, "Ingest service", "Go", "Receives and decodes readings") + ContainerDb(store, "Time-series store", "PostgreSQL", "Holds readings") + Container(app, "Installer app", "Kotlin", "Commissions devices") +} +System_Ext(erp, "Customer ERP") + +Rel(device, ingest, "Sends readings", "CoAP, CBOR") +Rel(ingest, store, "Writes") +Rel(installer, app, "Uses") +Rel(app, ingest, "Registers devices", "HTTPS") +Rel(ingest, erp, "Sends daily readings", "HTTPS") +@enduml +``` + +The other levels use ``, `` and `` in the same way. + +### C4 in Structurizr + +For anything bigger than a few diagrams, keep one model and draw every view from it. Then a name changed in the model changes in every diagram. [Structurizr](https://structurizr.com/) does this with a model written in its own domain-specific language (DSL), and py-doc can turn a Structurizr workspace into chapters and pictures. This starter describes the same system as the diagrams above. Download [`c4-workspace.dsl`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/c4-workspace.dsl). + +[[CAPTION:Figure]] A starter Structurizr workspace. + +```text +workspace "Sensor platform" "Starter C4 model" { + + model { + installer = person "Installer" "Fits and commissions sensors." + erp = softwareSystem "Customer ERP" "Bills customers from readings." "External" + + platform = softwareSystem "Sensor platform" "Collects readings and manages devices." { + device = container "Sensor firmware" "Measures and reports." "C, Zephyr" + ingest = container "Ingest service" "Receives and decodes readings." "Go" + store = container "Time-series store" "Holds readings." "PostgreSQL" "Database" + app = container "Installer app" "Commissions devices." "Kotlin" + } + + installer -> app "Uses" + app -> ingest "Registers devices with" "HTTPS" + device -> ingest "Sends readings to" "CoAP, CBOR" + ingest -> store "Writes readings to" + ingest -> erp "Sends daily readings to" "HTTPS" + } + + views { + systemContext platform "Context" { + include * + autoLayout + } + container platform "Containers" { + include * + autoLayout + } + styles { + element "Person" { + shape Person + } + element "Database" { + shape Cylinder + } + element "External" { + background #999999 + } + } + } +} +``` diff --git a/content/templates/architecture-review-checklist.md b/content/templates/architecture-review-checklist.md new file mode 100644 index 0000000..4ba1900 --- /dev/null +++ b/content/templates/architecture-review-checklist.md @@ -0,0 +1,127 @@ +--- +title: Architecture review checklist +--- + +# Architecture review checklist + +Use this checklist to review a system architecture or high-level design before anyone builds it. A flaw found at this stage costs a meeting and a redraft. The same flaw found in the field can cost a recall. + +It applies to: + +- high-level designs and system architecture documents going to an architecture review board; +- major changes to an existing system or platform; +- spikes and proofs of concept, before the approach goes into a product; +- third-party platforms and components you are thinking of adopting. + +For the detailed design of a single component or firmware module, use the [design review checklist](design-review-checklist.md) instead. + +## How the review runs + +[[CAPTION:Figure]] +```mermaid caption="The architecture review process" +flowchart TD + A[Proposal submitted] --> B[Author self-assesses against the checklist] + B --> C{Every item answered?} + C -- No --> D[Author refines the design] + D --> B + C -- Yes --> E[Reviewers check the answers] + E --> F[Review meeting] + F --> G{Verdict} + G -- Pass --> H[Approved for implementation] + G -- Conditional pass --> I[Actions tracked to closure] + I --> H + G -- Fail --> D +``` + +1. **Self-assessment.** The author works through the checklist and, for each item, points to the part of the design that answers it. +2. **Expert review.** Reviewers with the right specialisms (security, embedded, cloud, test) check those answers on their own before the meeting. +3. **Review meeting.** The panel discusses the findings, agrees a verdict and assigns actions. + +## Rating each item + +[[CAPTION:Table]] Ratings for architecture review items. + +| Rating | Meaning | What happens next | +|--------|---------|-------------------| +| Satisfactory | The design answers the item fully, with evidence | Nothing. Record it in the minutes | +| Needs improvement | The design answers the item in part, or without enough justification | Conditional approval, with an action, an owner and a due date | +| Unsatisfactory | The design does not answer the item, contradicts itself or carries an unacceptable risk | Blocks approval. The author reworks the design and resubmits it | + +An architecture passes when no item is unsatisfactory and every item that needs improvement has an owner and a target date. + +## Checklist + +### 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. + +[[CAPTION:Figure]] Architecture review record. + +```text +ARCHITECTURE REVIEW RECORD ARB-REC-YYYY-NNN + +System or component: +Design document: +Lead architect: +Review chair: +Reviewers: , , +Review date: YYYY-MM-DD + +Findings + Items reviewed: 23 + Satisfactory: + Needs improvement: + Unsatisfactory: + +Verdict: PASS | CONDITIONAL PASS | FAIL (rework and resubmit) + +Actions (conditional pass) + 1. [ARC-nn] . Owner: . Due: YYYY-MM-DD. Ticket: + 2. [ARC-nn] . Owner: . Due: YYYY-MM-DD. Ticket: + +Sign-off + Lead architect: ____________________ Date: __________ + Review chair: ____________________ Date: __________ +``` + +## Further reading + +The structure of this checklist follows the architecture checklist in Steve McConnell's *Code Complete* (second edition, Microsoft Press, 2004), extended for embedded and connected systems. diff --git a/content/templates/code-review-checklist.md b/content/templates/code-review-checklist.md new file mode 100644 index 0000000..430bd6b --- /dev/null +++ b/content/templates/code-review-checklist.md @@ -0,0 +1,122 @@ +--- +title: Code review checklist +--- + +# Code review checklist + +Use this checklist when you review a pull request. It is a prompt, not a script: skip the sections that do not apply to the change, and spend the time on the ones that do. The sections on timing, memory and hardware are for embedded code. + +Let the tools do what tools do well. Formatting, warnings and most coding-standard rules belong in CI, so a reviewer can spend their attention on design, behaviour and risk. + +## 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 new file mode 100644 index 0000000..c2d464b --- /dev/null +++ b/content/templates/debugging-checklist.md @@ -0,0 +1,57 @@ +--- +title: Debugging checklist +--- + +# Debugging checklist + +Debugging by trial and error wastes time and often adds a second bug. Use this checklist to keep an investigation methodical: form a hypothesis, test it, and only then change the code. + +To report a defect, or to close one, use the [defect report checklist](defect-report-checklist.md). + +## 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 new file mode 100644 index 0000000..14884c7 --- /dev/null +++ b/content/templates/defect-report-checklist.md @@ -0,0 +1,112 @@ +--- +title: Defect report checklist +--- + +# Defect report checklist + +A good defect report lets someone who has never seen the problem reproduce it. A poor one starts a conversation that takes longer than the fix. Use this checklist when you raise a defect and again when you close it. + +## 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). + +## Template + +```markdown +### Summary + + +### Environment +- Device and revision: +- Firmware version and commit: +- Other components and versions: +- Configuration that differs from the default: + +### Preconditions +1. + +### Steps to reproduce +1. +2. + +### Expected result + + +### Actual result + + +### Evidence +- +``` + +## Example + +```markdown +### Summary +Modem does not reconnect after deep sleep when the signal is weak (-115 dBm). + +### Environment +- Device and revision: gateway, revision C +- Firmware version and commit: v2.4.1 (a3b7c89f) +- Other components and versions: modem firmware BG95M3LAR02A03, FreeRTOS 10.4.3 +- Configuration that differs from the default: none + +### Preconditions +1. Device provisioned with a working SIM on band 20. +2. RF attenuator set to give -115 dBm RSRP. + +### Steps to reproduce +1. Put the device to sleep from the CLI: `system sleep --duration 300`. +2. Wait 300 seconds for the RTC to wake it. +3. Watch the diagnostic UART while the modem powers up. + +### Expected result +The modem driver restarts, the modem registers within 45 seconds, and the +device reports that it is connected. + +### Actual result +The modem powers up, but its first AT command times out after 10 seconds. +The driver then retries forever and flattens the backup battery in about +four hours. Happens every time at -115 dBm, and never at -90 dBm. + +### Evidence +- console-reconnect-fail.log +- power-rail-ch1.png (oscilloscope) +- uart-at-timeout.sr (logic analyser) +``` + +## Severity and priority + +Severity and priority are separate. Severity is how much damage the defect does, and it rarely changes. Priority is how soon it must be fixed, which is a business decision and can change from week to week. A cosmetic fault on the launch demo can be urgent, and a crash in a feature nobody uses yet can wait. + +[[CAPTION:Table]] Severity levels. + +| Severity | Meaning | Examples | +|----------|---------|----------| +| S1 Critical | The system stops, data is lost or corrupted, or security is broken, with no workaround | Crash or boot loop, hard fault, exploitable vulnerability, service down | +| S2 Major | A core function does not work, or works only with a lot of manual effort | Telemetry stops, partial data loss | +| S3 Moderate | A secondary function fails, and a workaround exists | Wrong LED sequence, a report that does not generate | +| S4 Minor | Little or no effect on operation | Typing error in a log message, misaligned text in a web page | + +[[CAPTION:Table]] Priority levels. + +| Priority | Meaning | How it ships | +|----------|---------|--------------| +| P1 Immediate | Work starts now and continues until it is fixed | A hotfix release | +| P2 High | Fixed in the current sprint | The next planned release | +| P3 Medium | Planned into an upcoming sprint | A normal release | +| P4 Low | Fixed when someone is working in that code anyway | A future release | + +## 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 new file mode 100644 index 0000000..a041104 --- /dev/null +++ b/content/templates/definition-of-done.md @@ -0,0 +1,45 @@ +--- +title: Definition of Done +--- + +# Definition of Done + +A work item is done when it could be released without anyone doing anything more to it. This applies to stories, bug fixes, features and technical tasks alike. The list sets the minimum quality bar for the team. + +"Merged" is not the same as "done". Work that still needs testing, documentation or a release note is not finished. + +## 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 + +Add these when your product, domain or regulator needs them: + +- [ ] 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)). +- As a checklist on the ticket in your tracker. +- As a gate in the CI pipeline, for the items a machine can check. +- In sprint reviews and retrospectives, when the team discusses what slipped through. + +## Common problems + +- Treating "merged" as "done", so testing and documentation drift into the next sprint. +- Pushing unreviewed code to meet a deadline. +- Relying on manual testing where an automated test would do the job every time. + +Review the list every few months, or when a retrospective shows it missed something. Pair it with the [Definition of Ready](definition-of-ready.md). diff --git a/content/templates/definition-of-ready.md b/content/templates/definition-of-ready.md new file mode 100644 index 0000000..66602f8 --- /dev/null +++ b/content/templates/definition-of-ready.md @@ -0,0 +1,43 @@ +--- +title: Definition of Ready +--- + +# Definition of Ready + +A backlog item is ready when the team can start it on the first day of the sprint without going back to ask what it means. Use this list in backlog refinement. An item that fails any line stays in the backlog until it passes. + +The Definition of Ready is a gate, not a form to fill in. If the team keeps waving items through that fail it, change the list or change the refinement, but do not keep both. + +## Checklist + +- [ ] **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. + +[[CAPTION:Table]] The INVEST criteria. + +| ID | Letter | The story is ready when | +|----|--------|-------------------------| +| I-1 | Independent | It can be built, tested and delivered without waiting for other work in progress | +| I-2 | Negotiable | The detail is open to discussion between the team and the product owner, and it is not a fixed contract | +| I-3 | Valuable | It delivers something a customer, stakeholder or downstream system can see | +| I-4 | Estimable | The team understands the scope and approach well enough to size it | +| I-5 | Small | It fits comfortably in one sprint, typically two to four engineering days | +| I-6 | Testable | Its acceptance criteria give a clear pass or fail | + +## Common problems + +- Epics pulled into a sprint whole, instead of being split first. +- Acceptance criteria that cannot fail, such as "works well" or "is fast". +- Integrations and hardware constraints that nobody mentioned until the work started. +- Security and performance needs left out because they were not in the story text. + +Pair this list with the [Definition of Done](definition-of-done.md): one controls what goes into a sprint and the other controls what comes out. diff --git a/content/templates/design-review-checklist.md b/content/templates/design-review-checklist.md new file mode 100644 index 0000000..f67fc6d --- /dev/null +++ b/content/templates/design-review-checklist.md @@ -0,0 +1,89 @@ +--- +title: Design review checklist +--- + +# Design review checklist + +Use this checklist to review the detailed design of a software component or firmware module before it is coded. It checks that the design is sound, consistent with the architecture above it, and complete enough to build and test from. + +For a whole system or a high-level design, use the [architecture review checklist](architecture-review-checklist.md) instead. Keep the completed checklist with the design, and go through it again at each design review or stage gate. + +## Checklist + +### 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. diff --git a/content/templates/experiment-record.md b/content/templates/experiment-record.md new file mode 100644 index 0000000..c0b99b3 --- /dev/null +++ b/content/templates/experiment-record.md @@ -0,0 +1,59 @@ +--- +title: Experiment record +--- + +# Experiment record + +Use this template for a spike, a prototype or a piece of research. An experiment has a question, a time-box and an end. It finishes when you can answer the question or the time runs out, and either way the record says what you found. + +Record negative results too. "We tried it and it does not work, for these reasons" saves the next person the same two weeks. + +## Template + +```markdown +--- +id: EXP-0000 +title: Short title +status: running # running | stopped | extended | graduated +owner: +started: YYYY-MM-DD +time-box: YYYY-MM-DD # the date it stops unless someone extends it +maturity: R0 # R0 idea | R1 feasible | R2 prototype | R3 ready for a product +--- + +# EXP-0000: Short title + +## Question + +What do we want to find out, and what decision depends on the answer? + +## Time-box + +The end date and the effort limit. + +## Method + +How we will answer the question, and what result would count as +success or failure. Decide this before you start. + +## Setup + +Hardware, software versions, configuration and where the data is kept. + +## Results + +What happened, with the data. Include the negative and the unexpected. + +## Conclusion + +The answer to the question, and how confident we are in it. + +## Decision and next step + +Stop, extend (and why), or graduate into a product. If it graduates, +link the requirement, ADR or RFC that follows. + +## Reproduction + +The commands and scripts that repeat the experiment. +``` diff --git a/content/templates/files/NOTICE b/content/templates/files/NOTICE new file mode 100644 index 0000000..46cc107 --- /dev/null +++ b/content/templates/files/NOTICE @@ -0,0 +1,15 @@ +Licences of the files in this folder + +architecture-communication-canvas.drawio +architecture-communication-canvas.pptx +architecture-inception-canvas.drawio +architecture-inception-canvas.pptx + Software Architecture Canvas, (c) 2023 Gernot Starke, Patrick Roos, + Ben Wolf and arc42 contributors, https://canvas.arc42.org/ + Licensed under Creative Commons Attribution-ShareAlike 4.0 International, + https://creativecommons.org/licenses/by-sa/4.0/ + Copied unchanged, except that a stray test label was removed from the + communication canvas. + +All other files + (c) Mark Bacon, under the MIT licence in the repository's LICENSE file. diff --git a/content/templates/files/architecture-communication-canvas.drawio b/content/templates/files/architecture-communication-canvas.drawio new file mode 100644 index 0000000..aa7f63e --- /dev/null +++ b/content/templates/files/architecture-communication-canvas.drawio @@ -0,0 +1,257 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/templates/files/architecture-communication-canvas.pptx b/content/templates/files/architecture-communication-canvas.pptx new file mode 100644 index 0000000..bc11021 Binary files /dev/null and b/content/templates/files/architecture-communication-canvas.pptx differ diff --git a/content/templates/files/architecture-inception-canvas.drawio b/content/templates/files/architecture-inception-canvas.drawio new file mode 100644 index 0000000..10dc328 --- /dev/null +++ b/content/templates/files/architecture-inception-canvas.drawio @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/templates/files/architecture-inception-canvas.pptx b/content/templates/files/architecture-inception-canvas.pptx new file mode 100644 index 0000000..990e26d Binary files /dev/null and b/content/templates/files/architecture-inception-canvas.pptx differ diff --git a/content/templates/files/c4-workspace.dsl b/content/templates/files/c4-workspace.dsl new file mode 100644 index 0000000..99b8650 --- /dev/null +++ b/content/templates/files/c4-workspace.dsl @@ -0,0 +1,42 @@ +workspace "Sensor platform" "Starter C4 model" { + + model { + installer = person "Installer" "Fits and commissions sensors." + erp = softwareSystem "Customer ERP" "Bills customers from readings." "External" + + platform = softwareSystem "Sensor platform" "Collects readings and manages devices." { + device = container "Sensor firmware" "Measures and reports." "C, Zephyr" + ingest = container "Ingest service" "Receives and decodes readings." "Go" + store = container "Time-series store" "Holds readings." "PostgreSQL" "Database" + app = container "Installer app" "Commissions devices." "Kotlin" + } + + installer -> app "Uses" + app -> ingest "Registers devices with" "HTTPS" + device -> ingest "Sends readings to" "CoAP, CBOR" + ingest -> store "Writes readings to" + ingest -> erp "Sends daily readings to" "HTTPS" + } + + views { + systemContext platform "Context" { + include * + autoLayout + } + container platform "Containers" { + include * + autoLayout + } + styles { + element "Person" { + shape Person + } + element "Database" { + shape Cylinder + } + element "External" { + background #999999 + } + } + } +} diff --git a/content/templates/files/commit-msg b/content/templates/files/commit-msg new file mode 100755 index 0000000..ffd0695 --- /dev/null +++ b/content/templates/files/commit-msg @@ -0,0 +1,41 @@ +#!/bin/sh +# commit-msg hook: checks that the first line of a commit message follows +# Conventional Commits (https://www.conventionalcommits.org/en/v1.0.0/). +# +# [(scope)][!]: +# +# Install it for one repository: +# mkdir -p .githooks && cp commit-msg .githooks/ && chmod +x .githooks/commit-msg +# git config core.hooksPath .githooks +# +# Set COMMIT_TYPES to change the allowed types, and REQUIRE_REFS=1 to insist +# on a "Refs:" trailer naming a ticket or requirement. + +types="${COMMIT_TYPES:-build chore ci docs feat fix perf refactor revert style test}" +msg_file="$1" +subject=$(sed -n '/^[^#]/{p;q;}' "$msg_file") + +# Git's own messages pass: merges, reverts, and fixup or squash commits. +case "$subject" in + "Merge "* | "Revert \""* | "fixup! "* | "squash! "* | "amend! "*) exit 0 ;; +esac + +alternatives=$(echo "$types" | tr ' ' '|') +pattern="^($alternatives)(\([a-z0-9._/-]+\))?!?: [^ ].*" + +fail() { + echo "commit-msg: $1" >&2 + echo " got: $subject" >&2 + echo " expected: [(scope)][!]: " >&2 + echo " types: $types" >&2 + echo " example: fix(modem): retry the AT handshake after wake-up" >&2 + exit 1 +} + +echo "$subject" | grep -Eq "$pattern" || fail "the first line is not a Conventional Commits header" +[ "${#subject}" -le 72 ] || fail "the first line is longer than 72 characters" + +if [ "${REQUIRE_REFS:-0}" = "1" ] && ! grep -Eq '^Refs: .+' "$msg_file"; then + fail "add a 'Refs:' trailer naming the ticket or requirement" +fi +exit 0 diff --git a/content/templates/files/component-register.yaml b/content/templates/files/component-register.yaml new file mode 100644 index 0000000..3a0c60c --- /dev/null +++ b/content/templates/files/component-register.yaml @@ -0,0 +1,14 @@ +# The components a product is built from, and who looks after each one. +# Keep it in the product repository, for example as docs/components.yaml. +components: + - name: component-name + owner: "Name or role" + deputy: "Name or role" # ideally at another site + repository: "git@example.com:group/component.git" + version: 0.0.0 + status: active # active | maintenance | deprecated | retired + consumers: [product-a] # products that use it + interfaces: [IF-0000] # interface specifications it provides + variation-points: [] # where products may configure or extend it + third-party: false # true for bought-in or open-source components + licence: # SPDX identifier, for third-party components diff --git a/content/templates/files/requirement.yaml b/content/templates/files/requirement.yaml new file mode 100644 index 0000000..75cddd7 --- /dev/null +++ b/content/templates/files/requirement.yaml @@ -0,0 +1,11 @@ +# One requirement. Keep one file per requirement, or a list of these per component. +id: REQ-XX-0000 # stable, never reused +title: Short title +statement: The system shall ... +type: functional # functional | performance | security | safety | interface | constraint +level: firmware # system | subsystem | software | firmware | hardware +parent: REQ-SYS-0000 # the requirement this one refines +verification: test # test | analysis | inspection | demonstration +status: draft # draft | approved | implemented | verified | retired +owner: +rationale: Why this requirement exists. diff --git a/content/templates/index.md b/content/templates/index.md index 9f9349d..e355674 100644 --- a/content/templates/index.md +++ b/content/templates/index.md @@ -1,10 +1,64 @@ --- title: Templates & Checklists author: Mark Bacon +description: Checklists for reviews and quality gates, and templates for engineering records, for embedded and connected-product teams. --- # Templates & Checklists -Checklists and templates: design, code review, definition of done and ready, defects, ADRs and RFCs. +Checklists for the reviews and quality gates in a software or firmware project, and templates for the records a team keeps along the way. They are written for embedded and connected products, but most of them work for any software team. -This section is moving in from site-web-content-src's Templates, EngineeringProcess's templates and technical-documentation's checklists. +Copy them into your own repository, tracker or wiki and change them to suit. A checklist nobody adapts tends to become a checklist nobody reads. + +## Checklists + +Each checklist is a task list, so it can go straight into a pull request, an issue or a review record. Every item has an ID, so review comments and records can refer to it. + +[[CAPTION:Table]] The checklists. + +| Checklist | Use it when | +|-----------|-------------| +| [Definition of Ready](definition-of-ready.md) | Deciding whether a backlog item can go into a sprint | +| [Definition of Done](definition-of-done.md) | Deciding whether a work item is finished | +| [Architecture review](architecture-review-checklist.md) | Reviewing a system architecture or high-level design | +| [Design review](design-review-checklist.md) | Reviewing the detailed design of a component or module | +| [Code review](code-review-checklist.md) | Reviewing a pull request | +| [Debugging](debugging-checklist.md) | Investigating and fixing a fault | +| [Defect report](defect-report-checklist.md) | Raising a defect, setting its severity, and closing it | + +## Templates + +[[CAPTION:Table]] The templates. + +| Template | Use it for | +|----------|------------| +| [Architecture decision record](adr.md) | Recording one significant decision | +| [Request for comments](rfc.md) | Proposing a change and gathering views before deciding | +| [Requirements and quality scenarios](requirements.md) | Writing requirements that can be traced and tested | +| [Interface specification](interface-specification.md) | Describing an interface between components or systems | +| [Architecture document](architecture-document.md) | Describing a system's architecture, with C4 diagram starters | +| [Architecture canvases](architecture-canvases.md) | Starting or explaining an architecture on one page | +| [Experiment record](experiment-record.md) | Running a spike, prototype or piece of research | +| [Postmortem](postmortem.md) | Learning from an incident or a defect found in the field | +| [Pull requests and commits](pull-request-and-commits.md) | Pull request descriptions, commit messages and a commit message hook | +| [Task brief for an AI agent](agent-task-brief.md) | Handing a coding task to an AI agent | +| [Conformance profile and component register](product-conformance-profile.md) | Tailoring guidelines to a product, and listing its components | + +## Files to download + +The templates that tools read are also available as files. + +[[CAPTION:Table]] Template files. + +| File | What it is | +|------|------------| +| [`requirement.yaml`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/requirement.yaml) | A requirement record | +| [`component-register.yaml`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/component-register.yaml) | A component register | +| [`c4-workspace.dsl`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/c4-workspace.dsl) | A starter Structurizr workspace | +| [`commit-msg`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/commit-msg) | A Git hook that checks commit messages | +| [Architecture Inception Canvas, draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.drawio) | The inception canvas, to edit in draw.io | +| [Architecture Inception Canvas, PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.pptx) | The inception canvas, as slides | +| [Architecture Communication Canvas, draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.drawio) | The communication canvas, to edit in draw.io | +| [Architecture Communication Canvas, PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.pptx) | The communication canvas, as slides | + +The canvases are by Gernot Starke, Patrick Roos, Ben Wolf and the arc42 contributors, under a Creative Commons Attribution-ShareAlike licence (see [Architecture canvases](architecture-canvases.md)). Everything else in this section is under the site's MIT licence. diff --git a/content/templates/interface-specification.md b/content/templates/interface-specification.md new file mode 100644 index 0000000..555b734 --- /dev/null +++ b/content/templates/interface-specification.md @@ -0,0 +1,95 @@ +--- +title: Interface specification +--- + +# Interface specification + +Use this template to describe an interface between components, products or external systems: a web API, a message stream, a remote procedure call, inter-process communication or a hardware bus. The machine-readable specification, such as an OpenAPI or AsyncAPI file, is the contract. This page wraps it with what the specification file cannot say: who owns it, the quality of service, errors, versioning and security. + +## Choose the specification format + +[[CAPTION:Table]] Specification formats by interface style. + +| Style | Specification | Where it usually lives | +|-------|---------------|------------------------| +| HTTP web API | OpenAPI 3.1 | `api/openapi.yaml` | +| Events and messaging (MQTT, Kafka, AMQP, WebSocket) | AsyncAPI 3 | `api/asyncapi.yaml` | +| Remote procedure call and streaming | gRPC with Protocol Buffers | `api/proto/*.proto` | +| Client-driven queries | GraphQL schema | `api/schema.graphql` | +| Inter-process communication, operating system or embedded | D-Bus XML, C headers, register maps | `api/idl/`, `include/` | +| Constrained device management | LwM2M object definitions | `api/lwm2m/*.xml` | + +Generate code, mocks and contract tests from the specification file where you can, so it cannot drift from the implementation. + +## Template + +```markdown +--- +id: IF-0000 +name: Interface name +owner: Team or role +version: 1.0.0 +status: proposed # proposed | active | deprecated | retired +style: openapi # openapi | asyncapi | grpc | graphql | ipc | hardware | custom +providers: [component] +consumers: [component, product] +last-reviewed: YYYY-MM-DD +--- + +# IF-0000: Interface name + +## 1. Purpose and scope + +What the interface does, what it deliberately does not do, who +provides it and who uses it. + +## 2. Specification + +Link to the specification file, for example `api/openapi.yaml`, and +summarise the main operations, topics or messages. For a hardware or +binary interface, give the transport, the message layout, packing, +byte order and alignment. + +## 3. Data and encoding + +Serialisation (JSON, CBOR, Protocol Buffers, raw binary), character +set (UTF-8), byte order, units and time format (UTC, ISO 8601). + +## 4. Timing and quality of service + +- Latency: for example 99th percentile under 50 ms. +- Throughput and rate limits: for example 100 requests per second per client. +- Delivery guarantee for messages: at most once, at least once or exactly once. +- Ordering and duplicate handling. + +## 5. Errors and recovery + +- Error codes and the error format (for HTTP, RFC 9457 problem details). +- Retry policy: which errors to retry, back-off and jitter. +- What consumers do when the provider is unreachable. + +## 6. Versioning and compatibility + +- Semantic versioning: a field removed or retyped is a major change. +- How the version is carried: path, header, topic or field. +- Deprecation notice period, for example six months. + +## 7. Security + +- Authentication: how callers prove who they are (mTLS, tokens, keys). +- Authorisation: roles or scopes per operation. +- Encryption in transit and, for sensitive data, at rest. +- Personal data carried, and why. + +## 8. Verification + +- Contract tests and where they run. +- Mock servers or simulators generated from the specification. +- The CI check that blocks incompatible changes. + +## 9. Change history + +| Version | Date | Change | +|---------|------|--------| +| 1.0.0 | YYYY-MM-DD | First version | +``` diff --git a/content/templates/postmortem.md b/content/templates/postmortem.md new file mode 100644 index 0000000..d6a977d --- /dev/null +++ b/content/templates/postmortem.md @@ -0,0 +1,108 @@ +--- +title: Postmortem +--- + +# Postmortem + +Write a postmortem after any incident that hurt customers, and after every critical (S1) or major (S2) defect found in the field. Publish it within five working days of the fix, while people still remember the details. + +A postmortem is blameless. It asks how the system and the process let the problem happen, not who made the mistake. People make mistakes all the time, and a good process catches them. If the answer is "someone should have been more careful", keep asking. + +## Finding the root cause + +Two simple techniques help get past the first, technical answer. + +**Five whys.** Ask why the failure happened, then why that happened, and keep going until you reach something the team can change in its process or design. + +[[CAPTION:Figure]] +```mermaid caption="A five-whys chain for a connectivity incident" +flowchart TD + A[Gateways lost their cloud connection] -->|Why?| B[The cellular connection timed out] + B -->|Why?| C[DNS lookups failed] + C -->|Why?| D[The network operator changed its DNS servers] + D -->|Why?| E[The gateway used fixed DNS addresses instead of the network's] + E -->|Why?| F[No test covers network settings that change] +``` + +**Fishbone diagram.** When there are several causes, group them by area, such as environment, code, process and tools, and look for the ones that combined. + +[[CAPTION:Figure]] +```mermaid caption="A fishbone diagram grouping the causes of a crash" +flowchart LR + subgraph Environment + E1[Weak signal] + E2[High temperature] + end + subgraph Code + C1[Unbounded buffer] + C2[Missing null check] + end + subgraph Process + P1[Review skipped] + P2[Soak test too short] + end + subgraph Tools + T1[Mocks with no latency] + T2[CI time-out] + end + Environment --> F[Crash in the field] + Code --> F + Process --> F + Tools --> F +``` + +## Template + +```markdown +# Postmortem: INC-0000, short title + +## Summary + +- Date: +- Duration: from first impact to full recovery +- Severity: S1 | S2 +- Affected: products, firmware versions, services, customers +- Lead investigator: + +Two or three sentences on what happened and what fixed it. + +## Impact + +Who was affected and how: devices offline, data lost, customers +contacted, money spent. + +## Timeline (UTC) + +- 14:02 Over-the-air update v2.4.1 starts on the first 500 devices. +- 14:15 Alert: disconnection rate above 20 %. +- 14:22 On-call engineer stops the roll-out. +- ... +- 17:15 Fixed version v2.4.2 reaches the affected devices, and they reconnect. + +## Root cause + +What failed, and why the system and process allowed it. + +## Contributing factors + +Everything else that made it happen or made it worse. Focus on +systems and processes, not people. + +## What went well + +- Things to keep doing, for example: the staged roll-out contained + the fault to 1 % of the fleet. + +## What went badly + +- Things to change, for example: soak tests ran only with a strong signal. + +## Actions + +| ID | Action | Owner | Due | Ticket | +|----|--------|-------|-----|--------| +| A1 | Add a weak-signal sweep to the hardware-in-the-loop tests | | YYYY-MM-DD | | +| A2 | Add a time-out and a retry limit to the modem driver | | YYYY-MM-DD | | +``` + +Every action has an owner and a date, and the team reviews them until they are closed. A postmortem whose actions never close was just a story. diff --git a/content/templates/product-conformance-profile.md b/content/templates/product-conformance-profile.md new file mode 100644 index 0000000..c606a6d --- /dev/null +++ b/content/templates/product-conformance-profile.md @@ -0,0 +1,88 @@ +--- +title: Product conformance profile and component register +--- + +# Product conformance profile and component register + +Engineering guidelines are written for every product, but no two products need exactly the same rules. A small sensor and a safety controller should not carry the same paperwork. The conformance profile records, for one product, which guidelines apply, which values it changes, and which exceptions it holds. The component register lists what the product is built from and who owns each part. + +Keep both in the product's repository and review them at each release. + +## Conformance profile + +Core rules apply to every product and cannot be tailored, so they never appear in the tailoring table. Every other change to a default needs a reason and an approver. Every exception needs an expiry date. + +```markdown +--- +product: Product name +technical-lead: +version: 0.1.0 +last-reviewed: YYYY-MM-DD +review-by: YYYY-MM-DD +--- + +# Conformance profile: product name + +## Scope + +What the product is, its target hardware, and its main risks: safety, +security and regulatory. + +## Guideline applicability + +| Guideline | Applies | Notes | +|-----------|---------|-------| +| EG-001 | Yes | | +| EG-023 | No | No certification needed. Revisit if the market changes | + +## Tailored rules and values + +| Rule | Default | This product | Reason | Approved by | +|------|---------|--------------|--------|-------------| +| PRR-09 | One working day | | | | + +## Exceptions + +| Rule | Scope | Reason | Approved by | Expires | +|------|-------|--------|-------------|---------| + +## Toolchain + +- Compiler and version: +- Build system: +- Static analysis: +- Test frameworks and rigs: + +## Components + +Link to the component register (`docs/components.yaml`), and list the +components this product provides to others. + +## Quality attribute profile + +The top three quality attributes, and any change to their order of +precedence, with the ADR that records it. +``` + +## Component register + +A list of the product's components, kept as YAML so tools can check it. Each entry names an owner and a deputy, preferably at another site, and lists the interfaces it provides and the products that use it. Download [`component-register.yaml`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/component-register.yaml). + +[[CAPTION:Figure]] Component register. + +```yaml +components: + - name: component-name + owner: "Name or role" + deputy: "Name or role" # ideally at another site + repository: "git@example.com:group/component.git" + version: 0.0.0 + status: active # active | maintenance | deprecated | retired + consumers: [product-a] # products that use it + interfaces: [IF-0000] # interface specifications it provides + variation-points: [] # where products may configure or extend it + third-party: false # true for bought-in or open-source components + licence: # SPDX identifier, for third-party components +``` + +The register is also the starting point for the software bill of materials: every component marked `third-party` needs its licence and version recorded. diff --git a/content/templates/pull-request-and-commits.md b/content/templates/pull-request-and-commits.md new file mode 100644 index 0000000..ca3a7c0 --- /dev/null +++ b/content/templates/pull-request-and-commits.md @@ -0,0 +1,104 @@ +--- +title: Pull requests and commits +--- + +# Pull requests and commits + +A pull request and its commits are the record of why the code is the way it is. Someone reading `git log` or `git blame` in three years' time should be able to find out what changed, why, and what evidence showed that it worked. + +## Pull request template + +Save this as `.github/pull_request_template.md` (GitHub) or `.gitlab/merge_request_templates/Default.md` (GitLab), so every new pull request starts from it. + +[[CAPTION:Figure]] Pull request template. + +```markdown +## What and why + +What this change does, and the problem it solves. + +## Links + +- Requirement: +- Ticket: +- ADR or RFC: + +## Evidence + +- Tests run and their results: +- Effect on size, timing, memory or power: + +## Risk and rollback + +What could go wrong, and how to undo the change. + +## Checklist + +- [ ] Commits and test names reference the requirement IDs +- [ ] Documentation updated +- [ ] Breaking change flagged in the title and the commit (`!`) +- [ ] AI assistance disclosed with an `Assisted-by:` trailer +- [ ] Safety-related, certified or regulated code touched (say which) +``` + +The [Definition of Done](definition-of-done.md) and the [code review checklist](code-review-checklist.md) say what the reviewer will look for. + +## Commit messages + +Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). The type at the start of the first line tells readers and release tools what kind of change it is. A changelog and the next version number can then come straight from the history. + +```text +[(scope)][!]: + +[body: what changed and why, wrapped at 72 characters] + +[trailers] +``` + +[[CAPTION:Table]] Conventional Commits types. + +| Type | Use it for | +|------|------------| +| `feat` | A new feature (a minor version) | +| `fix` | A bug fix (a patch version) | +| `perf` | A change that makes the code faster or smaller | +| `refactor` | A change that neither fixes a bug nor adds a feature | +| `test` | Adding or correcting tests | +| `docs` | Documentation only | +| `build` | The build system or dependencies | +| `ci` | The CI configuration | +| `style` | Formatting, with no change in meaning | +| `chore` | Anything else that does not touch the product code | +| `revert` | Reverting an earlier commit | + +An exclamation mark before the colon, or a `BREAKING CHANGE:` trailer, marks a change that breaks compatibility (a major version). + +```text +feat(telemetry): send readings as CBOR + +JSON payloads were 3.1 times larger and cost too much airtime on NB-IoT. +CBOR keeps the same structure, so the cloud decoder changes but the data +model does not. + +Refs: REQ-GW-0042, ADR-0007 +Assisted-by: Claude +``` + +- Write the description in the imperative ("add", not "added"), in lower case, with no full stop, and keep the first line to 72 characters or fewer. +- Use the body to explain why. The diff already shows what. +- Put references in trailers: `Refs:` for tickets and requirements, `Assisted-by:` for AI tools, `Co-authored-by:` for people. + +## Commit message hook + +This Git hook rejects a commit whose first line is not a Conventional Commits header. It is a POSIX shell script, so it runs with the Git that comes with every platform, Git for Windows included. Download [`commit-msg`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/commit-msg), then install it in the repository: + +```bash +mkdir -p .githooks +cp commit-msg .githooks/ +chmod +x .githooks/commit-msg +git config core.hooksPath .githooks +``` + +Commit the `.githooks` folder, so that everyone gets the same hook. Each person runs the `git config` line once per clone. The `COMMIT_TYPES` variable changes the allowed types, and `REQUIRE_REFS=1` makes a `Refs:` trailer compulsory. + +A hook runs on the developer's machine and can be skipped, so check the same rule in CI on the pull request title or its commits. diff --git a/content/templates/requirements.md b/content/templates/requirements.md new file mode 100644 index 0000000..f362f8d --- /dev/null +++ b/content/templates/requirements.md @@ -0,0 +1,63 @@ +--- +title: Requirements and quality scenarios +--- + +# Requirements and quality scenarios + +These two templates help you write requirements that can be traced and tested. The first is for a single requirement, kept as data. The second is for a quality attribute (non-functional) requirement, written as a scenario. + +## Requirement + +Keep each requirement as a small YAML record in the repository, one file per requirement or one list per component. Tools can then check the IDs, build the traceability matrix, and fail the build when a requirement has no test. + +[[CAPTION:Figure]] Requirement record (download [`requirement.yaml`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/requirement.yaml)). + +```yaml +id: REQ-XX-0000 # stable, never reused +title: Short title +statement: The system shall ... +type: functional # functional | performance | security | safety | interface | constraint +level: firmware # system | subsystem | software | firmware | hardware +parent: REQ-SYS-0000 # the requirement this one refines +verification: test # test | analysis | inspection | demonstration +status: draft # draft | approved | implemented | verified | retired +owner: +rationale: Why this requirement exists. +``` + +Good requirement statements: + +- Use "shall" for a requirement and nothing else, one requirement per statement. +- Can be verified. "Fast" cannot be tested and "within 200 ms" can. +- Say what is needed, not how to build it. +- Trace up to a parent and down to the design and the tests. Name tests after the requirement IDs they verify. + +## Quality scenario + +A quality attribute such as performance, availability or security means little until it is measurable. A scenario states what triggers the behaviour, under which conditions, what the system does and how the response is measured. + +[[CAPTION:Figure]] Quality attribute scenario. + +```text +ID: NFR-XXXX-000 +Attribute: Performance and timing +Source: Who or what causes the stimulus +Stimulus: The event that triggers the behaviour +Environment: The conditions under which the requirement applies +Response: What the system does +Measure: How the response is measured, with a threshold +Verification: Test | Analysis | Inspection | Demonstration +``` + +For example: + +```text +ID: NFR-GW-012 +Attribute: Availability +Source: Mobile network +Stimulus: The cellular connection drops +Environment: Normal operation, signal of -110 dBm or better +Response: The gateway buffers readings and reconnects +Measure: Reconnects within 60 s in 99 % of drops, with no lost readings +Verification: Test (hardware-in-the-loop network drop test) +``` diff --git a/content/templates/rfc.md b/content/templates/rfc.md new file mode 100644 index 0000000..141904d --- /dev/null +++ b/content/templates/rfc.md @@ -0,0 +1,81 @@ +--- +title: Request for comments +--- + +# Request for comments + +A request for comments (RFC) proposes a significant change and asks the people it affects for their views before anyone commits to it. Use one for a change that crosses teams or sites, changes a shared interface or process, or costs enough that a wrong call would hurt. + +An RFC is a discussion and an [architecture decision record](adr.md) is its result. When the RFC closes, the sponsor records the outcome below, and each decision it produced gets its own ADR. + +- Set a comment period, usually one to two weeks, and keep to it. +- Name a sponsor who will make the call at the end, so the RFC does not stay open for ever. +- Keep the problem statement separate from the proposal. Reviewers often agree on one and not the other. + +## Template + +```markdown +--- +id: RFC-0000 +title: Short title +status: draft # draft | in-review | accepted | rejected | withdrawn +author: +sponsor: # who decides when the comment period ends +affected: [teams or sites] +comment-period-ends: YYYY-MM-DD +decision-date: YYYY-MM-DD +--- + +# RFC-0000: Short title + +## Summary + +Two or three sentences: what you propose and why. + +## Problem + +What problem are we solving, for whom, and what does it cost us today? + +## Goals and non-goals + +- Goals: +- Non-goals: + +## Proposal + +The design in enough detail for reviewers to judge it: interfaces, +data, behaviour, and diagrams where they help. + +## Alternatives considered + +Each alternative, and why it is not the proposal. Include doing nothing. + +## Impact + +Who and what it affects: teams, sites, products, cost, schedule. + +## Migration + +How we get from here to there, and how we roll back if it goes wrong. + +## Risks + +What could go wrong, and how we reduce each risk. + +## Open questions + +- Questions the author wants reviewers to answer. + +## Outcome + +Completed by the sponsor at the end of the comment period. + +- Decision: accepted | rejected | withdrawn +- Reason: +- Objections not resolved: +- Resulting ADRs and guideline changes: + +## Change log + +- YYYY-MM-DD: First draft. +``` diff --git a/py-doc.yml b/py-doc.yml index 6b6f4cf..b765dea 100644 --- a/py-doc.yml +++ b/py-doc.yml @@ -56,9 +56,28 @@ documents: outputs: {docx: {}, pdf: {}} templates: - # Templates & Checklists. The section's own pull request lists the rest of its files here. + # Templates & Checklists: the checklists first, then the templates. Files that tools read + # (YAML, the commit-msg hook, the canvases) 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/adr.md + - content/templates/rfc.md + - content/templates/requirements.md + - content/templates/interface-specification.md + - content/templates/architecture-document.md + - content/templates/architecture-canvases.md + - content/templates/experiment-record.md + - content/templates/postmortem.md + - content/templates/pull-request-and-commits.md + - content/templates/agent-task-brief.md + - content/templates/product-conformance-profile.md outputs: {docx: {}, pdf: {}} radar: