Contributing

Contributing

Contributions, issues and module requests are welcome. This page summarises the workflow; the canonical source is CONTRIBUTING.md in the repository.

Ground rules

• Bash ≥ 4.0. Use modern features (mapfile, ${var,,}, arrays).
• One module = one file under lib/modules/, with a KRAKEN_MODULE_*_LOADED guard and a single kraken_<name>_run entry point. See Extending Kraken.
• Use the shared helpers (log_*, prompt_value, ensure_command, ensure_repo, kraken_valid_target) instead of re-implementing them.
• No set -e inside modules, return on error and let the operator read the message.
• Graceful degradation is mandatory: guard every external tool.

Local checks

Run these before opening a pull request, they mirror CI:

# Syntax
bash -n kraken.sh lib/*.sh lib/modules/*.sh

# Lint (uses the repo .shellcheckrc, SC1091/SC2034 disabled)
shellcheck kraken.sh lib/*.sh lib/modules/*.sh

# Source chain + help/version
bash kraken.sh --help
bash kraken.sh --version

Continuous integration

.github/workflows/ci.yml runs three jobs on every push and PR:

1. shellcheck at warning severity.
2. bash -n over all shell scripts.
3. smoke test that sources the whole chain and asserts every public function exists, then runs --help / --version.

If you add a public function (e.g. a new kraken_<name>_run), add it to the expected array in the smoke job.

Commit style

Conventional-commit prefixes are used in history: feat:, fix:, perf:, docs:, chore:. Keep the subject under ~50 characters and explain the why in the body when it is not obvious.

Security issues

Do not open public issues for vulnerabilities in the wrapper, follow SECURITY.md in the repository. See also Disclaimer & Legal.