Repository setup¶
The one-time steps an org owner runs after creating a repository from the template, and before the first PR.
The scripts are in kokeb-labs/.github/org/. Each one is a dry run
unless given --apply; --org names the organisation (a driver lives in kokeb-labs-drivers, everything else in
kokeb-labs) and --repo limits it to one repository. The rules behind them are in
repo-governance.md.
1. Create and scaffold¶
gh repo create kokeb-labs-drivers/driver-<chip> --private --template kokeb-labs/driver-template --clone
cd driver-<chip>
git switch -c feat/initial-driver
python3 tools/setup.py
tools/setup.py asks for the bus and a one-sentence description, scaffolds, builds and runs the host tests;
tools/scaffold.py --help lists every option (--platforms host,esp32 is a driver's default; a library gets
host unless esp32 is asked for); it ends with a checklist of what is left to fill in.
2. Apply the org settings¶
From a checkout of kokeb-labs/.github, after adding the repository to org/repos.json by PR. Its entry sets
the About: the description is the README's first sentence (C++20 driver for the <vendor> <parts> <what it is>
(<bus>)), and the topics are the shared kokeb-labs driver embedded cpp20 misra-cpp header-only plus the bus, the
device category, the vendor and the part (spi eeprom microchip at25040b):
python3 org/kokeb_org.py --org kokeb-labs-drivers --repo driver-<chip> # the plan
python3 org/kokeb_org.py --org kokeb-labs-drivers --repo driver-<chip> --apply # settings, Actions, labels, ...
A private repository on the free plan gets the settings, Actions policy and labels; security features and
rulesets need it public (the tool says which sections it skips). Run it again, with --check to see that nothing is
pending, after the repository goes public (section 6).
Run it without --apply first to see what changes.
3. Create the labels¶
--apply in step 2 already creates them; this is the manual way, for a repository outside the org tool.
python3 - <<'PY'
import subprocess, yaml
for label in yaml.safe_load(open(".github/labels.yml")):
subprocess.run(["gh", "label", "create", label["name"], "--color", label["color"],
"--description", label["description"], "--force"], check=True)
PY
4. Require the gate¶
After the first CI run has produced the check CI gate / gate, add it to the repository's main-review ruleset as
described in The required check.
5. Wire it in¶
Add the repository as a submodule or CMake dependency where it is consumed, in its own pin PR, then follow checklists/new-driver.md.
6. First release candidate and going public¶
The order that works, and the reason for each step:
maingreen first. Push, and wait forCIonmain, includingCI gate / gate. The docs publish togh-pagesfrommainbefore any tag does. Triage a failure with thereleaseskill, section 5: re-run the failed jobs only when the infrastructure failed.- Tag
vX.Y.Z-rc.1on that commit (thereleaseskill). Its CI repeats the run, then the Release workflow publishes the pre-release: firmware, SBOM, checksums. A pre-release publishes its docs under its own tag and takeslatestonly when no other version holds it. - Make it public (
gh repo edit <org>/<repo> --visibility public --accept-visibility-change-consequences), thenpython3 org/kokeb_org.py --org kokeb-labs-drivers --repo driver-<chip> --apply: rulesets, secret scanning with push protection, CodeQL and private vulnerability reporting need a public repository. If the last call answers 422, run it again after a few seconds; the new visibility has not reached that endpoint yet. - Enable Pages from the
gh-pagesbranch, root, and openhttps://<org>.github.io/<repo>/. --checkreports0 change(s) pending.
A private repository on the free plan shares a small Actions storage quota with the rest of its organisation. A full quota fails every upload step in every repository of it at once, which looks like a broken workflow and is not one; a public repository does not count against it.