PlatformEngr® Platform fundamentals course

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] message per broken rule. It runs nothing from the repo.
  • Two kinds of user: people and the coding agents that work for them.
  • npm ci --ignore-scripts installs exactly the lock file, with no install scripts.
  • The workflow design-check runs the same check on every push to main and every pull request.

Pitfalls

  • Pushing without running the check: main turns red with [Y1] for invalid YAML.
  • A line indented by accident becomes part of the line above it in YAML.

Commands

npm run checkCheck every design file
gh run list --workflow design-check --limit 1The latest run on GitHub
gh run view --log-failedWhy 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.