[Buildroot] [PATCH v3 1/1] docs: add agent guidance

* [Buildroot] [PATCH v3 1/1] docs: add agent guidance
@ 2026-09-10  1:58 Matthew Weber
  2026-09-11 19:14 ` Fiona Klute via buildroot
  0 siblings, 1 reply; 4+ messages in thread
From: Matthew Weber @ 2026-09-10  1:58 UTC (permalink / raw)
  To: buildroot; +Cc: ju.o, Matthew Weber

Document Buildroot structure, documentation, build and validation
workflows, mailing-list submission, Patchwork usage, and AI-assisted
contribution requirements.

This file provides shared guidance for AI agents that recognize
AGENTS.md. Claude Code projects can load it by importing @AGENTS.md
from a root CLAUDE.md file.

Assisted-by: GitHub Copilot
Signed-off-by: Matthew Weber <matt@thewebers.ws>
---
Changes v2 -> v3:
	- add Docker, local validation, GitLab CI, runtime-test, and Patchwork
		guidance, including the current Patchwork URLs (suggested by Julien
		Olivain)
	- add a root CLAUDE.md import for Claude Code
		(suggested by Yegor Yefremov)

 AGENTS.md | 300 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |   1 +
 2 files changed, 301 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..a4d11570fc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,300 @@
+# AGENTS.md - Buildroot
+
+## Repository purpose
+
+Buildroot is a simple, efficient tool for generating embedded Linux systems
+through cross-compilation.
+
+The repository contains:
+
+- `package/`: target and host package definitions
+- `board/`: board-specific support files
+- `configs/`: predefined board configurations
+- `boot/`: bootloader and firmware support
+- `linux/`: Linux kernel integration
+- `system/`: target system configuration
+- `toolchain/`: toolchain support
+- `fs/`: root filesystem image generation
+- `support/`: infrastructure, scripts, tests, and tooling
+- `docs/`: the Buildroot user manual and website
+- `DEVELOPERS`: file ownership and maintainer notification rules
+
+Read the relevant package, board, or infrastructure documentation before
+changing its implementation.
+
+## Documentation
+
+The primary documentation is in `docs/manual/`.
+
+Useful entry points:
+
+- `docs/manual/manual.adoc`: manual index and build definition
+- `docs/manual/quickstart.adoc`: first Buildroot build
+- `docs/manual/common-usage.adoc`: common make targets and workflows
+- `docs/manual/contribute.adoc`: contribution and patch-submission process
+- `docs/manual/adding-packages.adoc`: adding packages
+- `docs/manual/adding-board-support.adoc`: adding board support
+- `docs/manual/developers.adoc`: `DEVELOPERS` and `get-developers`
+- `docs/manual/resources.adoc`: community resources and Patchwork
+- `docs/manual/prerequisite.adoc`: host requirements
+
+Generate the text manual with:
+
+```sh
+make manual-text
+```
+
+The generated text manual is written to `output/docs/manual/manual.text`.
+Online documentation is available at <https://buildroot.org/docs.html>.
+
+## Building Buildroot
+
+Build as a normal user. From the repository root:
+
+```sh
+make menuconfig
+make
+```
+
+The resulting kernel, bootloader, and root filesystem images are placed in
+`output/images/`.
+
+Useful commands include:
+
+```sh
+make list-defconfigs
+make <boardname>_defconfig
+make savedefconfig BR2_DEFCONFIG=<path>
+make source
+make legal-info
+```
+
+Use `O=<output-directory>` for an out-of-tree output directory:
+
+```sh
+make O=/path/to/output menuconfig
+make O=/path/to/output
+```
+
+Check `docs/manual/prerequisite.adoc` before diagnosing host dependency
+problems. Buildroot requires GNU make 3.81 or newer and a Linux host.
+
+Host dependency problems can be avoided by using the Buildroot Docker
+reference image, by prefixing commands with:
+
+```sh
+utils/docker-run
+```
+
+## Testing and validation
+
+Choose validation appropriate to the change:
+
+- Run `utils/check-package` on new or modified package files.
+- Prefer the containerized check for patch preparation:
+
+  ```sh
+  utils/docker-run make check-package
+  ```
+
+- Validate `DEVELOPERS` changes with:
+
+  ```sh
+  ./utils/get-developers -v
+  ```
+
+- Check the validity of Kconfig `Config.in` files with:
+
+  ```sh
+  utils/check-symbols
+  ```
+
+  This check is also run by CI in
+  <https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/support/misc/gitlab-ci.yml.in#L55>.
+
+- Build a package with several toolchain configurations using:
+
+  ```sh
+  utils/test-pkg -p <packagename>
+  ```
+
+- Build the affected defconfig, package, board, or test target.
+- Use the test infrastructure under `support/testing/` when the change
+  affects runtime behavior.
+
+Run runtime tests with:
+
+```sh
+utils/docker-run support/testing/run-tests -d dl -o output_folder <testname>
+```
+
+See the `using-the-runtime-tests-framework` section in
+<https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/docs/manual/contribute.adoc#user-content-using-the-runtime-tests-framework>.
+
+Buildroot GitLab CI can also run runtime-test jobs; see the
+`runtime-tests-and-gitlab-ci` section in
+<https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/docs/manual/contribute.adoc#user-content-runtime-tests-and-gitlab-ci>.
+
+- Generate documentation with `make manual-text` when changing the manual.
+
+Do not claim a change is tested unless the relevant command or build was run.
+
+If the public GitLab CI of the patch author is used, include the job link.
+This saves time for maintainers and provides evidence of the work. For
+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/>
+
+## Finding responsible developers
+
+`DEVELOPERS` lists developers associated with architectures, packages, boards,
+and infrastructure. Use `utils/get-developers` to identify notification
+recipients:
+
+```sh
+./utils/get-developers <patch-files>
+./utils/get-developers -e
+./utils/get-developers -c
+```
+
+When adding a new package, board, or significant functionality, update
+`DEVELOPERS` in the same patch as described in `docs/manual/developers.adoc`.
+
+## Contribution workflow
+
+Buildroot uses the mailing list for discussion, review, and patch submission.
+Patches are not submitted through the issue tracker.
+
+- Mailing list: `buildroot@buildroot.org`
+- Subscription: <https://lists.buildroot.org/mailman/listinfo/buildroot>
+- Archives: <https://lists.buildroot.org/pipermail/buildroot/>
+- Searchable archives: <https://lore.kernel.org/buildroot/>
+- Bug tracker: <https://gitlab.com/buildroot.org/buildroot/-/issues>
+- IRC: `#buildroot` on OFTC
+- Patchwork: <https://patchwork.buildroot.org/project/buildroot/list/>
+
+Read `docs/manual/contribute.adoc` before preparing a patch series.
+
+Keep patches focused and complete. Use the affected area as the commit-title
+prefix, start the description with a lowercase word, explain why the change is
+needed, and include a `Signed-off-by` line from the human contributor.
+
+Typical patch preparation:
+
+```sh
+git fetch --all --tags
+git rebase upstream/master
+utils/docker-run make check-package
+git format-patch -M -n -s -o outgoing upstream/master
+./utils/get-developers outgoing/*
+git send-email --to buildroot@buildroot.org --cc-cmd \
+  './utils/get-developers -e' upstream/master
+```
+
+Use `Tested-by`, `Reviewed-by`, and `Acked-by` only according to the meanings
+documented in `docs/manual/contribute.adoc`.
+
+## Working with Patchwork
+
+Use Patchwork to inspect, test, and apply patches submitted to the mailing
+list. Patchwork is not the submission mechanism.
+
+For an individual patch, download its mbox representation and apply it with
+`git am`:
+
+```sh
+git checkout -b test-patch
+curl --fail --location \
+  'https://patchwork.buildroot.org/project/buildroot/patch/<patch-id>/mbox/' |
+  git am
+```
+
+For a patch series, open the series listing in Patchwork and use the series
+mbox link when available. Apply the complete series in one operation:
+
+```sh
+git checkout -b test-series
+curl --fail --location '<series-mbox-url>' | git am
+```
+
+A series can also be applied by downloading each patch mbox in order, but the
+series mbox or a Patchwork bundle is preferred because it preserves ordering
+and commit metadata.
+
+Example series listing:
+
+<https://patchwork.buildroot.org/project/buildroot/list/?series=<series-id>>
+
+Example individual-patch mbox:
+
+<https://patchwork.buildroot.org/project/buildroot/patch/<patch-id>/mbox/>
+
+After applying a series, inspect the resulting commits and run validation for
+the affected area:
+
+```sh
+git log --oneline --decorate -n <number-of-patches>
+make <affected-target>
+utils/docker-run make check-package
+```
+
+Patchwork's REST API may be used for searching or inspecting patch metadata,
+but do not assume that API URLs provide an mbox download. Use the mbox link
+provided by the Patchwork interface for applying patches, and verify the
+downloaded content before running `git am`.
+
+## AI-assisted contributions
+
+AI tools may assist with code, documentation, analysis, and other meaningful
+content.
+
+When AI-assisted work is committed or prepared for submission, follow the
+commit-message and patch-formatting requirements in
+[`docs/manual/contribute.adoc`](docs/manual/contribute.adoc#submitting-patches),
+including the subject and body wrapping rules, required trailers, and human
+sign-off.
+
+Meaningful AI-generated content must be attributed with an `Assisted-by` trailer
+in the commit message:
+
+    Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+
+Trivial completions, spelling corrections, and common boilerplate do not require
+attribution. For substantial AI-generated content, summarize the relevant
+prompts or session context in the commit message or patch description.
+
+AI tools must not add `Signed-off-by` trailers. The human contributor must:
+
+- review and understand all AI-assisted changes;
+- run and assess appropriate validation;
+- verify licensing and provenance;
+- add their own `Signed-off-by` trailer;
+- take responsibility for the submitted contribution.
+
+AI-assisted changes must not introduce license-incompatible material. Generated
+content must be checked for factual correctness, appropriate attribution, and
+compatibility with Buildroot and any affected package's license.
+
+AI-generated content should receive review proportional to its significance and
+the degree of AI involvement. Do not submit generated output without human
+understanding and validation.
+
+AI tools must not invoke `git send-email`, upload patches, or otherwise submit
+patches on the contributor's behalf. When a patch is ready to submit, present
+the proposed command sequence, including `git format-patch`,
+`utils/get-developers`, and `git send-email`, for the contributor to review and
+run themselves. Do not execute the sending or submission command.
+
+AI tools must not autonomously commit or push changes without explicit human
+review and direction.
+
+### Local agent behavior
+
+Keep changes narrowly scoped to the requested behavior. Follow existing
+Buildroot conventions and documentation. Preserve unrelated user changes.
+Do not create commits or branches unless explicitly requested.
+
+### Further reading
+
+- [Linux Foundation Generative AI Policy](https://www.linuxfoundation.org/legal/generative-ai)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
-- 
2.39.5

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

^ permalink raw reply related	[flat|nested] 4+ messages in thread