Archived

This repository has been archived on 2026-06-22. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.

Padreug 30fbd0cef9 docs: add upstream-PR workflow + lnbits branch-model reference

Two new docs under docs/:

- upstream-prs.md — how to send a PR upstream using the
  ~/dev/upstream-prs/ worktree flow. Opens with a "Primer" section
  for anyone new to forks / pull requests (the three remote roles —
  upstream / github-fork / origin — explained as a table), then the
  per-project prerequisites, the prb/prc helper-driven workflow, and
  a "Common pitfalls" section.

- lnbits-upstream-flow.md — reference for how lnbits/lnbits actually
  moves: the dev/main branch split, the squash-merge PR convention,
  the non-FF release merge from dev into main, and how to read the
  history with --first-parent. Adapted from internal aiolabs notes
  with the fork-versioning specifics stripped; closing section is
  generic guidance for anyone maintaining their own long-lived fork.

README links both from a new "Further reading" section. The prior
"Contributing" section is retitled "Contributing to this scaffold"
to avoid colliding with the new upstream-PR doc on the term.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-25 20:07:03 +02:00

4.4 KiB

Raw Permalink Blame History

Contributing back to upstream

How to send fixes or features upstream (to projects like lnbits/lnbits) using the worktree-based PR flow built into this scaffold's dev-env layer.

New to forks and pull requests? Skim the Primer first. Otherwise jump to Workflow.

Primer

GitHub, Forgejo, Gitea, and similar services host git repositories. To contribute to a project you don't own:

Fork the upstream repo via the web UI ("Fork" button). This creates <host>/<your-user>/<repo> — your personal copy.
Branch off your fork's main (or whichever branch upstream accepts PRs against). Make your change.
Push the branch to your fork.
Open a Pull Request from your fork's branch into the upstream.
Iterate — maintainers review, you push follow-up commits to the same branch and the PR updates automatically.
Maintainer merges — usually as a single squashed commit on upstream's target branch.
Delete the branch on both sides once merged.

The three roles a remote can play in your local clone:

Remote name	What it points at	Read or write?
`upstream`	The canonical project you're contributing to	Read (you fetch from it)
`github-fork` (or `fork`)	Your personal copy you push to	Write (you push to it)
`origin`	Optional: a private mirror you control (forgejo / gitea / codeberg / sourcehut)	Read + write

This scaffold's settings.nix declares all three via git.remotes; the bootstrap script wires them into the local bare repo so every worktree sees the same set automatically. See remotes.md for topology patterns.

Prerequisites (per project)

Fork the upstream repo on the relevant host.
Set your fork URL in settings.nix:
```
git.remotes.fork = "https://github.com/<your-username>/lnbits";
```
Use the SSH form (git@github.com:<your-username>/lnbits.git) if you've set up SSH push.
Bootstrap (or re-bootstrap). The (planned) bootstrap script adds the github-fork remote to the bare repo at ~/dev/repos/lnbits.git.

Verify the remotes are wired:

git -C ~/dev/repos/lnbits.git remote -v

Expected at minimum:

upstream      https://github.com/lnbits/lnbits (fetch / push)
github-fork   https://github.com/<your-user>/lnbits (fetch / push)

If origin is set, it points at your private remote (forgejo etc.).

Workflow

1. Create the PR branch

prb lnbits fix-invoice-validation

The (planned) prb helper:

git fetch upstream
creates branch fix-invoice-validation off upstream/main
adds a worktree at ~/dev/upstream-prs/lnbits-fix-invoice-validation
sets the worktree's push target to your fork (github-fork)

2. Make changes

cd ~/dev/upstream-prs/lnbits-fix-invoice-validation
# … edit, test, commit …
git commit -am "Fix invoice validation for zero-amount invoices"

3. Push to your fork + open the PR

git push -u github-fork fix-invoice-validation

git prints a URL to open the PR. Alternatively, with the GitHub CLI:

gh pr create --base main --head <your-username>:fix-invoice-validation

(Use the project's preferred target branch — for lnbits/lnbits it's dev, not main. See lnbits-upstream-flow.md.)

4. Iterate on review

Push more commits to the same branch — the PR updates automatically. Don't force-push unless you've squashed/rebased deliberately.

5. After merge — clean up

prc lnbits fix-invoice-validation

The (planned) prc helper removes the worktree and prunes the local branch. On the web UI, click "Delete branch" on the merged PR to remove your fork's copy too.

Common pitfalls

PR target branch. Many projects (including lnbits/lnbits) accept PRs against dev, not main. Read the project's CONTRIBUTING file or its branch-model reference before opening.
Stale branches on your fork. They accumulate forever if you don't clean up. prc handles the local side; the web UI handles the fork side.
Commits drifting onto your fork's main. Keep your fork's main strictly in lockstep with upstream/main. All feature work lives in branches.
Wrong remote when pushing. If git push defaults to upstream (because that's origin), you'll get an access-denied error. The worktree's tracking remote should be github-fork; if not, set it: git branch --set-upstream-to=github-fork/<branch>.

4.4 KiB Raw Permalink Blame History