omnixient/modules/dev-env/docs/upstream-prs.md

Contributing to Upstream Projects

How to contribute fixes and features back to upstream projects (lnbits, lamassu, nix-bitcoin, Lightning.Pub) using the worktree-based workflow provided by dev-env.

Prerequisites (one-time, per repo)

1. Fork the upstream repo on GitHub. Click "Fork" on the upstream's GitHub page (e.g. github.com/lnbits/lnbits) to create your personal copy.

2. Set your GitHub username in the dev-env config (or override per-project):

   dev-env.github.forkUser = "your-github-username";
   

3. Re-run dev-env-bootstrap. It adds the github-fork remote to the bare repo derived from git@github.com:<forkUser>/<repo>.git. Verify with:

   git -C ~/dev/repos/lnbits.git remote -v
   # origin       forgejo@git.atitlan.io:aiolabs/lnbits.git (fetch)
   # upstream     https://github.com/lnbits/lnbits (fetch)
   # github-fork  git@github.com:your-github-username/lnbits.git (fetch)
   

Quick reference

Command	Alias	Description
git-pr-branch <repo> <branch>	prb	Create PR worktree from upstream/main
git-pr-cleanup <repo> <branch>	prc	Remove worktree after PR merges
git-pr-list	prl	List active PR worktrees
prs	—	cd ~/dev/upstream-prs

Workflow

1. Create the PR branch

prb lnbits fix-invoice-validation
# Fetches upstream
# Creates 'fix-invoice-validation' from upstream/main
# Adds worktree at ~/dev/upstream-prs/lnbits-fix-invoice-validation

2. Make changes

cd ~/dev/upstream-prs/lnbits-fix-invoice-validation
git status                       # On branch fix-invoice-validation
nvim src/some_file.py
pytest tests/
git commit -am "Fix invoice validation for zero-amount invoices"

3. Push to your GitHub fork

git push github-fork fix-invoice-validation

4. Open the PR on GitHub

Go to upstream (e.g. github.com/lnbits/lnbits). You'll see the "fix-invoice-validation had recent pushes" banner. Click "Compare & pull request" and fill in title/description.

5. Address review feedback

cd ~/dev/upstream-prs/lnbits-fix-invoice-validation
nvim src/some_file.py
git commit -am "Address review: add input sanitization"
git push github-fork fix-invoice-validation

6. Cleanup after merge

prc lnbits fix-invoice-validation
# Removes worktree, deletes local branch

Layout

~/dev/
├── repos/
│   └── lnbits.git              # bare repo, three remotes:
│       ├── origin              # forgejo (your team's fork)
│       ├── upstream            # github (lnbits/lnbits)
│       └── github-fork         # github (your-github-username/lnbits)
│
├── lnbits/                     # team-fork worktrees
│   ├── dev/
│   └── main/
│
└── upstream-prs/
    └── lnbits-fix-invoice-validation/   # transient PR worktree

Git remotes explained

Remote	Points to	Used for
origin	Forgejo	Your team's fork — main, dev, feature/*
upstream	GitHub (original)	Read-only; fetch latest upstream changes
github-fork	GitHub (your fork)	Write-only target for PR branches

Common scenarios

Sync with upstream before starting

prb does this for you, but if you need to manually:

cd ~/dev/repos/lnbits.git
git fetch upstream

Rebase on latest upstream mid-PR

cd ~/dev/upstream-prs/lnbits-fix-invoice-validation
git fetch upstream
git rebase upstream/main
git push github-fork fix-invoice-validation --force-with-lease

Multiple PRs for the same repo

prb lnbits fix-invoice-validation
prb lnbits add-webhook-support
prb lnbits update-deps
prl   # list all

Abandon a PR

prc lnbits fix-invoice-validation   # same as cleanup

Best practices

1. One PR per feature/fix. Keep PRs focused and reviewable.
2. Branch from upstream/main. prb enforces this.
3. Clear commit messages. What and why, not just what.
4. Test before pushing.
5. Cleanup after merge. Don't accumulate stale worktrees.
6. Rebase, not merge. Keeps a clean history.

Troubleshooting

"github-fork remote not found"

git -C ~/dev/repos/lnbits.git remote add github-fork \
    git@github.com:$GITHUB_FORK_USER/lnbits.git

Or re-run dev-env-bootstrap after setting dev-env.github.forkUser.

"Permission denied" pushing to github-fork

• Make sure you've forked the repo on GitHub.
• Check ssh -T git@github.com succeeds.
• Verify the URL: git -C ~/dev/repos/lnbits.git remote -v.

"Branch already exists"

prc lnbits fix-x   # cleanup first
prb lnbits fix-x   # then recreate