Academy — Contributor Track

Land a canon-compliant PR without review blockers

Stage-by-stage walkthrough of the UIAO_125 Contributor track. For developers, canon stewards, and CI engineers working inside the substrate.

Published

May 6, 2026

The Contributor track comes out of UIAO_125 §1.2 unchanged — this page is the reader-facing walkthrough, not a parallel curriculum. Each stage names what to read, what to do, and how to verify. Gate evidence for stage N is a prerequisite for stage N+1.

Prerequisites (shared core)

Before stage 1, finish the shared core in UIAO_125 §1.1: substrate orientation, vocabulary, artifact literacy, governance flow. Those four modules take ~90 minutes.

Stage 1 — Foundation read

Read:

UIAO_001 SSOT
UIAO_003 Adapter Segmentation Overview — the dual-axis class × mission-class taxonomy you’ll live inside
UIAO_200 Substrate Manifest — the three-module topology
UIAO_201 Workspace Contract — how $UIAO_WORKSPACE_ROOT resolves

Do: clone the repo, run uiao substrate walk. Read the output.

Verify: exit code 0. Zero DRIFT-SCHEMA or DRIFT-PROVENANCE findings. You now know what a clean substrate looks like.

Stage 2 — Canon change workflow

Read:

CONTRIBUTING.md — the canon-change protocol
ADR-028 — a real ADR to study
ADR-030 — the pre-UIAO promotion path you’ll follow for any inbox-origin content

Do: write and land a small ADR — a doctrinal change, however minor, that you can defend. Use the existing ADRs as templates.

Verify: the ADR lands on main. CI is green. At least one named other-contributor has commented on the decision in the PR.

Stage 3 — Schema authoring and validation

Read:

src/uiao/schemas/ — the five JSON Schemas that validate every registry, manifest, and frontmatter edit
scripts/validate_schemas.py — how CI runs validation locally

Do: write a new JSON Schema (or meaningfully extend an existing one). Validate it against a fixture in the corresponding registry.

Verify: make schemas exits 0. The registry validates cleanly against your schema changes.

Stage 4 — Adapter development

Read:

Do: build a new adapter against the modernization-registry.yaml schema. Produce: - Tier 1 (live commercial tenant) evidence — run against a Microsoft 365 Developer Program tenant or a vendor dev program - Tier 2 (contract fixtures) evidence — under tests/fixtures/contract/<your-adapter>/

Verify: UIAO_121 conformance template filled for the adapter. Tier 1 + Tier 2 both green. Registry entry advances from draft → beta.

Stage 5 — Release engineering

Read: UIAO_118 Release Engineering.

Do: cut a release — tag triggers release.yml, which produces a signed wheel, a CycloneDX SBOM, and a sigstore bundle.

Verify: tag pushed to origin, release workflow green, release assets attached with three signature files. Matches the v0.2.1 pattern from the current release.

Completion

You’re done with the Contributor track when you’ve landed a PR that touches at least one canon artifact, at least one schema, and at least one test — and CI is green. That’s the criterion in UIAO_125 §3.

Adjacent paths

Operator track — complementary, not mutually exclusive
Comic tour — a 45-minute flyover if you want the mental model before diving deeper
Substrate Status — the honest reality map at any point