scst/CONTRIBUTING.md

Contributing to SCST

SCST follows the Linux kernel coding style for C code and 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:

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.
kunit	KUnit infrastructure, tooling and unit tests.
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

Run applicable checks from the repository root before submitting a change. Use the resolved base commit of the series as <base>, rather than a moving branch name. Inspect the final diff, including new and untracked files intended for the patch. No Git hooks are installed.

Change	Required local checks
Any change	git diff --check <base>.
Prepared commits	scripts/checkpatch_commits <base> and Conform as described below; review prefixes against the registry above.
Uncommitted C changes	scripts/checkpatch_diff <base>; rerun per-commit checks after preparing the series.
Shell scripts or sourced shell files	Syntax checks and ShellCheck as described below.
Python files	python3 -m py_compile <changed-files>.
Go files	gofmt -l <changed-files> must produce no output; follow component guidance.

Fix diagnostics introduced by the change; report any remaining diagnostic with its location and reason. Do not extend ignore lists just to pass. Record the checked base and HEAD, commands, results and checks not run. A missing tool or failed invocation is not a passed check. After changing code or commit messages, rerun the affected checks on the final version.

Shell scripts

For 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 covers only Bash scripts under scripts/ whose paths already exist in HEAD.

Commit checks

Commit checks use 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:

git show -s --format=%B <commit> > <message-file>
conform enforce --commit-msg-file <message-file>

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.

Analyzer tooling

Run make lint-test for isolated analyzer-tooling fixtures. See the scripts guide for source selection, exact exclusions and tooling requirements.

Builds and tests

Use the narrowest applicable target from the top-level or component Makefile. INSTALL.md covers build prerequisites and installation; make help lists targets and variables. Build and packaging workflows live in .github/workflows/ci.yml and .github/workflows/coverity.yml.

• KUnit checks kernel functions with private fixtures and simulated dependencies. Its guide covers module builds, VM execution, fixture cleanup and userspace checks for the runner.
• Ginkgo component tests exercise management, SCSI commands and data I/O through a configured SCST target. make ginkgo-check checks the framework only; follow the guide before running tests that load modules or access storage.

make sparse and make smatch analyze the configured modules; use KUNIT_TEST=y to include KUnit sources. Their policies and reports are described in the scripts guide.

scripts/kernel/run-regression-tests checks kernel compatibility through compilation and checkpatch. It downloads or prepares kernel trees and is separate from the analyzer targets above. The nightly support matrix is ABT_KERNELS in nightly/conf/nightly.conf; CI exercises a subset in .github/workflows/run_regression_tests.yaml.

Report static checks, compilation and executed tests separately. Static checks do not establish build or runtime correctness. Documentation-only and instruction-only changes do not require a build or a live test run.