Contributing to Blackout Secure Dev Setup Kit

Thank you for your interest in contributing.

Getting started

Fork the repository.
Clone your fork: git clone https://github.com/your-username/bos-devsetup-kit.git
Create a feature branch: git checkout -b feat/your-feature.
Run the setup script to install the local toolchain. ShellCheck is included by default; optional additional lint tooling includes:
- PSScriptAnalyzer for *.ps1
- shellcheck for *.sh
- ruff for src/configure-vscode.py

Every tunable lives in config/dev-setup.config.json. Prefer adding or changing a config key over hardcoding a new value in a script.

Run an installer script on its own to iterate quickly, for example:

pwsh ./src/scripts/install-node.ps1 -Audit

bash ./src/scripts/install-node.sh --audit

Run the full setup in audit mode before testing a real run:

.\setup.ps1 -Audit

./setup.sh --audit

Test both the audit and real-run paths for anything you touch.
Update README.md if you add or change a config key, option, or script.
Keep platform parity — a behavior change to the PowerShell path should have a matching bash change, and vice versa, unless the platforms genuinely diverge.
Open the PR with a clear description of the change and the motivation.

No admin/root access, no sudo, no WSL. Every step must work per-user.
Every step must be idempotent and safe to re-run.
Every install step needs an audit path that detects and reports without writing anything.
Follow .editorconfig (4-space indent, LF line endings, tabs in *.sh).
Read tunables through the shared config loader (src/config.ps1, src/config.sh) rather than duplicating lookup logic.

Use GitHub Issues for bug reports.
Include your OS/shell, the -Audit/--audit output, and the relevant section of your config/dev-setup.config.json.
For security issues, follow the organization-wide Security Policy and report privately via GitHub Security Advisories.

By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0.