Compare commits
1 Commits
e1cefa5be2
...
docs/teams
| Author | SHA1 | Date | |
|---|---|---|---|
| 12bd24a973 |
@@ -2165,6 +2165,11 @@ makes §0.1's roster possible:
|
|||||||
Every phase is independently shippable and leaves the site working. Phases 1 and 2 are the only hard
|
Every phase is independently shippable and leaves the site working. Phases 1 and 2 are the only hard
|
||||||
serial dependency in the list.
|
serial dependency in the list.
|
||||||
|
|
||||||
|
**Phase 11 is the exception to "independently shippable", and it is last on purpose** (org lead,
|
||||||
|
2026-08-18). The integration kit teaches an outside audience to build against this contract; Teams
|
||||||
|
expands the contract, so the book is the last thing owed before `edge` becomes `main`. It is also the
|
||||||
|
only phase that cannot merge until the cutover exists — see its own note.
|
||||||
|
|
||||||
### Phase 0 — a one-guild roster spike (`servuo-plugins` + `link`, throwaway)
|
### Phase 0 — a one-guild roster spike (`servuo-plugins` + `link`, throwaway)
|
||||||
|
|
||||||
**Not a deliverable — insurance on the phase that gates everything else.** `servuo-plugins` has no CI
|
**Not a deliverable — insurance on the phase that gates everything else.** `servuo-plugins` has no CI
|
||||||
@@ -2505,6 +2510,56 @@ rendering the admin UI from the declaration rather than from a hardcoded "Discor
|
|||||||
purpose: extracting a capability surface from one working implementation is honest; designing it before
|
purpose: extracting a capability surface from one working implementation is honest; designing it before
|
||||||
one exists is speculation.
|
one exists is speculation.
|
||||||
|
|
||||||
|
### Phase 11 — the integration kit (`integration-kit`) — **the last phase before the cutover**
|
||||||
|
|
||||||
|
The kit is the instruction book for putting a *different* game on this platform, written for an
|
||||||
|
audience outside this org. Teams expands the contract that book teaches against, so the book is the
|
||||||
|
last thing this bet owes before `edge` becomes `main`.
|
||||||
|
|
||||||
|
**One sentence in it is already wrong.** `book/02-website-module.md` states, of extension slots,
|
||||||
|
"**core declares a slot; a module may only fill one**". Phase 3 inverted exactly that: with
|
||||||
|
`declareModuleSlot` a MODULE declares a place on its own page and CORE fills it, and by phase 6
|
||||||
|
`module-uo` declares three. A new game's module cannot implement Teams at all without the inverted
|
||||||
|
direction, so this is not a stale detail — it is the shape the reader needs and does not have.
|
||||||
|
|
||||||
|
**Two genuinely new shapes to teach, and only two:**
|
||||||
|
|
||||||
|
- **The inverted slot** (§3.7a) — a module declaring a place for core, why the name is namespaced under
|
||||||
|
the module's own id, and why a module wants *separate* slots rather than one (it decides where each
|
||||||
|
of core's contributions sits on a page it owns).
|
||||||
|
- **`registerTeamProvider`** — the first registration where **core calls the module and waits**. Every
|
||||||
|
other one is the module claiming a mount or core notifying it. The envelope, the 10-second budget,
|
||||||
|
and the asymmetry that matters: every call fails **stale** (core keeps what it has) except
|
||||||
|
`projectRoster`, which fails **closed**, because for a visibility question "keep what you have"
|
||||||
|
means serving the roster unprojected.
|
||||||
|
|
||||||
|
`pageUrlTemplate` is a footnote beside those — one optional string, and the reader meets it while
|
||||||
|
reading the provider.
|
||||||
|
|
||||||
|
**What this phase explicitly does NOT do: enumerate the contract.** The kit already teaches only four
|
||||||
|
members and has never mentioned `registerNotificationStreams`, `registerAnnounceLeg` or
|
||||||
|
`registerPostHook`, all of which predate Teams. That is the design, not a gap:
|
||||||
|
[`MODULE_API.md`](MODULE_API.md) is normative and the kit teaches one path end to end and links out.
|
||||||
|
The question this phase answers is "did the teaching path change", and the answer is yes in two
|
||||||
|
places and no everywhere else.
|
||||||
|
|
||||||
|
**Then the two mechanical lines:** `ci/core-ref.json`'s sha moves to the cutover commit and
|
||||||
|
`template/module.json`'s `coreApi` becomes `^1.6.0`, which puts `scripts/checkCoreApi.js` back to
|
||||||
|
green. That check is an **equality**, and its going red is the mechanism rather than a bug — a
|
||||||
|
contract bump is meant to turn that repo red until someone has re-read the chapters. Moving the pin is
|
||||||
|
that person saying they have.
|
||||||
|
|
||||||
|
> **Ordering, stated because it is genuinely awkward.** This phase is written *before* the cutover and
|
||||||
|
> can only *merge after* it. CI clones the pinned sha and checks the template against that core's
|
||||||
|
> `MODULE_API_VERSION` — and 1.6.0 does not exist on `main` until the cutover lands, so there is no sha
|
||||||
|
> to pin and no core for the template to build against until then. Write the chapters last, open the
|
||||||
|
> PR once the cutover merge exists, and put the pin move in it.
|
||||||
|
|
||||||
|
**Checks that gate it** (all dependency-free Node scripts, run from the repo root — which is also how a
|
||||||
|
reader runs them): `checkLinks`, `checkRenameSites`, `checkChapterPaths`, `checkCoreApi --core .core`,
|
||||||
|
plus the template's own `npm ci` / `check:imports` / `build` / `check:externals` / `npm test` on both
|
||||||
|
halves. Build the client **before** the client tests; two of them read the built chunk.
|
||||||
|
|
||||||
### Cross-cutting, every phase that touches the server
|
### Cross-cutting, every phase that touches the server
|
||||||
|
|
||||||
`npm run swagger` regenerated and committed · `npm run routes:manifest -- --check` zero-line diff ·
|
`npm run swagger` regenerated and committed · `npm run routes:manifest -- --check` zero-line diff ·
|
||||||
|
|||||||
Reference in New Issue
Block a user