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