From d234a2da37163b7dc1442b8a90bf64a40935b61d Mon Sep 17 00:00:00 2001 From: Mikkeli Date: Fri, 4 Sep 2026 14:14:17 +0900 Subject: [PATCH] Adopt designed front matter: typed, with staleness on plans MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces `type: default` — one value across every document, read by nothing, so it discriminated nothing. Types are now reference, guidelines, plan and report, applied to every markdown file with no exceptions for the hub. Plans carry status and updated, reports carry date. REPOS.md already noted that plans go stale and reports do not, but nothing made that visible: a plan from months ago looked identical to one written today. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ --- OVERVIEW.md | 3 ++ README.md | 3 ++ docs/ARCHITECTURE.md | 3 ++ docs/ORIN-RUNTIME.md | 3 ++ docs/REPOS.md | 118 +++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 5 ++ 6 files changed, 135 insertions(+) diff --git a/OVERVIEW.md b/OVERVIEW.md index c8b3b1b..ca80cf4 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -1,3 +1,6 @@ +--- +type: reference +--- # Project Yukart Overview A Mitsubishi Z27AG Colt Ralliart, plus diff --git a/README.md b/README.md index c1f473f..8f79d20 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +--- +type: reference +--- # Project Yukart Making a 2008 Mitsubishi Colt Ralliart (Z27AG) a bit smarter with modern technologies. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 10cc5f8..9dc4614 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,3 +1,6 @@ +--- +type: reference +--- # Architecture ## The one rule diff --git a/docs/ORIN-RUNTIME.md b/docs/ORIN-RUNTIME.md index 0b34463..faeb5b3 100644 --- a/docs/ORIN-RUNTIME.md +++ b/docs/ORIN-RUNTIME.md @@ -1,3 +1,6 @@ +--- +type: reference +--- # Orin runtime [ARCHITECTURE.md](ARCHITECTURE.md) describes services and the bus without saying diff --git a/docs/REPOS.md b/docs/REPOS.md index 8d85c8e..d2c185c 100644 --- a/docs/REPOS.md +++ b/docs/REPOS.md @@ -1,3 +1,6 @@ +--- +type: reference +--- # Repositories ## Splitting rule @@ -113,6 +116,121 @@ it records the investigation and the dead ends, not just the final commands. ### Scaffolding conventions +No template repository. Template instantiation is fork-at-create, so it could not +reach repos that already exist, and the scaffolding is a handful of markdown files +— lighter than the machinery to manage it. A template earns its place where there +is a real toolchain to carry, which is the ESP32 case above. + +Every component repo carries: + +``` +README.md the shared blurb, "What this repo is about", then + links to guidelines and impl/ +docs/GUIDELINES.md numbered sections, ends "## N. To be added" +docs/impl/plans/ at least INITIAL.md +docs/impl/reports/ +docs/BOM.md only where the repo owns hardware +``` + +### Front matter + +Every markdown document carries front matter, with **no exceptions for the hub or +for any particular repo**. The `type` discriminates: + +| `type` | Applies to | Extra fields | +|---|---|---| +| `reference` | READMEs, OVERVIEW, ARCHITECTURE, BOM — things that describe what is | — | +| `guidelines` | `GUIDELINES.md` | — | +| `plan` | anything under `impl/plans/`, plus `ROADMAP.md` | `status`, `updated` | +| `report` | anything under `impl/reports/` | `date` | + +`status` is one of `active`, `superseded` or `done`. + +The extra fields exist for one reason. This document already observes that **plans +go stale and reports do not** — but nothing made staleness visible, so a plan +written months ago looked identical to one written this morning. `status` and +`updated` fix that; `date` on a report records the moment it describes, which is +the whole value of a report. + +A `type` with one possible value would be decoration. This one has four and they +are worth grepping for. + +## Naming + +Repositories are named `-`, with **no project prefix**. The `yukart` +Gitea org already namespaces everything, so a `yukart-` prefix would be a constant +occupying the most significant characters of every name — pure noise in a sorted +index, and the reason the earlier scheme scattered. + +| Group | Meaning | +|---|---| +| `svc-` | A service running on the Orin | +| `app-` | A display client, running off the Orin | +| `tool-` | Off-car tooling; never deployed to the car | + +The goal is that **lexical order equals semantic grouping**: opening the org +listing puts every service together, every client together, every tool together. +The group segment does that work because it is the first thing that varies. + +Ungrouped singletons — `contracts` — are fine where a category has exactly one +member and always will. + +`project-yukart` and `orin-nano-env-setup` predate this and keep their names +rather than paying a rename for two repos that are stable and easy to find. + +### Reusability + +Nothing in a name marks a repo as reusable. A component that turns out to be +genuinely reusable outside Yukart **leaves the org** rather than being renamed — +location says it, not spelling. + +## Helper and deployment repos + +Arduino and ESP32 work implies flashing, build and deployment scaffolding that +is likely to be reused. Keep those generic and outside the org — e.g. an ESP32 +project skeleton with the toolchain, flashing scripts and CI already wired up. + +### Gitea template repositories + +Gitea supports these: repo **Settings → Repository → Template**, after which the +repo offers **"Use this template"** to create new repos from it. + +Use a template repo for **scaffolding** — a new ESP32 or Arduino project that +should start with the toolchain, directory layout and flashing scripts in place. + +Do **not** use one for code you intend to keep updating in one place. Template +instantiation is a fork-at-create: the copy has no link back, so improvements to +the template never reach repos already created from it. For genuinely shared +code, use a git submodule or publish a package instead. + +Rule of thumb: *template for the starting shape, submodule/package for living +code.* + +## Linking convention + +Cross-repo links use the `gitea:owner/repo` scheme, as established in the hub +README — e.g. `[Environment setup](gitea:yukart/orin-nano-env-setup)`. + +## Per-repo document layout + +Following the convention already set by `orin-nano-env-setup`: + +``` +README.md minimal portal, points everywhere else +docs/ + GUIDELINES.md implementation practice for this repo + BOM.md hardware, where the repo owns hardware + impl/ + plans/ what is intended + reports/ what actually happened, and why +``` + +The `impl/plans` ÷ `impl/reports` split is worth keeping: plans go stale, +reports do not. A report like `PCAN-SETUP.md` stays valuable precisely because +it records the investigation and the dead ends, not just the final commands. + +### Scaffolding conventions + No template repository for this. Template instantiation is fork-at-create, so it could not reach the repos that already exist, and the scaffolding is three markdown files — lighter than the machinery to manage it. A template earns its diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index e34441a..f27ff6c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,3 +1,8 @@ +--- +type: plan +status: active +updated: 2026-09-04 +--- # Roadmap Phases are ordered by dependency, not by date. Each phase should end with