Git & Open Source Workflow

Open source Bitcoin work is collaboration under a microscope. Your code is not “done” when it runs on your laptop, it is done when reviewers can understand, test, and trust it.

Why this matters

Bitcoin repositories move carefully. A confusing commit history or a PR that mixes five unrelated changes will stall. Learning the workflow early makes every later contribution smoother.

Analogy

A pull request is like a work order on a job site: what changed, why it is safe, and how to verify it. Maintainers are the inspectors. They are not being difficult, they are protecting users’ money.

The daily loop

Branching

git checkout -b fix/clarify-fee-docs
# ...edit files...
git add -p
git commit -m "docs: clarify fee estimation examples"
git push -u origin HEAD

Keep branches focused: one bug, one feature, or one docs improvement.

Commits that help reviewers

Prefer messages that explain why:

• Good: wallet: avoid double-counting change in balance
• Weak: fix stuff

Conventional commit prefixes (fix:, feat:, docs:, test:) help changelogs and skimming.

Pull request hygiene

A strong PR description answers:

1. What problem are you solving?
2. How did you test it?
3. What should reviewers watch for?

Common mistakes

• Opening a PR from main with dozens of unrelated commits
• Force-pushing during active review without warning
• Ignoring CI failures and asking for review anyway

Practice

Fork a small Bitcoin-adjacent repo, fix a typo or docs issue, and open a PR following the project’s CONTRIBUTING.md. Treat the review comments as the real lesson.

Worked mental model

Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

Hands-on habit

Every protocol idea should be paired with one local experiment:

1. Reproduce the happy path on regtest (or Polar for Lightning)
2. Break it on purpose (wrong fee, expired invoice, offline peer)
3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)

That habit turns reading into builder instinct.

Glossary check

Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

Resource order

Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Next steps

With Git habits in place, study the cryptography that Bitcoin actually uses, hashes, key pairs, ECDSA, and Schnorr.