docs: stop telling contributors to register a device in master.yml (#134)
Step 6 of "Adding a new device" still said to add `- <device>` to the matrix in .github/workflows/master.yml, and called that matrix "the *only* build registry". Neither has been true since #120 moved the matrix into .github/scripts/ci-matrix.py, where it is derived from the tree rather than listed. master.yml has no device list at all. Not a hypothetical staleness: #111 (Tapo TC70 v3) and #108 (KC110) each append a line to a block that no longer exists, so both are merge conflicts rather than the one-line changes they were written as. Their authors did the documented thing. So step 6 is now the opposite instruction -- there is nothing to add, and adding it is the mistake. It also names NOT_BUILT, since that is the one list a contributor could reasonably go looking for, and says to leave it alone. Two adjacent claims went stale with the same change: the master.yml bullet described a cron-and-dispatch workflow with no pull_request trigger, and nothing mentioned ci-matrix.py at all -- including that --self-test runs in the Select devices job and will fail a PR that puts the tree and the selector out of step. A second correction, caught by Qodo in review: "opening the PR is what gets the device built" holds only for a non-draft PR. classify() returns needs_build=False for a draft and self_test() asserts it; master.yml lists ready_for_review in its triggers precisely because a PR opened as a draft would otherwise never build once marked ready. Left as written, a contributor could open a draft, see no build, and read that as the device being fine. The ci:full label is documented for the same reason -- it is the other contributor-facing lever over the matrix.
This commit is contained in:
@@ -116,14 +116,21 @@ size first (the README device table lists all of these for existing boards).
|
|||||||
`libsns_<sensor>.so` not provided by the SoC osdrv, a patched `load_hisilicon`, a sensor
|
`libsns_<sensor>.so` not provided by the SoC osdrv, a patched `load_hisilicon`, a sensor
|
||||||
`.ini`), or a custom kernel config at `br-ext-chip-<vendor>/board/<family>/<soc>.generic.config`.
|
`.ini`), or a custom kernel config at `br-ext-chip-<vendor>/board/<family>/<soc>.generic.config`.
|
||||||
Keep the file count minimal — anything reusable belongs upstream in `OpenIPC/firmware`.
|
Keep the file count minimal — anything reusable belongs upstream in `OpenIPC/firmware`.
|
||||||
6. **Register for nightly CI.** Add `- <device>` to the matrix in
|
6. **CI registration is automatic — there is nothing to add.** The build matrix is derived
|
||||||
`.github/workflows/master.yml` under the matching group (SoC/APFPV/FPV/Ruby/etc.). This
|
from the tree by `.github/scripts/ci-matrix.py`: a device is registered by having
|
||||||
matrix is the *only* build registry — a device not listed here is never built or released.
|
`devices/<dir>/.../<dir>_defconfig`, full stop. Do **not** add the device to
|
||||||
|
`.github/workflows/master.yml` — it holds no device list, and a PR that adds one is just a
|
||||||
|
merge conflict. The only written-down list is `NOT_BUILT` in `ci-matrix.py`, the opt-out
|
||||||
|
for devices that exist but are deliberately not built; leave it alone unless you mean to
|
||||||
|
opt out. Opening the PR is therefore what gets the device built, narrowed to just it —
|
||||||
|
but a **draft** PR deliberately builds nothing, so mark it ready for review when you want
|
||||||
|
that build. `ci:full` as a PR label overrides the narrowing and builds every device.
|
||||||
7. **Document it.** Add a row to the device table in `README.md` (and the clones table if it's
|
7. **Document it.** Add a row to the device table in `README.md` (and the clones table if it's
|
||||||
a rebrand of an existing board).
|
a rebrand of an existing board).
|
||||||
8. **Build & verify locally.** `./builder.sh <device>`, then check
|
8. **Build & verify.** `./builder.sh <device>`, then check
|
||||||
`archive/<device>/<timestamp>/` for the image and confirm it fits the flash size. Use
|
`archive/<device>/<timestamp>/` for the image and confirm it fits the flash size. Use
|
||||||
`package.sh <pkg>` to iterate on a single package without a full re-clone.
|
`package.sh <pkg>` to iterate on a single package without a full re-clone. A non-draft PR
|
||||||
|
builds it on CI too, but a local build is the faster loop while the defconfig is moving.
|
||||||
|
|
||||||
## `package/` — builder-local Buildroot packages
|
## `package/` — builder-local Buildroot packages
|
||||||
|
|
||||||
@@ -135,9 +142,10 @@ via `SITE_METHOD = local`), `demo-openipc`. Read the package `Config.in` help te
|
|||||||
|
|
||||||
## CI (`.github/workflows/`)
|
## CI (`.github/workflows/`)
|
||||||
|
|
||||||
- **master.yml** ("Build") — nightly cron (03:00 UTC) + manual dispatch. Builds the full
|
- **master.yml** ("Build") — nightly cron (03:00 UTC), manual dispatch, and pull requests.
|
||||||
device matrix; it always rebuilds (the input that actually changes is firmware HEAD /
|
Every event except `pull_request` builds the full device matrix and always rebuilds (the
|
||||||
toolchain / kernel, all *outside* this repo, so there is no skip-gate). Caches ccache and
|
input that actually changes is firmware HEAD / toolchain / kernel, all *outside* this repo,
|
||||||
|
so there is no skip-gate); a PR builds only the devices its diff can reach. Caches ccache and
|
||||||
Buildroot's `BR2_DL_DIR` at `/tmp/builder-dl` (outside `openipc/` because `builder.sh`
|
Buildroot's `BR2_DL_DIR` at `/tmp/builder-dl` (outside `openipc/` because `builder.sh`
|
||||||
`rm -rf`s that tree each run). Uploads each image to three release tags: dated
|
`rm -rf`s that tree each run). Uploads each image to three release tags: dated
|
||||||
`nightly-YYYYMMDD-<sha>`, rolling `nightly`, and legacy `latest`; pushes the NOR build to
|
`nightly-YYYYMMDD-<sha>`, rolling `nightly`, and legacy `latest`; pushes the NOR build to
|
||||||
@@ -149,6 +157,15 @@ via `SITE_METHOD = local`), `demo-openipc`. Read the package `Config.in` help te
|
|||||||
`manifest.json` + `manifest.flat` on the `gh-pages` branch via
|
`manifest.json` + `manifest.flat` on the `gh-pages` branch via
|
||||||
`.github/scripts/enrich_manifest.py`.
|
`.github/scripts/enrich_manifest.py`.
|
||||||
- **cleanup.yml** — weekly prune of dated `nightly-*` releases beyond the newest 90.
|
- **cleanup.yml** — weekly prune of dated `nightly-*` releases beyond the newest 90.
|
||||||
|
- **ci-matrix.py** (`.github/scripts/`) — not a workflow, but where the device registry now
|
||||||
|
lives. It maps the paths a PR touches to the devices that build them, reading the mapping
|
||||||
|
off the tree the same way `builder.sh` does: a file affects exactly the devices whose
|
||||||
|
defconfig shares its directory (which is why `devices/common/` is 18 targets, not one).
|
||||||
|
Recognising a path can only *narrow*; anything it has never heard of widens back to the
|
||||||
|
full matrix, so a misclassification costs runner time, never coverage. The nightly is never
|
||||||
|
narrowed. `ci-matrix.py --self-test` checks the file still agrees with the tree and runs in
|
||||||
|
the `Select devices` job, so it fails the PR rather than silently skipping a device — run it
|
||||||
|
after touching anything under `devices/`.
|
||||||
|
|
||||||
### Moving-ref cache caveat
|
### Moving-ref cache caveat
|
||||||
The monthly `builder-dl` cache can freeze packages pinned to a moving ref (VERSION = HEAD /
|
The monthly `builder-dl` cache can freeze packages pinned to a moving ref (VERSION = HEAD /
|
||||||
|
|||||||
Reference in New Issue
Block a user