diff --git a/docs/REPOS.md b/docs/REPOS.md index 82087b4..99451dd 100644 --- a/docs/REPOS.md +++ b/docs/REPOS.md @@ -257,100 +257,3 @@ for any particular repo**. The `type` discriminates: `status` and `updated` make a plan's staleness visible — plans go stale and reports do not, and without them a plan from months ago reads identically to one written this morning. `date` on a report records the moment it describes. - -## 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 -place where there is a real toolchain to carry, which is the ESP32 case above. - -What every component repo has instead: - -``` -README.md frontmatter, the shared blurb, "What this repo is - about", then links to guidelines and impl/ -docs/GUIDELINES.md frontmatter, 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 -``` - -**Frontmatter follows the document's nature, not its location:** living documents -carry `type: default`; historical records do not. So README, GUIDELINES, BOM and -plans have it, and reports do not. The hub carries none at all, being the portal -rather than a component.