Files
nix-bitcoin/CLAUDE.md
T
plebandClaude Opus 5.5 aedda5bc86 docs: describe the fork vs upstream, add CLAUDE.md
- README: table of differences from upstream (master), pin a release
  tag in the usage example, drop references to personal hosts
- docs/fork-maintenance.md -> docs/maintenance.md: rewritten from a
  tracking note into a record of what was removed and an ongoing
  maintenance guide (mempool signers, per-release checklist)
- CLAUDE.md: branch layout, tag a release after consumer-facing
  changes (v0.MINOR.PATCH), how to check changes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 08:40:23 -08:00

2.4 KiB

CLAUDE.md

This is a trimmed fork of fort-nix/nix-bitcoin, which is archived. It has NixOS modules for bitcoind, lnd, electrs and mempool only. Read README.md for an overview and docs/maintenance.md for what was removed and what needs upkeep.

Branches

  • main is where development happens, and releases are tagged from it. Commit here.
  • master holds upstream's archived tree for reference. Don't commit to it or move it.
  • On gitea, the default branch is master, so consumers must pin a tag.

Tag a release after every change

Consumers pin ?ref=refs/tags/vX.Y.Z, so a change on main doesn't reach anyone until it's tagged. After committing a change that affects what consumers evaluate or build (modules, pkgs/, flake.nix, flake.lock), propose a new tag. Changes that only touch docs don't need one.

Versioning is v0.MINOR.PATCH. Ignore upstream's v0.0.x tags, which exist only in older local clones.

Bump When Examples
MINOR Package version bumps, new options, anything a consumer may have to change config for (removed or renamed options, changed defaults) v0.1.0 → v0.2.0
PATCH Fixes and hash refreshes with no config impact v0.1.0 → v0.1.1

Steps:

  1. Find the latest fork tag with git tag --list 'v0.[1-9]*' --sort=-v:refname | head -1.
  2. Create an annotated, unsigned tag: git tag -a vX.Y.Z -m "<summary>". In the message, summarize the changes since the last tag and say whether the release has been deployed yet.
  3. Push the branch and the tag with git push origin main and git push origin vX.Y.Z. Pushing is outward-facing, so confirm with the user first.
  4. Remind the user to bump the tag in the consuming flake.

Checking changes

There is no test suite.

  • Run nix flake check for evaluation.
  • After touching pkgs/mempool/, run nix build .#mempool-backend .#mempool-frontend .#mempool-rust-gbt .#mempool-nginx-conf.
  • Runtime behaviour is only verified by deploying to a node. Say so when something hasn't been deployed.

mempool updates

Use pkgs/mempool/generate.sh. It checks the release tag's signature against pinned fingerprints for wiz and mononaut. Never add a new signer fingerprint without the user's sign-off. See the "Updating mempool" section of docs/maintenance.md.

Writing style

The README and docs describe a generic node. Don't name personal hosts or private configs.