REPOS: remove the stale duplicate of Naming..Scaffolding

The front-matter commit (d234a2d) accidentally appended a second copy of
the Naming through Scaffolding sections. The current-state rewrite
(574df14) then updated only the first copy, leaving the tail with old
wording and the superseded `type: default` front-matter rule. The tail
held nothing the first copy and the Front matter section don't.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mikkeli
2026-10-09 00:51:59 +09:00
parent feb9564ce4
commit 16b1031b8c
-97
View File
@@ -257,100 +257,3 @@ for any particular repo**. The `type` discriminates:
`status` and `updated` make a plan's staleness visible — plans go stale and `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 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. written this morning. `date` on a report records the moment it describes.
## Naming
Repositories are named `<group>-<thing>`, 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.