scripts/CONTRIBUTING.md

Contributing

Thanks for contributing to scripts.

Development setup

Requirements: Perl 5.38 or newer, which is what the oldest supported system ships (CentOS Stream 10 carries 5.40, openEuler 24.03 LTS carries 5.38). No module beyond the interpreter is needed, by design: the scripts use builtins only. Podman is needed only for the container rigs described in docs/DEVELOPMENT.md.

git clone https://sourcedock.dev/petrbalvin/scripts.git
cd scripts
perl -c network-diag.pl
perl tests/network-diag.pl

Workflow

1. Branch from development. Never commit directly to main, which is release-only.
2. Commit in Conventional Commits form: type(scope): description, subject line only, imperative mood, lowercase after the colon, no trailing full stop. Allowed types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert.
3. One logical change per commit. A refactor, a behaviour change and a formatting pass are three commits, never one.
4. Add or extend the checks in tests/ for the code you touched. A new script arrives with its own tests/<script>.pl.
5. Update the documentation when the flags, the behaviour or the target systems change.
6. Open a pull request against development.

main is not a release branch in the usual sense: the deploy pipeline publishes the scripts on every push to it, so a merge to main is a release. The scripts carry their own versions, and the commit history is the record of what changed.

Code style

There is no formatter to run, and the style is the one the other scripts already share. Read the script nearest to your change and follow it.

• Builtins only. No use beyond strict and warnings. A job Perl has no builtin for is either written out in the script (the command runner, version comparison, the JSON codecs, IPv4 and IPv6 arithmetic) or delegated to a system binary through the script's run helper, which is how dnf, rpm, curl, openssl, podman, systemctl and the rest are driven.
• Every external command is one argument list. run([...]) never builds a string, so no shell parses a path, a key or a URL.
• Idempotence is the contract. Every operation checks the current state first and reports what it found; running a script twice must change nothing the second time.
• --dry-run changes nothing, and the summary of a dry run reads as a preview, not as an accomplishment.
• Messages are in British English, on stderr, and none of them uses a dash as punctuation.
• perl -c <script> must be clean, and so must perl tests/<script>.pl.
• New files open with the shebang #!/usr/bin/env perl, then the two-line licence header whose SPDX identifier matches LICENSE.

The gates are listed in docs/DEVELOPMENT.md, and the test pipeline runs the same set.

AI contribution policy

AI tools are welcome as productivity aids and are a normal part of modern software development. What matters is that the contribution stays understandable, reviewable and genuinely useful.

• Disclose the assistance. If AI helped draft any part of a commit, issue, pull request or review, say so.

• Commit messages carry exactly one trailer, on the line after the subject:

  Assisted-by: MODEL
  

  Name the model that did the work, spelled the way its maker spells it, for example GLM 5.3, DeepSeek V4.1 Flash or Qwen 3.8 Flash. No Co-Authored-By, no Signed-off-by, no other trailers, and no prose: the trailer is the disclosure.

• Issues and pull requests attribute the assistance in a comment, for example _Assisted-by: GLM 5.3_. It does not belong in the pull request description.

• Take responsibility. You are accountable for the accuracy, completeness and intent of everything you submit, whether or not AI produced it.

• Review before marking ready. Read the diff carefully, run it locally, and add the tests it needs. Do not mark a pull request ready until you can defend every change in it.

• Quality over quantity. Contributions that look like un-reviewed output, or whose author cannot engage substantively during review, may be closed.

• Preferred models. Prefer open-weight models with transparent training data and minimal output filtering.

AI assists. It does not replace judgement.

Continuous integration

Workflows live in .gitea/workflows/ and run on the project's own runners:

Workflow	Trigger	What it does
Test	push or pull request to development	every script compiles, carries its licence header and uses no dash as punctuation, then the six check files under tests/
Deploy	push to main	writes SHA256SUMS over every script and publishes them over rsync

The container rigs are not in the pipeline: they need Podman and a privileged container, which belong to the machine at the keyboard rather than to a shared runner. A change to a script that touches a system is expected to be verified that way locally, and the pull request says what was run.

Reporting bugs

Open an issue at https://sourcedock.dev/petrbalvin/scripts/issues with the script and its version (the script's --version), the operating system and version, the exact command, the full output, and the expected against the actual behaviour.

Security issues do not go in the issue tracker. Report them as SECURITY.md describes.