Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions docs/implementations/2026-11-17-implementation-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Implementation-record template

Date: 2026-11-17

## Problem / Motivation

Every meaningful change in this organisation ships with a record at `docs/implementations/YYYY-MM-DD-<slug>.md`, which explains what was done, why, and how it was checked. The rule is that each record follows a template at `docs/implementations/_TEMPLATE.md`, but no repository had one. Records were written from memory of the required sections, so their structure drifted, and a reader could not tell whether a missing section had been skipped or did not apply.

## What Changed

| File | Change |
|---|---|
| `docs/implementations/_TEMPLATE.md` | New. The template: the seven required sections, with a short note under each on what it must contain. |
| `docs/implementations/2026-11-17-implementation-template.md` | New. This record. |

## Implementation Approach

The template lists the seven sections in their required order: Problem / Motivation, What Changed, Implementation Approach, Mathematical / Statistical Details, Design Decisions, Verification, Related Docs. Each section carries an HTML comment that says what belongs in it. Comments do not render on GitHub, so a record copied from the template and filled in shows only its content.

The same file is added, byte for byte, to `ddr4-udimm`, `spdr` and `.github`, each through its own pull request.

## Design Decisions

- **One template, copied into each repository**, not a single shared file linked from all of them. A contributor working in one repository finds it where the rule says it is, and the rule names a path inside the repository.
- **Comments, not example text.** Placeholder prose left in by mistake would render and read as content. A forgotten comment is invisible.
- **"Does not apply" is said, not implied.** A section that does not apply says so in one line. Only the mathematical section may be deleted outright, for a purely structural change such as this one.
- **Existing records are left as they are.** Older records use their own headings, some numbered. Rewriting them would change the historical record for no gain.

## Verification

1. Open `docs/implementations/_TEMPLATE.md` on GitHub and confirm that the seven headings render in order and the comments do not show.
2. Confirm that this record follows the template.
3. Confirm that the file is identical in all three repositories: `git hash-object docs/implementations/_TEMPLATE.md` gives the same hash in each.

## Related Docs

- Organisation profile: [github.com/Pactolus-Microelectronics](https://github.com/Pactolus-Microelectronics)
57 changes: 57 additions & 0 deletions docs/implementations/_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
<!--
Template for an implementation record. Copy it to
docs/implementations/YYYY-MM-DD-<slug>.md, where <slug> is a short hyphenated
name for the change (for example `erc-gate-in-ci`). Fill in every section and
delete these comments. A section that does not apply says so in one line,
except "Mathematical / Statistical Details", which may be deleted for a purely
structural change.
-->

# <Title: what changed, in a few words>

Date: YYYY-MM-DD

## Problem / Motivation

<!-- Why was this change needed? What risk, gap or wrong claim did it address? -->

## What Changed

| File | Change |
|---|---|
| `path/to/file` | One sentence on what changed in this file. |

## Implementation Approach

<!--
How it was done: the pattern, algorithm or strategy chosen. For a function,
state its contract: inputs, outputs, side effects and the invariants it relies on.
-->

## Mathematical / Statistical Details

<!--
Any formula, statistical test or numeric algorithm, in plain English with
notation, so a reader can audit it without reading the code. Every number
traces to its source. Delete this section only for a purely structural change.
-->

## Design Decisions

<!-- The alternatives that were considered, and why this one was chosen over them. -->

## Verification

<!--
Concrete, runnable steps that confirm the change works, and what each one
showed when it was run. A status word (complete, validated, tested, measured)
says at what level and points to the evidence.
-->

1.

## Related Docs

<!-- Links to the relevant documents, issues and pull requests. -->

-
Loading