From 538ac1aaf7e781a8e60639c19712d8a219e82eff Mon Sep 17 00:00:00 2001 From: user01010111 Date: Tue, 1 Sep 2026 14:14:01 +1200 Subject: [PATCH 1/3] docs: add instructions for coding agents Add a root AGENTS.md which directs coding agents to existing NUT contribution requirements and recurring project-specific review checks. Tell contributors using coding agents to ensure their tool reads the file, and register it for source distribution. AI assistance: OpenAI Codex gpt-5.6-sol was used for research, drafting and review. The human contributor remains responsible for the change. Signed-off-by: user01010111 --- AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- docs/developers.txt | 2 ++ 3 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..f1195daab5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Instructions for coding agents + +These instructions apply throughout the Network UPS Tools (NUT) repository. They supplement, but do not replace, the project's authoritative guidance. + +## Read the project guidance + +Before proposing a change, read the parts relevant to it: + +- `docs/developers.txt` for coding style, portability, build and contribution requirements. +- `docs/developer-guide.txt` for NUT architecture, design and data flow. +- `.github/pull_request_template.md` for the current contribution checklist. +- `SECURITY.md` before investigating or reporting a possible vulnerability. + +Follow more specific guidance in those files if this summary differs from it. + +## Work from evidence + +- Verify claims against the current source and applicable specifications, consulting relevant history where needed. Trace affected callers, consumers and data flow, then change the layer which owns the behaviour. +- Reuse established NUT helpers, types, probes and patterns before adding new code. Check nearby code for applicable precedent. + +## Keep changes focused and portable + +- Keep each change narrow and cohesive. Exclude unrelated cleanup, formatting and speculative refactoring. +- Follow affected-file style and the portability requirements in `docs/developers.txt`, including plain ASCII in source comments and AsciiDoc where ASCII suffices. +- When adding, removing or renaming files, or changing templates, update the applicable `Makefile.am`, `configure.ac`, distribution lists and generation rules. Update source templates rather than generated files unless project practice requires a generated artefact to be tracked. +- Update manuals, compatibility data, version markers, `NEWS.adoc`, `UPGRADING.adoc` and acknowledgements only where required by the affected change. + +## Validate the affected behaviour + +- Run affected tests and builds, and run `make distcheck-light` before upstreaming. Include relevant documentation and distribution checks when their inputs or metadata change. +- Report expected compatibility, what was actually tested, material failures and untested limitations. Do not claim hardware, platform or runtime acceptance from CI jobs which did not exercise it. +- Diagnose the first relevant CI failure before changing code, distinguishing the proposed change from baseline or CI-environment failures. + +## Preserve human responsibility + +- A human contributor must review and take responsibility for every proposed change and for the right to submit it under the project's licence. +- Do not add a `Signed-off-by` trailer on the contributor's behalf. The human contributor must consciously provide the required DCO sign-off for each commit. +- Disclose AI or coding-helper use as required by the current pull-request template, identifying the exact tool and model actually used where available. This does not prescribe a tool or model and does not replace human review. diff --git a/Makefile.am b/Makefile.am index ae7a3c9cd4..6ef2914483 100644 --- a/Makefile.am +++ b/Makefile.am @@ -260,7 +260,7 @@ libtool: $(LIBTOOL_DEPS) # by automake. Note that the INSTALL file is (re-)imposed by autotools # runs and is essentially a manual on configure script general usage, so # NUT's actual installation notes have had to use a different filename. -EXTRA_DIST = LICENSE-GPL2 LICENSE-GPL3 LICENSE-DCO MAINTAINERS +EXTRA_DIST = AGENTS.md LICENSE-GPL2 LICENSE-GPL3 LICENSE-DCO MAINTAINERS # Since the renaming of documentation to `*.adoc` extension to help IDE # and GitHub UIs to render the source files in a pretty fashion, we need diff --git a/docs/developers.txt b/docs/developers.txt index 56f012973b..0c12379f4a 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -4,6 +4,8 @@ Information for developers This document is intended to explain some of the more useful things within the tree, and provide a standard for working on the code. +NOTE: Contributors using a coding agent should ensure it reads `AGENTS.md` in the repository root. Tools which do not detect that file automatically should be pointed to it explicitly. + General stuff -- common subdirectory ------------------------------------ From c16df8cc7340bc1232c4f45a72b1cca71a492aff Mon Sep 17 00:00:00 2001 From: user01010111 Date: Tue, 1 Sep 2026 14:29:27 +1200 Subject: [PATCH 2/3] docs: wrap agent guidance source lines Wrap agent guidance source lines consistently with existing NUT documentation while preserving the rendered text. AI assistance: OpenAI Codex gpt-5.6-sol was used for drafting and validation. The human contributor remains responsible for the change. Signed-off-by: user01010111 --- AGENTS.md | 52 +++++++++++++++++++++++++++++++++------------ docs/developers.txt | 4 +++- 2 files changed, 41 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f1195daab5..46d606fd92 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,14 @@ # Instructions for coding agents -These instructions apply throughout the Network UPS Tools (NUT) repository. They supplement, but do not replace, the project's authoritative guidance. +These instructions apply throughout the Network UPS Tools (NUT) repository. +They supplement, but do not replace, the project's authoritative guidance. ## Read the project guidance Before proposing a change, read the parts relevant to it: -- `docs/developers.txt` for coding style, portability, build and contribution requirements. +- `docs/developers.txt` for coding style, portability, build and contribution + requirements. - `docs/developer-guide.txt` for NUT architecture, design and data flow. - `.github/pull_request_template.md` for the current contribution checklist. - `SECURITY.md` before investigating or reporting a possible vulnerability. @@ -15,24 +17,46 @@ Follow more specific guidance in those files if this summary differs from it. ## Work from evidence -- Verify claims against the current source and applicable specifications, consulting relevant history where needed. Trace affected callers, consumers and data flow, then change the layer which owns the behaviour. -- Reuse established NUT helpers, types, probes and patterns before adding new code. Check nearby code for applicable precedent. +- Verify claims against the current source and applicable specifications, + consulting relevant history where needed. Trace affected callers, consumers + and data flow, then change the layer which owns the behaviour. +- Reuse established NUT helpers, types, probes and patterns before adding new + code. Check nearby code for applicable precedent. ## Keep changes focused and portable -- Keep each change narrow and cohesive. Exclude unrelated cleanup, formatting and speculative refactoring. -- Follow affected-file style and the portability requirements in `docs/developers.txt`, including plain ASCII in source comments and AsciiDoc where ASCII suffices. -- When adding, removing or renaming files, or changing templates, update the applicable `Makefile.am`, `configure.ac`, distribution lists and generation rules. Update source templates rather than generated files unless project practice requires a generated artefact to be tracked. -- Update manuals, compatibility data, version markers, `NEWS.adoc`, `UPGRADING.adoc` and acknowledgements only where required by the affected change. +- Keep each change narrow and cohesive. Exclude unrelated cleanup, formatting + and speculative refactoring. +- Follow affected-file style and the portability requirements in + `docs/developers.txt`, including plain ASCII in source comments and AsciiDoc + where ASCII suffices. +- When adding, removing or renaming files, or changing templates, update the + applicable `Makefile.am`, `configure.ac`, distribution lists and generation + rules. Update source templates rather than generated files unless project + practice requires a generated artefact to be tracked. +- Update manuals, compatibility data, version markers, `NEWS.adoc`, + `UPGRADING.adoc` and acknowledgements only where required by the affected + change. ## Validate the affected behaviour -- Run affected tests and builds, and run `make distcheck-light` before upstreaming. Include relevant documentation and distribution checks when their inputs or metadata change. -- Report expected compatibility, what was actually tested, material failures and untested limitations. Do not claim hardware, platform or runtime acceptance from CI jobs which did not exercise it. -- Diagnose the first relevant CI failure before changing code, distinguishing the proposed change from baseline or CI-environment failures. +- Run affected tests and builds, and run `make distcheck-light` before + upstreaming. Include relevant documentation and distribution checks when + their inputs or metadata change. +- Report expected compatibility, what was actually tested, material failures + and untested limitations. Do not claim hardware, platform or runtime + acceptance from CI jobs which did not exercise it. +- Diagnose the first relevant CI failure before changing code, distinguishing + the proposed change from baseline or CI-environment failures. ## Preserve human responsibility -- A human contributor must review and take responsibility for every proposed change and for the right to submit it under the project's licence. -- Do not add a `Signed-off-by` trailer on the contributor's behalf. The human contributor must consciously provide the required DCO sign-off for each commit. -- Disclose AI or coding-helper use as required by the current pull-request template, identifying the exact tool and model actually used where available. This does not prescribe a tool or model and does not replace human review. +- A human contributor must review and take responsibility for every proposed + change and for the right to submit it under the project's licence. +- Do not add a `Signed-off-by` trailer on the contributor's behalf. The human + contributor must consciously provide the required DCO sign-off for each + commit. +- Disclose AI or coding-helper use as required by the current pull-request + template, identifying the exact tool and model actually used where + available. This does not prescribe a tool or model and does not replace + human review. diff --git a/docs/developers.txt b/docs/developers.txt index 0c12379f4a..74d6d7ea10 100644 --- a/docs/developers.txt +++ b/docs/developers.txt @@ -4,7 +4,9 @@ Information for developers This document is intended to explain some of the more useful things within the tree, and provide a standard for working on the code. -NOTE: Contributors using a coding agent should ensure it reads `AGENTS.md` in the repository root. Tools which do not detect that file automatically should be pointed to it explicitly. +NOTE: Contributors using a coding agent should ensure it reads `AGENTS.md` in +the repository root. Tools which do not detect that file automatically should +be pointed to it explicitly. General stuff -- common subdirectory ------------------------------------ From 9d65221cd555b997aeb7fd18e6bc1f7f5f9b19e4 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 1 Sep 2026 09:51:14 +0200 Subject: [PATCH 3/3] NEWS.adoc: mention new AGENTS.md and SECURITY.md [#3470, #3608] Signed-off-by: Jim Klimov --- NEWS.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS.adoc b/NEWS.adoc index 8da073ce8e..daa27a08a6 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -471,6 +471,10 @@ https://github.com/networkupstools/nut/milestone/13 with insecure start-up like it could do before). [issue #3331, PR #3435] - Recipes, CI and helper script updates not classified above: + * Introduced `AGENTS.md` for AI agents to help in a consistent manner with + minimal friction. [#3608] + * Introduced `SECURITY.md` for rules about responsible disclosure of + potentially exploitable bugs. [#3470] * Introduced `ci_build.sh` settings and respective CI workflow settings to optionally re-use a `config.cache` file from older runs, and similar logic for NIT `nit.sh` to re-use generated certificate and private key