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](docs/DEVELOPMENT.md).

```sh
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](https://www.conventionalcommits.org/) 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](LICENSE).

The gates are listed in [docs/DEVELOPMENT.md](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](SECURITY.md) describes.