diff --git a/.conform.yaml b/.conform.yaml new file mode 100644 index 000000000..d5d9119d0 --- /dev/null +++ b/.conform.yaml @@ -0,0 +1,9 @@ +# Kernel-style subjects; SCST prefixes are documented in CONTRIBUTING.md. +# Do not enable Conventional Commits or case/imperative checks on the prefix. +policies: + - type: commit + spec: + header: + length: 75 + invalidLastCharacters: "." + dco: false diff --git a/AGENTS.md b/AGENTS.md index 2b9f5af7f..58f1ca321 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,18 +125,41 @@ the public certificate is an enrollment input. ## Validation +- Follow [CONTRIBUTING.md](CONTRIBUTING.md) for code style and commit + conventions. Before handoff, inspect the final diff and run the applicable + checks below from the repository root. Use the resolved base commit of the + submitted series as ``; do not silently substitute a moving branch. + + | Change | Required local checks | + | --- | --- | + | Any change | `git diff --check `; inspect added files too, including files not yet tracked. | + | Prepared commits | `scripts/checkpatch_commits `; run Conform as described in `CONTRIBUTING.md` and review prefixes against its registry. | + | Uncommitted C changes | `scripts/checkpatch_diff `. Rerun the per-commit checks once the series is prepared. | + | Shell scripts or sourced shell files | ShellCheck and syntax checks as described below. | + | Python files | `python3 -m py_compile `. | + | Go files | `gofmt -l ` must produce no output; follow component validation guidance. | + +- For changed Bash files, run `bash -n ` for each file and + `shellcheck -x -P SCRIPTDIR `. For POSIX shell files, use + `sh -n` and ShellCheck's `sh` dialect. Check sourced files with the caller's + dialect if they have no shebang. Include new files and files outside + `scripts/`: `make shellcheck` currently covers only Bash scripts under + `scripts/` whose paths already exist in `HEAD`. +- Fix diagnostics introduced by the change. Report any remaining diagnostic + with its location and reason; do not extend ignore lists just to pass. + A missing tool or failed invocation is not a passed check. Report the + checked base and HEAD, commands, results and checks not run. After editing + code or commit messages, rerun the affected checks on the final version. - Use the narrowest real entry point from the top-level/component Makefiles. The top-level build and packaging workflows are represented by `.github/workflows/ci.yml` and `.github/workflows/coverity.yml`. -- Kernel-style checks use `scripts/checkpatch`, `scripts/checkpatch_diff`, or - `scripts/checkpatch_commits`. The kernel compatibility, compile, sparse, and - smatch workflow is `scripts/run-regression-tests` as configured by - `.github/workflows/run_regression_tests.yaml`; it is heavyweight, downloads - or prepares kernel trees, and is not a quick unit test. -- `make ginkgo-check` checks the component-test framework only. Read a local - `AGENTS.md` before using a component `test` target. For instruction-only or - documentation-only changes, inspect the full diff and run - `git diff --check`; do not build merely to validate prose. +- `scripts/run-regression-tests` provides kernel compatibility, compilation, + sparse and smatch checks. It downloads or prepares kernel trees and is not + part of the lightweight checks above. Static checks do not establish build + or runtime correctness. +- `make ginkgo-check` checks the component-test framework only. Read component + guidance before using its `test` target. Do not build merely to validate + instruction-only or documentation-only changes. - Never use an untracked local helper as an established project entry point. ## Safety boundaries diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..11f0de85e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,105 @@ +# Contributing to SCST + +SCST follows the [Linux kernel coding style][coding-style] for C code and +[Submitting patches][submitting-patches] for commit-message structure. The +rules below describe SCST-specific additions and exceptions. + +## Code style + +- Preserve the naming and diagnostic conventions of the component being + changed, including its existing `TRACE_*` and `PRINT_*` macros. The shared + definitions are in `scst/include/scst_debug.h`. +- Use the repository's `scripts/checkpatch` wrapper. Its ignore list records + the diagnostics disabled for SCST; do not copy that list into another + configuration. A disabled diagnostic is not a general style exemption. + +## Commit messages + +`Signed-off-by:` is optional in SCST. This matches the `MISSING_SIGN_OFF` and +`NO_AUTHOR_SIGN_OFF` exclusions in `scripts/checkpatch`. + +Use a prefix from the registry below in the kernel-style subject: + +```text +scst_vdisk: Refresh thin provisioning after backend changes +scripts: Add commit message checks +``` + +Choose the most specific registered prefix that describes the change. Add a +new prefix and its scope to this registry before using it. Existing history +contains aliases and ad hoc path prefixes; their presence alone does not +register them for new commits. Standard Git-generated merge and revert +subjects retain their usual form. + +### Prefix registry + +| Prefix | Scope | +| --- | --- | +| `scst` | Core changes spanning several core components. | +| `scst_main` | Core registration, initialization and lifecycle. | +| `scst_lib` | Core command and device helpers. | +| `scst_targ` | Core command execution and target processing. | +| `scst_mem` | Core memory and scatter-gather allocation. | +| `scst_sysfs` | Core sysfs interfaces. | +| `scst_pres` | Persistent reservations. | +| `scst_dlm` | Cluster and DLM integration. | +| `scst_event` | Core event interface. | +| `scst_copy_mgr` | Copy manager. | +| `scst_debug` | Shared tracing and diagnostics. | +| `scst_vdisk` | Virtual disk handlers. | +| `scst_user` | User-space device-handler interface. | +| `scst_disk`, `scst_tape`, `dev_handlers` | Physical disk, tape, or shared device-handler changes. | +| `scst/include/backport.h` | Shared kernel compatibility helpers. | +| `iscsi-scst`, `iscsi-scstd`, `isert-scst` | iSCSI target, control daemon, or iSER transport. | +| `qla2x00t-32gbit`, `qla2x00t` | Newer or legacy QLogic tree, respectively. | +| `srpt`, `fcst`, `scst_local` | SRP, FCoE, or local target driver. | +| `scstadmin` | Configuration utility, Perl library and service integration. | +| `scripts` | Repository development and maintenance scripts. | +| `tests` | Component tests and their framework. | +| `build` | Build system and packaging. | +| `dpkg` | Debian package generation. | +| `nightly build` | Nightly kernel matrix and automation. | +| `.github/workflows` | GitHub Actions workflows. | +| `docs`, `www` | Project documentation or website material. | +| `.gitignore` | Repository ignore rules. | + +For new commits, use `srpt` instead of the historical `ib_srpt`, +`.github/workflows` instead of `github`, and `build` instead of `Makefile`, +`Makefiles` or `kbuild`. If a change spans several areas, select the area that +motivated it rather than combining prefixes with commas. An established +subarea may follow the prefix, for example `qla2x00t-32gbit: target: ...`. + +## Local checks + +[AGENTS.md](AGENTS.md#validation) lists the checks to run before handing off +work. The same commands can be run manually; no Git hooks are installed. + +Commit checks use [Conform][conform] (`v0.1.0-alpha.30` was used to validate +this configuration), available as `conform` on `PATH`. `.conform.yaml` +checks the kernel-style subject length and trailing punctuation. Prefix +selection and the explanation of the change require review. Conventional +Commits validation is deliberately disabled because SCST prefixes include +hyphens, spaces and paths. + +For a nonempty linear series with an ancestor base, run +`conform enforce --revision-range ..HEAD` from the repository root. +Conform's range traversal in the version above does not work in linked Git +worktrees. In a linked worktree, or for a history containing merges, check +each non-merge commit in `..HEAD` using a message file outside the +repository: + +```sh +git show -s --format=%B > +conform enforce --commit-msg-file +``` + +A failed invocation does not count as a successful check. + +Checkpatch requires a kernel `scripts/` directory containing `checkpatch.pl` +and its companion data files. The wrapper defaults to the running kernel's +build tree; set `CHECKPATCH_PATH` to use another prepared directory. Record +the kernel/tool version with the result when it affects diagnostics. + +[coding-style]: https://docs.kernel.org/process/coding-style.html +[submitting-patches]: https://docs.kernel.org/process/submitting-patches.html +[conform]: https://github.com/siderolabs/conform