Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
70 lines (51 loc) · 2.63 KB

CONTRIBUTING.md

File metadata and controls

70 lines (51 loc) · 2.63 KB
Raw

Contributing

This repository provisions a development environment. Every mechanism in it, whether bash, Nix, a container image or an Ansible role, must converge on the same toolchain, which is listed in CLAUDE.md.

Ground rules

No secrets, ever. Real values live in ~/.config/shell/secrets.env at mode 0600, outside version control. A template committed here contains commented-out variable names only, never values. Refer to credentials by name.

Everything must be idempotent. Re-running any provisioner against an already provisioned machine must be a no-op that exits zero. bootstrap.sh does this with per-item have and skip guards. Keep that property.

A failing third-party repository must not abort provisioning. Warn, name the repository and the URL, and carry on. A missing vendor package is a degraded machine, not a failed run.

Expose the corporate escape hatches. Anything new needs equivalents of PROXY, CORP_CA and REPO_SUITE. Do not assume unproxied egress or a trusted default CA bundle.

Shell scripts

  • set -euo pipefail at the top.
  • Clean under shellcheck -S warning.
  • LF line endings. .gitattributes enforces this, because the repository is often edited from Windows and executed inside WSL, where a CRLF shebang makes the interpreter unresolvable.
  • Executable bit set on anything meant to be run directly.

Check your work before opening a pull request:

shellcheck -S warning bootstrap.sh
./bootstrap.sh verify

Documentation and comments

British spelling. No em dashes or en dashes anywhere, including comments and commit messages.

Explain the reasoning behind anything that looks odd. Several things in this repository are deliberate and have been rediscovered the hard way more than once: the pinned REPO_SUITE, the PATH precedence that lets apt shadow brew, and the use of absolute paths for git credential helpers. The "Things already learned the hard way" section of CLAUDE.md is the record of those. Add to it when you learn a new one.

Commits

  • Imperative mood in the subject line, wrapped at 72 characters.
  • A body only when the change needs explaining.
  • Signed commits. commit.gpgsign is expected to be true.
  • No trailers or sidecars of any kind. No Co-Authored-By, no tool attribution, no emoji markers. The message ends where the message ends.

Pull requests

Keep changes focused. Fill in the pull request template, including evidence that the change actually provisions a machine: the relevant bootstrap.sh output, or a clean verify run.

Licence

By contributing you agree that your contributions are licensed under the MIT License.