Padreug
6adc82e8f3
modules/git/remotes.nix declares upstream/fork/extras schema. extras is a typed submodule list so order is preserved and future fields (pushUrl, mirror) can extend without breaking callers. docs/remotes.md walks the three canonical topologies (upstream-only / github-fork / multi-remote with private host). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# Remote topology
|
|
|
|
`lnbits-sensei.git.remotes` (declared in `modules/git/remotes.nix`)
|
|
abstracts how the local LNbits checkout is wired to its git remotes.
|
|
Three patterns cover almost every workflow.
|
|
|
|
## 1. Upstream-only
|
|
|
|
You read upstream, never push. Good for a read-only dev box, a CI
|
|
runner, or initial exploration before you've decided to contribute.
|
|
|
|
```nix
|
|
lnbits-sensei.git.remotes = {
|
|
upstream = "https://github.com/lnbits/lnbits";
|
|
fork = null;
|
|
extras = [ ];
|
|
};
|
|
```
|
|
|
|
What you get:
|
|
|
|
- `upstream` remote pointing at canonical lnbits/lnbits.
|
|
- No `fork` remote — the bootstrap script skips it when `fork` is null.
|
|
- No extras.
|
|
|
|
## 2. GitHub fork for PRs
|
|
|
|
You maintain a personal fork on GitHub and use it as your push target
|
|
for PRs landing in upstream. `upstream` stays pull-only.
|
|
|
|
```nix
|
|
lnbits-sensei.git.remotes = {
|
|
upstream = "https://github.com/lnbits/lnbits";
|
|
fork = "git@github.com:<you>/lnbits.git";
|
|
extras = [ ];
|
|
};
|
|
```
|
|
|
|
What you get:
|
|
|
|
- `upstream` for fetching releases / rebasing onto main.
|
|
- `fork` as the default push target.
|
|
- The upstream-PR helper (later pass) knows to push branches to `fork`
|
|
and open the compare URL against `upstream`.
|
|
|
|
## 3. Multi-remote with a private host
|
|
|
|
You also push to a private forgejo / gitea / codeberg mirror — for
|
|
internal review, a deployment pipeline, or just an off-GitHub backup.
|
|
The upstream + public-fork flow stays intact; the extras layer on top.
|
|
|
|
```nix
|
|
lnbits-sensei.git.remotes = {
|
|
upstream = "https://github.com/lnbits/lnbits";
|
|
fork = "git@github.com:<you>/lnbits.git";
|
|
extras = [
|
|
{ name = "internal"; url = "git@<your-forgejo>:<org>/lnbits.git"; }
|
|
{ name = "mirror"; url = "git@codeberg.org:<you>/lnbits.git"; }
|
|
];
|
|
};
|
|
```
|
|
|
|
What you get:
|
|
|
|
- Same as pattern 2, plus the named extras as additional remotes.
|
|
- Each extra becomes a `git remote add <name> <url>` on bootstrap;
|
|
pushing to them is opt-in (never the default push target).
|
|
|
|
## Notes
|
|
|
|
- `extras` is a list of `{ name; url; }` submodules — order is
|
|
preserved, and future fields (`pushUrl`, `mirror`) can be added
|
|
without breaking existing configs.
|
|
- The module is schema-only. The dev-env bootstrap script (later pass)
|
|
is what actually runs `git remote add` against a real checkout. It
|
|
is idempotent: re-running after editing `extras` reconciles the
|
|
on-disk remotes with the declared set.
|
|
- `fork = null` is the right value when you have no GitHub fork —
|
|
don't point it at a placeholder URL, the bootstrap script keys on
|
|
null to skip the `fork` remote entirely.
|