CONTRIBUTING.md

Contributing to RigForge

RigForge is the companion miner for the Pithead P2Pool stack. Bug fixes, CPU tuning profiles, and docs changes are all welcome.

If your idea is about the stack as a whole rather than the miner, the Pithead repo may be the better home for it.

Before you start

• For anything beyond a small fix, open an issue first so we can agree on the approach before you spend time on it. This avoids duplicated work.
• Check the existing issues to see if someone is already on it.

Making changes

RigForge is portable Bash that has to run on Ubuntu/Debian. macOS is deprecated (#493): unsupported and untested — no CI, no bench — but the Darwin code paths still work and stay working, so don't break them gratuitously:

• Keep it portable. Avoid GNU-only flags and other Linux-isms where a POSIX-friendly alternative exists, and guard platform-specific code paths.

• Run make lint before you push and fix any warnings. It runs ShellCheck and shfmt over the script, utilities, and the test scripts, exactly as CI does:

  make lint    # or: make test  (lint + the full dependency-free suite)

  CI runs the same checks with pinned tools (shfmt 3.14.1, diff-cover 10.6.0 for patch coverage, and zizmor 1.30.1 for workflow security), so use matching versions when reproducing a CI finding. (make fmt auto-applies the shfmt formatting.) make lint also runs the topology gate and the file budget gate below.

• Update the README or other docs when you change behavior or add options.

• New config.json keys are lowercase snake_case, matching Pithead. The three SCREAMING legacy keys (ACCESS_TOKEN, DONATION, HOME_DIR) are frozen as-is — never rename a shipped key.

Pre-commit hooks

Install the hooks once and they run on every commit, catching issues before they reach CI:

make dev-setup            # installs the linter toolchain (brew/apt) + the git hooks in one go
# — or by hand:
pipx install pre-commit   # or: pip install pre-commit
pre-commit install

This runs make lint (ShellCheck + shfmt over the Makefile's SHELL_FILES), gitleaks secret scanning (the same pinned version CI runs, so a committed token or pool credential is caught before it's pushed), and a few hygiene checks: private-key detection, a large-file guard, and final-newline and trailing-whitespace fixers.

File budget gate

make lint fails if a source file grows past its ceiling. Two rules, and scripts/lint-file-budget.sh is the whole implementation:

• A file over 400 lines must have a row in docs/dev/file-budget.tsv recording its current line count. Over 800 with no row, the refusal names the hard ceiling instead — a new file has no reason to be born that big.
• Ceilings only ever go down. The gate compares your budget file against develop and rejects any row whose ceiling rose. A row's first appearance must record the file's real count, not reserve headroom above it. A file that shrinks back to 400 or under drops its row.

make lint-file-budget                    # self-test, then the gate
scripts/lint-file-budget.sh --generate   # reprint the budget this tree implies; commit it by hand

Prose (*.md), data (*.json), and binaries are exempt — the reasons are enumerated one per glob in the script. rigforge.sh is deliberately not exempt.

If your change is refused because the ceiling equals the file's current size, the ratchet has left no slack, which is intended. Ask first whether a line-neutral form of the change exists; that question usually dissolves the problem. If there genuinely is none, fold the addition into the same commit as a cut that makes room for it — never a follow-on PR, which cannot raise the ceiling to fit.

Regenerate the budget file rather than merging it, and never resolve a conflict in it by taking a side: both sides are measurements of different trees, and taking one bakes in a count that was never true of the merged result. The gate never rewrites this baseline: --generate prints a proposed copy to stdout, and a contributor deliberately redirects and reviews it.

Config & docs linting

The YAML, Markdown, and link checks gate in CI and have matching Make targets for local runs:

make lint-yaml     # yamllint the workflows + configs   (.yamllint)
make lint-md       # markdownlint the docs              (.markdownlint-cli2.yaml; needs Node 22+)
make lint-links    # lychee link-check the docs         (.lychee.toml; needs lychee — runs weekly in CI)
make lint-all      # shell + yaml + markdown + workflows in one go
make ci            # everything CI runs that can run locally (adds the container e2e when Docker is up)

The weekly CI tool watcher reads the Markdown linter pin from Makefile and compares it with npm's latest published version. It reports stale pins without changing them; failed or malformed registry responses remain unchecked and fail the watcher. Validate a pin update with make lint-md. GitHub Actions and pre-commit dependencies are watched by Dependabot.

An .editorconfig encodes the whitespace conventions (shfmt -i 4, LF, final newline) so most editors match these checks automatically.

Branching

RigForge uses a two-branch model (same as Pithead):

• develop is the default, integration branch. All PRs target develop.
• main is the release branch. develop is merged into main at each release, and version tags are cut from main.

Submitting a pull request

1. Fork the repo and create a topic branch off develop.
2. Make your change and confirm shellcheck passes.
3. Open a PR against develop and fill out the template.
4. A PR into develop merges on green required checks plus the adversarial-review status recorded on its head SHA by a session that did not author it, human-driven or automated. Merges are explicit, never automatic: bring the branch up to date with develop, get the review at that head, then gh pr merge --squash. Only the owner's account merges; a PR into main also needs the code owner's review.

Keep PRs focused and the description clear about what changed and why. Small, reviewable changes get merged faster.

By contributing, you agree that your contributions are licensed under the project's MIT License.