CONTRIBUTING.md

Contributing

Thanks for contributing to the Ops Scripts Toolkit.

Scope

• Keep this repository public-safe and generic.
• Do not add company-specific hostnames, account IDs, internal URLs, or private deployment details.
• Use environment variables, config files, and example templates instead of embedded secrets.

Script standards

Naming

• Use snake_case filenames for all scripts.
• Prefer action names for tasks (verb_object.sh / verb_object.py).
• Prefer audit/check names for diagnostics (something_audit.sh, something_check.py).

Bash scripts

• Start with:
  • #!/usr/bin/env bash
  • set -euo pipefail
• Provide usage/--help output for non-trivial scripts.
• Use clear exit codes:
  • 0 success
  • non-zero for warnings/failures/errors
• Avoid destructive defaults; add dry-run modes where practical.

Python scripts

• Use Python 3.
• Include argparse help text for CLI scripts.
• Keep dependencies minimal and documented.
• Handle errors with user-readable messages and non-zero exit codes.

Security requirements

• Never commit credentials, tokens, private keys, or passwords.
• Prefer AWS profiles/roles over static keys.
• Add .example files for environment/config templates.
• If sensitive data was ever committed, rotate it immediately.

Validation before PR

Run locally:

find . -type f -name "*.sh" -print0 | xargs -0 -n1 bash -n
python3 -m compileall -q .
pre-commit run --all-files

Optional CI-parity check:

./security_baseline_run.sh \
  --dry-run \
  --non-strict \
  --no-sudo \
  --only-group network \
  --output-json \
  --json-compact \
  --json-file ./artifacts/security/summary.json \
  --quiet

Pull request guidelines

• Keep changes focused and minimal.
• Update README.md when adding/removing scripts or changing behavior.
• Include examples for new scripts when useful.
• If you run CI manually, ensure it passes before requesting review.