From fdf7f5790fd2ec9e52b99f9764991cab7a6d7c87 Mon Sep 17 00:00:00 2001 From: Gleb Chesnokov Date: Sun, 18 Oct 2026 13:01:27 +0300 Subject: [PATCH] docs: Describe script ownership and invocation boundaries Add a directory map with Make entry points and explain the preserved working-directory conventions. Identify the current checkpatch ignore and scan policies and the separate kernel regression analyzer path. Record the caller updates required when moving helpers and the scope of make shellcheck. Describe the side effects of cleanup, release and runtime tools. --- scripts/AGENTS.md | 17 +++++++++++++++++ scripts/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 scripts/AGENTS.md create mode 100644 scripts/README.md diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 000000000..ee6d1c5dc --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,17 @@ +# Repository tooling + +[README.md](README.md) describes the directories and entry points. Follow the +root guidance and any nested instructions, including [KUnit tooling](kunit/AGENTS.md). + +- Keep a moved helper and all its callers, Make targets, CI jobs, packaging + references, tests, and documentation in the same commit. +- Resolve shared helper paths relative to the owning script. For sourced + Bash libraries use `BASH_SOURCE` when the caller can live elsewhere. +- Preserve intentional caller-directory semantics for source selection, + archive contents, patch generation, and module signing. +- Keep path reorganizations separate from changes to analyzer coverage, + diagnostic filtering, kernel support, or runtime behavior. Document policy + changes explicitly in their own commits. +- Inspect side effects before running a helper. Syntax checks and lint do not + authorize cleanup, downloads, builds, signing, deployment, or live-device + exercises; use the root safety boundaries and the requested task scope. diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 000000000..317d0c576 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,45 @@ +# Repository scripts + +The tools are grouped by purpose. Existing Make targets keep their names; +direct callers of a relocated script must use its new directory below. + +| Directory | Tools and entry points | +| --- | --- | +| `source/` | `list-source-files`, `list-non-source-files`, `clean-source-tree`, `list-double-blank-lines`, and `run-shellcheck` (`make shellcheck`). | +| `kernel/` | `generate-kernel-patch`, `generate-patched-kernel`, `run-regression-tests`, `kernel-matrix`, `sign-modules`, patch filters, and shared kernel/RPM helpers. | +| `release/` | `generate-release-archive` (`make release-archive`), `build-rpm-artifacts` (`make rpm-artifacts`), `prepare-package-release`, and `update-version`. | +| `runtime/` | `monitor-interrupt-rate`, `monitor-memory-usage`, `blockdev-perftest`, and `test-persistent-reservation`. | +| `ci/` | CI image and guest preparation, VM execution, and associated configuration. | +| `kunit/` | KUnit inventory, labels, runner, and tooling tests; see [the KUnit guide](../doc/KUNIT.md). | + +The existing `checkpatch`, `checkpatch_commits`, `checkpatch_diff`, and +`checkpatch_scan` entry points remain directly under `scripts/`. The wrapper's +diagnostic ignore list is in `checkpatch`; whole-tree scan exclusions are in +`checkpatch_scan`. The kernel regression runner retains its separate analyzer +commands and filtering. Moving the tools does not change these policies. + +Use Make targets from the repository root unless a component workflow says +otherwise. Direct scripts retain their working-directory conventions: +`generate-kernel-patch` and `update-version` use the SCST root, while archive +generation and source inventory use the requested or current source directory. +Module Makefiles invoke `sign-modules` from the directory containing modules. +Consult each script's argument handling before invoking it. + +`kernel/run-regression-tests` prepares kernel trees and runs compilation, +checkpatch, sparse, and smatch according to its options. The maintained kernel +matrix is `ABT_KERNELS` in `nightly/conf/nightly.conf`; the CI subset is selected +through `kernel/kernel-matrix` and `.github/kernel-matrix.conf`. + +Some helpers modify source trees, generated artifacts, or live devices: +`source/clean-source-tree` removes untracked and ignored files; kernel helpers +can download, patch, build, or sign; release helpers can update versions or +write packages. Runtime benchmarks and reservation exercises require a +deliberately selected disposable device. The runtime monitors only observe +host counters. See the root [repository guidance](../AGENTS.md) for operational +boundaries. + +Follow [the local checks](../CONTRIBUTING.md#local-checks) when editing tools. +`make shellcheck` selects Bash scripts under all of `scripts/` using paths +recorded in `HEAD`. Check newly added or renamed paths explicitly before +committing; sourced libraries, POSIX shell scripts, and callers outside +`scripts/` also need the checks described there.