[Buildroot] [RFC][PATCH] docs: document check-package ignore list and GitLab CI selection

[Yegor Yefremov]

From: Yegor Yefremov <yegorslists at googlemail.com>

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(+)

diff --git a/AGENTS.md b/AGENTS.md
index a4d11570fc..1ff824affc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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/20260906215252.499931-1-ju.o@free.fr/>
 - <https://patchwork.buildroot.org/project/buildroot/patch/20260907110454.1071513-1-bernd@kuhls.net/>
 
+## 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,
-- 
2.34.1