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>
This commit is contained in:
pleb
2026-11-16 08:40:23 -08:00
co-authored by Claude Opus 5.5
parent 230e5c539b
commit aedda5bc86
4 changed files with 184 additions and 265 deletions
+43
View File
@@ -0,0 +1,43 @@
# 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.