181 lines
4.6 KiB
Markdown
181 lines
4.6 KiB
Markdown
# 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):
|
|
|
|
```nix
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd ~/dev/repos/lnbits.git
|
|
git fetch upstream
|
|
```
|
|
|
|
### Rebase on latest upstream mid-PR
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
prb lnbits fix-invoice-validation
|
|
prb lnbits add-webhook-support
|
|
prb lnbits update-deps
|
|
prl # list all
|
|
```
|
|
|
|
### Abandon a PR
|
|
|
|
```bash
|
|
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"**
|
|
|
|
```bash
|
|
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"**
|
|
|
|
```bash
|
|
prc lnbits fix-x # cleanup first
|
|
prb lnbits fix-x # then recreate
|
|
```
|