Cheat notes · Module 00 · Orientation
Orientation: a platform design you can check
A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.
The idea
A platform design written as structured files in Git can be reviewed, versioned and checked like code, so every decision has a place and a reason.
Remember
- Platform: "an integrated collection of capabilities defined and presented according to the needs of the platform's users" (CNCF Platforms White Paper).
- The design check (
scripts/check.mjs) parses YAML and Markdown and prints[ID] messageper broken rule. It runs nothing from the repo. - Two kinds of user: people and the coding agents that work for them.
npm ci --ignore-scriptsinstalls exactly the lock file, with no install scripts.- The workflow
design-checkruns the same check on every push tomainand every pull request.
Pitfalls
- Pushing without running the check:
mainturns red with[Y1]for invalid YAML. - A line indented by accident becomes part of the line above it in YAML.
Commands
npm run check | Check every design file |
gh run list --workflow design-check --limit 1 | The latest run on GitHub |
gh run view --log-failed | Why it failed |
Test yourself
Answer in your head first, then open the answer.
What does the design check never do?
Run anything from the repo. It only parses the files.
Where does the check run besides your laptop?
In the design-check workflow, on every pull request and push to main.
Why write the design in files rather than slides?
Changes become reviewable diffs with history, and a check can test them.
Where module 00 leaves you: Your repo on GitHub holds package.json, package-lock.json, .gitignore, scripts/check.mjs and .github/workflows/check.yaml. npm run check prints eight lines marked not written yet and Nothing written yet. The check is ready. The workflow run on main is green.