Skip to contentSkip to conversation

docs: document check-package ignore list and GitLab CI selection

RFC PATCH New Yegor Yefremov via buildroot 1 participant 1 message Sep 14

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 docs: document check-package ignore list and GitLab CI selection

From: Yegor Yefremov <[email protected]>

AGENTS.md told agents to run check-package and pointed at CI, but not how either behaves in practice. Two gaps regularly cost contributors a round trip.

First, .checkpackageignore is verified in both directions, so an entry that has gone stale is itself an error. Describe the line format and both failure modes: a listed check that no longer fails, reported against the package file, and an entry naming a file that no longer exists, reported against .checkpackageignore itself. Mention "make .checkpackageignore" to regenerate the list, with a caution that it rewrites every entry and hides unrelated regressions in the diff.

Second, which CI jobs run is selected by the suffix of the branch name pushed to GitLab, which is not discoverable without reading support/scripts/generate-gitlab-ci-yml. Add a table of the recognized suffixes, the behaviour when pushing a tag, the "test-pkg config:" commit-message block, and the "# gitlab-runner:" size comment.

Both sections were written against the implementation, not from memory:
utils/check-package, utils/checkpackagelib/lib_ignore.py, support/scripts/generate-gitlab-ci-yml and support/misc/gitlab-ci.yml.in. Both stale-entry errors were reproduced against the current tree before being documented. "make check-package" passes, though note it does not itself inspect AGENTS.md.

Assisted-by Claude:Opus-5 [Claude Code]
---
 AGENTS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
AGENTS.md +58 -0
index a4d11570fc..1ff824affc 100644
@@ -97,6 +97,30 @@ Choose validation appropriate to the change:
   utils/docker-run make check-package
   ```
 
+  `.checkpackageignore` lists the pre-existing violations that
+  `check-package` tolerates: one line per file, holding the file path
+  followed by the names of the checks allowed to fail for that file, for
+  example:
+
+  ```
+  package/foo/foo.mk lib_mk.Indent
+  board/foo/post-build.sh Shellcheck
+  ```
+
+  The list is verified in both directions, so a stale entry is itself an
+  error. After fixing a file, remove the check name it no longer triggers,
+  and remove the whole line once no check remains or the file is deleted or
+  renamed. Otherwise `make check-package` fails with one of:
+
+  ```
+  <file>:0: <check> was expected to fail, did you fix the file and forget to update .checkpackageignore?
+  .checkpackageignore:<n>: ignored file <file> is missing
+  ```
+
+  The complete list can be regenerated from the current tree with
+  `make .checkpackageignore`. Do this only deliberately: it rewrites every
+  entry and hides unrelated regressions in the diff.
+
 - Validate `DEVELOPERS` changes with:
 
   ```sh
@@ -146,6 +170,40 @@ example:
 - <https://patchwork.buildroot.org/project/buildroot/patch/[email protected]/>
 - <https://patchwork.buildroot.org/project/buildroot/patch/[email protected]/>
 
+## GitLab CI
+
+`.gitlab-ci.yml` first runs `support/scripts/generate-gitlab-ci-yml` over
+`support/misc/gitlab-ci.yml.in` to generate the real pipeline, then runs that
+pipeline as a child pipeline.
+
+Which jobs are generated depends on the name of the branch pushed to GitLab,
+so CI coverage is selected by naming the branch accordingly:
+
+| Branch name suffix | Jobs generated |
+| --- | --- |
+| *(none, or unrecognized)* | the basic checks only |
+| `-basics` | the basic checks, plus a `savedefconfig` check of all defconfigs |
+| `-defconfigs` | build every defconfig |
+| `-defconfigs-<pattern>` | build the defconfigs starting with `<pattern>` |
+| `-<name>_defconfig` | build that defconfig only |
+| `-runtime-tests` | the whole `support/testing` suite |
+| `-tests.<prefix>` | the runtime tests starting with `tests.<prefix>` |
+
+The basic checks are `make check-package`, `utils/check-symbols`,
+`utils/get-developers -v`, and the `utils/checkpackagelib/` and
+`utils/checksymbolslib/` pytest suites.
+
+Pushing a git tag instead runs the basic checks, the `qemu_*` defconfigs, and
+all runtime tests.
+
+Independently of the branch name, a commit message containing a line reading
+`test-pkg config:` followed by an indented config fragment additionally
+triggers `utils/test-pkg` jobs for that fragment, against all toolchains.
+
+A runtime test needing a larger runner declares it with a
+`# gitlab-runner: <size>` comment on the line above its class definition. The
+default is `small`.
+
 ## Finding responsible developers
 
 `DEVELOPERS` lists developers associated with architectures, packages, boards,
Signature · 6 lines
2.34.1

_______________________________________________
buildroot mailing list
[email protected]
https://lists.buildroot.org/mailman/listinfo/buildroot