From 8801ad06660bcca4eb3aaf1871df254f58c2dddc Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Mon, 3 Aug 2026 20:47:48 -0300 Subject: [PATCH 1/3] [docs] Harmonized AGENTS.md with @openwisp guidelines Aligned this repository's AGENTS.md with @openwisp contributing guidelines and its technology-family conventions. Removed redundant generic instructions while preserving repository-specific requirements, commands, and safety guidance. --- AGENTS.md | 22 +++++++++++++++++----- requirements-test.txt | 2 +- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cb34d45..534ba76 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,27 +22,39 @@ If instructions conflict, repository config and CI workflows win first, docs nex ## Development Notes -- Keep changes focused. Avoid unrelated refactors and formatting churn. - Preserve public APIs, parser outputs, graph comparison semantics, and supported input formats unless explicitly required. - Place imports at the top of the file. Only defer imports when necessary (e.g., Django model imports inside functions or methods where the app registry is not yet ready). - Avoid unnecessary blank lines inside function and method bodies. +- Prefer short, precise names that rely on their nearest meaningful scope. Do not repeat a feature, domain object, or namespace already named by the containing module, class, or function. For example, prefer `EstimatedLocation.refresh()` over `EstimatedLocation.refresh_estimated_location()`. Repeat that context only when the name is used outside that scope or is needed to distinguish genuinely different concepts. When a concise name cannot express a necessary distinction, use a concise docstring to describe it rather than encoding it in an excessively long name. +- Before adding a comment or docstring, ask whether it conveys information a reader cannot reasonably infer from clear code, names, and surrounding scope. Add a concise comment when it explains a non-obvious reason, constraint, compatibility or security requirement, side effect, or unavoidable complexity. In opaque syntax or domain-specific code, especially shell scripts, a comment may also explain what the code does. Do not add comments that merely restate adjacent code one-to-one. - Update docs when behavior, settings, public APIs, setup steps, or supported versions change. ## Testing and QA -- Add or update tests for every behavior change. - For bug fixes, write the regression test first, run it against the unfixed code, confirm it fails for the expected reason, then implement the fix. +- When separate tests cover different cases of the same feature, share almost identical setup, and primarily vary in input or expected outcome, group them in one test method with subTest. Keep each subtest's setup explicit and independent, and retain separate test methods when cases exercise genuinely distinct behavior. Leave one blank line immediately before each with self.subTest(...): call. +- Prefer method decorators for context managers that apply to the entire test method and would otherwise create unnecessary nesting, unless decorator ordering conflicts or the context manager requires data unavailable when the method is defined. - Use targeted tests while iterating, then run the documented full test command before considering the change complete. - Run `openwisp-qa-format` after editing when available. -- Run `./run-qa-checks` when present. Treat failures as blocking unless confirmed unrelated and reported. - Prefer in-process tests so coverage tools can measure changed code. ## Security Notes - Watch for malformed parser input, unsafe file paths, excessive parsing costs, and secrets in fixtures or logs. - Preserve validation around topology formats, node/link attributes, parser errors, and graph diff output. -- Write comments and docstrings only when they explain why code is shaped a certain way. Put comments before the relevant code block instead of scattering them inside it. ## Troubleshooting -- If setup, QA, or tests fail, check docs first, then compare with CI. If commands diverge, follow CI. +- If documentation and CI commands differ, use CI for verification and report the exact documentation path, CI workflow path, and differing commands. Do not change the documentation until the user explicitly chooses one of these actions: update the named documentation file in the current change because the divergence was caused by that change, or leave it unchanged for a separate follow-up. Never decide that scope distinction independently. + +## Contributing Guidelines + +- Before editing, inspect the relevant implementation, tests, documentation, and configuration. Follow existing repository patterns and do not invent behavior or requirements. +- Keep each contribution focused and change only the lines necessary for its goal. Do not include unrelated refactors, formatting churn, or generated and dependency-file changes unless explicitly required. +- Add or update focused tests for every behavior change. In repositories without a dedicated automated test suite, use the documented build and QA workflow as the equivalent behavior verification. For bug fixes, first reproduce the failure with a regression test when the repository's test setup allows it. +- Run the relevant targeted tests, builds, and documented QA checks, including `./run-qa-checks` when provided. Do not claim a change is complete when verification fails; report the failure or blocker. +- When requirements, intended behavior, or an unexpected failure are unclear, stop and seek clarification instead of making speculative changes. +- When starting work on a new issue, create a new branch from `master`. Use `issues/-` for issue work; otherwise, use a short, descriptive branch name. +- Commit messages must be descriptive and use past tense. Past tense is a writing guideline that agents and contributors must follow; it is not checked automatically. For issue work, use an allowed prefix and a capitalized, past-tense subject ending with `#`, for example `[fix] Fixed perennial "modified" state #213`. Repeat the issue reference in the body with `Fixes`, `Closes`, `Resolves`, or `Related to` as appropriate. Use `openwisp-commit --check` to validate the structural commit convention and `cz -n cz_openwisp info` to view the allowed prefixes and message structure. If the repository's declared QA dependency predates these commands, install the development version with `pip install --upgrade "openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/archive/refs/heads/master.tar.gz"` in the development environment. +- Add an explanatory commit body only for substantial changes, new features, or non-obvious bug fixes. The releaser automatically publishes the subject of `[feature]`, `[change]`, `[change!]`, `[deps]`, and `[fix]` commits, including scoped variants, in the changelog. Write those subjects in clear, user-friendly language suitable for release notes. +- Send new commits in response to review feedback instead of amending existing commits. diff --git a/requirements-test.txt b/requirements-test.txt index 855ac73..4ead416 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,5 +1,5 @@ nose2[coverage_plugin]>=0.16.0 responses~=0.26.1 -openwisp-utils[qa]~=1.2.2 +openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/archive/refs/heads/master.tar.gz parameterized~=0.9.0 freezegun==1.5.5 From 51c2534d490b6d6d685ca08817b8455a61e550d5 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Tue, 4 Aug 2026 16:05:20 -0300 Subject: [PATCH 2/3] [docs] Refined testing guidance in AGENTS.md [skip ci] --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 534ba76..dee9dbe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ If instructions conflict, repository config and CI workflows win first, docs nex - Before editing, inspect the relevant implementation, tests, documentation, and configuration. Follow existing repository patterns and do not invent behavior or requirements. - Keep each contribution focused and change only the lines necessary for its goal. Do not include unrelated refactors, formatting churn, or generated and dependency-file changes unless explicitly required. -- Add or update focused tests for every behavior change. In repositories without a dedicated automated test suite, use the documented build and QA workflow as the equivalent behavior verification. For bug fixes, first reproduce the failure with a regression test when the repository's test setup allows it. +- Add or update focused tests for every behavior change. For bug fixes, follow the regression-test rule above. - Run the relevant targeted tests, builds, and documented QA checks, including `./run-qa-checks` when provided. Do not claim a change is complete when verification fails; report the failure or blocker. - When requirements, intended behavior, or an unexpected failure are unclear, stop and seek clarification instead of making speculative changes. - When starting work on a new issue, create a new branch from `master`. Use `issues/-` for issue work; otherwise, use a short, descriptive branch name. From 5f8244e64a81a1bd1306e4619da09cb983acffb5 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Tue, 4 Aug 2026 17:51:35 -0300 Subject: [PATCH 3/3] [docs] Further improvements to AGENTS.md - Listed "Contributing Guidelines" rules early on, some rules have been adapted to this repository to avoid ambiguity. - Ensured following rules do not repeat nor contradict the rules listed in "Contributing Guideliens". --- AGENTS.md | 29 ++++++++++++++--------------- requirements-test.txt | 2 +- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dee9dbe..5453c33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,19 @@ Follow the DRY principle: do not duplicate information or code across files. If instructions conflict, repository config and CI workflows win first, docs next, and this file is supplemental. +## Contributing Guidelines + +- Before editing, inspect the relevant implementation, tests, documentation, and configuration. Follow existing repository patterns and do not invent behavior or requirements. +- Keep each contribution focused and change only the lines necessary for its goal. Do not include unrelated refactors, formatting churn, or generated and dependency-file changes unless explicitly required. +- Add or update focused tests for every behavior change. Use test-driven development when the scope is very clear, such as bug fixes or narrowly scoped changes. For new features, tests may be added after implementation, but confirm they fail when key feature code is removed. When a test failure does not clearly state the expected outcome that was not met, add an explicit assertion message. +- Run `openwisp-qa-format` after each change when available. +- Run the relevant targeted tests, builds, and documented QA checks, including `./run-qa-checks` when provided. Do not claim a change is complete when verification fails; report the failure or blocker. +- When requirements, intended behavior, or an unexpected failure are unclear, stop and seek clarification instead of making speculative changes. +- When starting work on a new issue, create a new branch from `master`. Use `issues/-` for issue work; otherwise, use a short, descriptive branch name. +- Commit messages must be descriptive and use past tense. Past tense is a writing guideline that agents and contributors must follow; it is not checked automatically. For issue work, use an allowed prefix and a capitalized, past-tense subject ending with `#`, for example `[fix] Fixed perennial "modified" state #213`. Repeat the issue reference in the body with `Fixes`, `Closes`, `Resolves`, or `Related to` as appropriate. Use `openwisp-commit --check` to validate the structural commit convention and `cz -n cz_openwisp info` to view the allowed prefixes and message structure. +- Add an explanatory commit body only for substantial changes, new features, or non-obvious bug fixes. The releaser automatically publishes the subject of `[feature]`, `[change]`, `[change!]`, `[deps]`, and `[fix]` commits, including scoped variants, in the changelog. Write those subjects in clear, user-friendly language suitable for release notes. +- Send new commits in response to review feedback instead of amending existing commits. + ## Development Notes - Preserve public APIs, parser outputs, graph comparison semantics, and supported input formats unless explicitly required. @@ -27,15 +40,13 @@ If instructions conflict, repository config and CI workflows win first, docs nex - Avoid unnecessary blank lines inside function and method bodies. - Prefer short, precise names that rely on their nearest meaningful scope. Do not repeat a feature, domain object, or namespace already named by the containing module, class, or function. For example, prefer `EstimatedLocation.refresh()` over `EstimatedLocation.refresh_estimated_location()`. Repeat that context only when the name is used outside that scope or is needed to distinguish genuinely different concepts. When a concise name cannot express a necessary distinction, use a concise docstring to describe it rather than encoding it in an excessively long name. - Before adding a comment or docstring, ask whether it conveys information a reader cannot reasonably infer from clear code, names, and surrounding scope. Add a concise comment when it explains a non-obvious reason, constraint, compatibility or security requirement, side effect, or unavoidable complexity. In opaque syntax or domain-specific code, especially shell scripts, a comment may also explain what the code does. Do not add comments that merely restate adjacent code one-to-one. -- Update docs when behavior, settings, public APIs, setup steps, or supported versions change. +- Update docs when behavior, settings, public APIs, setup steps, or supported versions change, including when a documented feature's behavior changes or a new user-facing feature is added. ## Testing and QA -- For bug fixes, write the regression test first, run it against the unfixed code, confirm it fails for the expected reason, then implement the fix. - When separate tests cover different cases of the same feature, share almost identical setup, and primarily vary in input or expected outcome, group them in one test method with subTest. Keep each subtest's setup explicit and independent, and retain separate test methods when cases exercise genuinely distinct behavior. Leave one blank line immediately before each with self.subTest(...): call. - Prefer method decorators for context managers that apply to the entire test method and would otherwise create unnecessary nesting, unless decorator ordering conflicts or the context manager requires data unavailable when the method is defined. - Use targeted tests while iterating, then run the documented full test command before considering the change complete. -- Run `openwisp-qa-format` after editing when available. - Prefer in-process tests so coverage tools can measure changed code. ## Security Notes @@ -46,15 +57,3 @@ If instructions conflict, repository config and CI workflows win first, docs nex ## Troubleshooting - If documentation and CI commands differ, use CI for verification and report the exact documentation path, CI workflow path, and differing commands. Do not change the documentation until the user explicitly chooses one of these actions: update the named documentation file in the current change because the divergence was caused by that change, or leave it unchanged for a separate follow-up. Never decide that scope distinction independently. - -## Contributing Guidelines - -- Before editing, inspect the relevant implementation, tests, documentation, and configuration. Follow existing repository patterns and do not invent behavior or requirements. -- Keep each contribution focused and change only the lines necessary for its goal. Do not include unrelated refactors, formatting churn, or generated and dependency-file changes unless explicitly required. -- Add or update focused tests for every behavior change. For bug fixes, follow the regression-test rule above. -- Run the relevant targeted tests, builds, and documented QA checks, including `./run-qa-checks` when provided. Do not claim a change is complete when verification fails; report the failure or blocker. -- When requirements, intended behavior, or an unexpected failure are unclear, stop and seek clarification instead of making speculative changes. -- When starting work on a new issue, create a new branch from `master`. Use `issues/-` for issue work; otherwise, use a short, descriptive branch name. -- Commit messages must be descriptive and use past tense. Past tense is a writing guideline that agents and contributors must follow; it is not checked automatically. For issue work, use an allowed prefix and a capitalized, past-tense subject ending with `#`, for example `[fix] Fixed perennial "modified" state #213`. Repeat the issue reference in the body with `Fixes`, `Closes`, `Resolves`, or `Related to` as appropriate. Use `openwisp-commit --check` to validate the structural commit convention and `cz -n cz_openwisp info` to view the allowed prefixes and message structure. If the repository's declared QA dependency predates these commands, install the development version with `pip install --upgrade "openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/archive/refs/heads/master.tar.gz"` in the development environment. -- Add an explanatory commit body only for substantial changes, new features, or non-obvious bug fixes. The releaser automatically publishes the subject of `[feature]`, `[change]`, `[change!]`, `[deps]`, and `[fix]` commits, including scoped variants, in the changelog. Write those subjects in clear, user-friendly language suitable for release notes. -- Send new commits in response to review feedback instead of amending existing commits. diff --git a/requirements-test.txt b/requirements-test.txt index 4ead416..b26f296 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,5 +1,5 @@ nose2[coverage_plugin]>=0.16.0 responses~=0.26.1 -openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/archive/refs/heads/master.tar.gz +openwisp-utils[qa] @ https://github.com/openwisp/openwisp-utils/archive/refs/heads/1.3.tar.gz parameterized~=0.9.0 freezegun==1.5.5