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

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

[Matthew Weber]

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

This specific file was added as most AI will look for it.

Assisted-by: GitHub Copilot
Signed-off-by: Matthew Weber <matt@thewebers.ws>

---

v1 -> v2 : I messed up the additional info section and patchwork didn't
           pick the series up

This is modeled after similar work I did on another project. I
tried to keep this simple to start and there are more refs in the
pull request. https://github.com/elisa-tech/wg-aerospace/pull/234/changes

 AGENTS.md | 257 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 257 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..e05c87f4fc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,257 @@
+# 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.
+
+## 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
+  ```
+
+- Build the affected defconfig, package, board, or test target.
+- Use the test infrastructure under `support/testing/` when the change
+  affects runtime behavior.
+- 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.
+
+## 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.ozlabs.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.ozlabs.org/project/buildroot/list/?series=<series-id>>
+
+Example individual-patch mbox:
+
+<https://patchwork.ozlabs.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)
-- 
2.39.5

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

Re: [Buildroot] [PATCH v2 1/1] docs: add agent guidance

[Yegor Yefremov via buildroot]

Hi Matthew, all,

On Wed, Sep 9, 2026 at 2:44 PM Matthew Weber <matt@thewebers.ws> wrote:
>
> Document Buildroot structure, documentation, build and validation
> workflows, mailing-list submission, Patchwork usage, and AI-assisted
> contribution requirements.
>
> This specific file was added as most AI will look for it.

What about also adding CLAUDE.md with the following content:

@AGENTS.md

Otherwise, Claude Code won't include this file automatically.

Regards,
Yegor

> Assisted-by: GitHub Copilot
> Signed-off-by: Matthew Weber <matt@thewebers.ws>
>
> ---
>
> v1 -> v2 : I messed up the additional info section and patchwork didn't
>            pick the series up
>
> This is modeled after similar work I did on another project. I
> tried to keep this simple to start and there are more refs in the
> pull request. https://github.com/elisa-tech/wg-aerospace/pull/234/changes
>
>  AGENTS.md | 257 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 257 insertions(+)
>  create mode 100644 AGENTS.md
>
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 0000000000..e05c87f4fc
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,257 @@
> +# 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.
> +
> +## 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
> +  ```
> +
> +- Build the affected defconfig, package, board, or test target.
> +- Use the test infrastructure under `support/testing/` when the change
> +  affects runtime behavior.
> +- 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.
> +
> +## 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.ozlabs.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.ozlabs.org/project/buildroot/list/?series=<series-id>>
> +
> +Example individual-patch mbox:
> +
> +<https://patchwork.ozlabs.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)
> --
> 2.39.5
>
> _______________________________________________
> buildroot mailing list
> buildroot@buildroot.org
> https://lists.buildroot.org/mailman/listinfo/buildroot
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH v2 1/1] docs: add agent guidance

[Julien Olivain via buildroot]

Hi Matthew,

Thanks for this proposal. I have few comments and suggestions, see 
below.

On 09/09/2026 14:43, Matthew Weber wrote:
> Document Buildroot structure, documentation, build and validation
> workflows, mailing-list submission, Patchwork usage, and AI-assisted
> contribution requirements.
> 
> This specific file was added as most AI will look for it.
> 
> Assisted-by: GitHub Copilot
> Signed-off-by: Matthew Weber <matt@thewebers.ws>
> 
> ---
> 
> v1 -> v2 : I messed up the additional info section and patchwork didn't
>            pick the series up
> 
> This is modeled after similar work I did on another project. I
> tried to keep this simple to start and there are more refs in the
> pull request. 
> https://github.com/elisa-tech/wg-aerospace/pull/234/changes
> 
>  AGENTS.md | 257 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 257 insertions(+)
>  create mode 100644 AGENTS.md
> 
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 0000000000..e05c87f4fc
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,257 @@
> +# 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.

We could also mention that the docker-run script is here to provide a
reference build host environment. For ex:

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
> +  ```

The check-symbols script could be cited here. For ex:

Check the validity of Kconfig Config.in files with:

```sh
utils/check-symbols
```

It is used by the CI here:
https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/support/misc/gitlab-ci.yml.in#L55
It is useful to catch typos or undefined symbols in Kconfig files.
(and yes, this script is not appearing in the Buildroot
documentation at the moment, it could also be added).

> +
> +- Build the affected defconfig, package, board, or test target.

Package can be build tested locally for several toolchain configuration 
with:

```sh
utils/test-pkg -p <packagename>
```

Alternatively,  there is also the Gitlab CI of the patch author account 
which can be used. See:
https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/docs/manual/contribute.adoc#user-content-runtime-tests-and-gitlab-ci

> +- Use the test infrastructure under `support/testing/` when the change
> +  affects runtime behavior.

Maybe we should mention here the command to run tests is:
```sh
utils/docker-run support/testing/run-tests -d dl -o output_folder 
[testname ...]
```

See:
https://gitlab.com/buildroot.org/buildroot/-/blob/2026.08/docs/manual/contribute.adoc#user-content-using-the-runtime-tests-framework

What do you think?

> +- 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, the job link can be
provided. See 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/
Doing so saves time to maintainers and it is also a good proof of work.

> +
> +## 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.ozlabs.org/project/buildroot/patch/<patch-id>/mbox/' 
> |

The patchwork instance at https://patchwork.ozlabs.org/ is no
longer used and was replace recently. See:
https://gitlab.com/buildroot.org/buildroot/-/commit/2d7d9d8200232bce215d87cadda443ba74308f01

Could you point all patchwork URLs to
https://patchwork.buildroot.org/project/buildroot/
please?

> +  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.ozlabs.org/project/buildroot/list/?series=<series-id>>

Also update here to:
https://patchwork.buildroot.org/project/buildroot/

> +
> +Example individual-patch mbox:
> +
> +<https://patchwork.ozlabs.org/project/buildroot/patch/<patch-id>/mbox/>

Also update here to:
https://patchwork.buildroot.org/project/buildroot/

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

Best regards,

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