36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# Naming conventions (first-party vs vendored)
|
|
|
|
This repository distinguishes **first-party** Bare OS sources from **vendored** third-party trees. Governance wording rules and identifier style apply differently in each.
|
|
|
|
## First-party trees
|
|
|
|
Subject to [kernel program](kernel-program.md) vocabulary, CI terminology checks (`scripts/verify-banned-terminology.mjs`), and the alias matrix ([Naming alias matrix](../docs/reference/naming-alias-matrix.md)):
|
|
|
|
- `packages/bare-os-booter/`, `packages/bare-os-protocol/`, `packages/bare-os-coreutils/`, `packages/bare-os-seeder/` (except its vendored subtree below)
|
|
- `kernel/` except `kernel/lib/bare/`
|
|
- `docs/`, `handbook/`, `developer-guide/`, `users-manual/`, `scripts/`
|
|
|
|
Prefer **boot stage** / **boot step** / **capability word** language in new prose and APIs. When renaming symbols, keep **deprecated aliases** until the published deprecation window ends (see [Naming migrations](naming-migrations.md)).
|
|
|
|
## Vendored exception
|
|
|
|
`kernel/lib/bare/` (mirrored under `packages/bare-os-seeder/kernel/lib/bare/`) is **vendored**. It may contain legacy English tokens, upstream identifiers, and MIME-adjacent strings. The terminology verifier **skips** this subtree entirely.
|
|
|
|
## Environment variables
|
|
|
|
- Prefix operational flags with `BARE_OS_`.
|
|
- Prefer `*_BOOT_SKIP_STAGES` over legacy `*_BOOT_SKIP` spellings where both exist; document aliases in the naming alias matrix.
|
|
|
|
## `ctx` methods
|
|
|
|
- New APIs use **`bareOs…`** camelCase on the injected context object.
|
|
- Canonical boot hook names: **`bareOsRegisterBootStepHook`**, **`bareOsInvokeBootStepHooks`**, **`bareOsEmitBareBootStepHint`**. Legacy `**…BootPhase…`** methods remain as thin wrappers.
|
|
|
|
## `/proc` and wire-visible paths
|
|
|
|
- Do not remove legacy proc filenames or JSON keys without a **versioned alias** period. Internal variable names may use neutral wording while on-disk names stay stable.
|
|
|
|
## Extension and capability identifiers
|
|
|
|
- Use stable string keys aligned with `packages/bare-os-protocol` capability documentation and `docs/schemas/` where applicable.
|