mirror of
https://github.com/SCST-project/scst.git
synced 2026-10-22 06:02:33 +00:00
docs: Define contribution rules and local static checks
Document SCST additions to the Linux kernel coding and commit style, including a prefix registry and optional sign-off. Configure Conform for kernel-style subjects and list applicable pre-handoff checks in AGENTS.md. Use the existing checkpatch and ShellCheck entry points. Document direct Conform invocations for commit ranges and message files in linked worktrees, without introducing another checking script. Keep the existing CI workflows and checkpatch exclusions unchanged.
This commit is contained in:
Gleb Chesnokov
@@ -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
|
||||
@@ -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 `<base>`; do not silently substitute a moving branch.
|
||||
|
||||
| Change | Required local checks |
|
||||
| --- | --- |
|
||||
| Any change | `git diff --check <base>`; inspect added files too, including files not yet tracked. |
|
||||
| Prepared commits | `scripts/checkpatch_commits <base>`; run Conform as described in `CONTRIBUTING.md` and review prefixes against its registry. |
|
||||
| Uncommitted C changes | `scripts/checkpatch_diff <base>`. 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 <changed-files>`. |
|
||||
| Go files | `gofmt -l <changed-files>` must produce no output; follow component validation guidance. |
|
||||
|
||||
- For changed Bash files, run `bash -n <file>` for each file and
|
||||
`shellcheck -x -P SCRIPTDIR <changed-files>`. 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
|
||||
|
||||
+105
@@ -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 <base>..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 `<base>..HEAD` using a message file outside the
|
||||
repository:
|
||||
|
||||
```sh
|
||||
git show -s --format=%B <commit> > <message-file>
|
||||
conform enforce --commit-msg-file <message-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
|
||||
Reference in New Issue
Block a user