mikkeli
d234a2da37
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
---
|
|
type: reference
|
|
---
|
|
# Repositories
|
|
|
|
## Splitting rule
|
|
|
|
- **`project-yukart`** — overview, roadmap, cross-cutting design. No code, ever.
|
|
- **`orin-nano-env-setup`** — the host: kernel modules, drivers, OS packages,
|
|
device permissions, systemd plumbing. Anything that must be true *before* an
|
|
application starts.
|
|
- **One repo per application or application cluster.** A cluster is a set of
|
|
services that are developed, versioned and deployed together.
|
|
- **Helper/deployment repos** stand alone when they are reusable outside Yukart.
|
|
|
|
Anything cross-repo — topic names, payload schemas, the DBC — belongs in the
|
|
contracts repo, not copied into each consumer.
|
|
|
|
## Current
|
|
|
|
| Repository | Role |
|
|
|---|---|
|
|
| [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture |
|
|
| [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
|
|
| [app-flutter](gitea:yukart/app-flutter) | Flutter display client |
|
|
| [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the HTTP surface |
|
|
| [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance |
|
|
| [tool-mapmint](gitea:yukart/tool-mapmint) | Map artifact minting, workstation-side |
|
|
| [tool-mock](gitea:yukart/tool-mock) | Mocks and fixtures — a fake car on a workstation |
|
|
|
|
## Planned
|
|
|
|
| Repository | Role | Why separate |
|
|
|---|---|---|
|
|
| `contracts` | Topic namespace, payload schemas, Z27AG DBC | Consumed by every other repo, including non-Jetson clients; must not be duplicated |
|
|
| `svc-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin |
|
|
| `app-esp32` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
|
|
| `app-hud` | Local renderer for a directly-driven screen (Class A) | Its own toolchain and graphics stack — **in question**, see the display contract |
|
|
| `tool-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |
|
|
|
|
Create these lazily — when there is something to put in them, not before.
|
|
|
|
## 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. 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 `<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.
|