docs(dev-env): aiolabs stack overview and lnbits workflow notes
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
dbd9e76027
commit
346042f1c5
8 changed files with 1276 additions and 0 deletions
181
modules/dev-env/docs/upstream-prs.md
Normal file
181
modules/dev-env/docs/upstream-prs.md
Normal file
|
|
@ -0,0 +1,181 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue