forked from farhoodlabs/paperclip
Chris Farhood
9f3f71a199
Captures branch model (master/dev/local), the 3-file fork delta, upstream sync procedure, and the post-reset rule against re-introducing fork code. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
# Paperclip fork — farhoodlabs
|
|
|
|
This is a thin fork of [paperclipai/paperclip](https://github.com/paperclipai/paperclip).
|
|
Fork repo: https://git.farh.net/farhoodlabs/paperclip
|
|
|
|
## Branch model
|
|
|
|
| Branch | Purpose |
|
|
|---|---|
|
|
| `master` | Pure mirror of `upstream/master`. No fork files. Sync via `git push origin upstream/master:master --force-with-lease`. |
|
|
| `dev` | `master` + one fork commit (Dockerfile prod stage + 2 build workflows). Builds `git.farh.net/farhoodlabs/paperclip-dev:*` on push. |
|
|
| `local` | **Deployed branch.** Same content as `dev`. Builds `git.farh.net/farhoodlabs/paperclip:*` on push. |
|
|
|
|
The fork tree differs from upstream by exactly **3 files**:
|
|
|
|
```
|
|
Dockerfile (production stage adds kubectl, kubeseal, uv, forgejo CLIs, tea, mmx-cli, nano, vim)
|
|
.github/workflows/build-prod.yml (pushes to git.farh.net/farhoodlabs/paperclip)
|
|
.github/workflows/build-dev.yml (pushes to git.farh.net/farhoodlabs/paperclip-dev)
|
|
```
|
|
|
|
The base/deps/build stages of the Dockerfile match upstream verbatim so upstream changes apply cleanly.
|
|
|
|
## Sync upstream
|
|
|
|
```bash
|
|
git fetch upstream
|
|
git push origin upstream/master:master --force-with-lease
|
|
git checkout dev && git merge master && git push origin dev
|
|
git checkout local && git merge dev && git push origin local
|
|
```
|
|
|
|
Conflicts should only ever appear on `Dockerfile` itself (if upstream changes the production stage). Resolution rule: keep upstream's deps/base/build stages exactly; preserve the fork's `RUN` block in the production stage.
|
|
|
|
## Deployment
|
|
|
|
Production runs in Kubernetes (`paperclip` namespace, single replica). Image: `git.farh.net/farhoodlabs/paperclip:<tag>`. Flux does not watch moving tags — rolling a fix means either pushing a semver-tagged release or `kubectl rollout restart deploy/paperclip -n paperclip`.
|
|
|
|
## Don't
|
|
|
|
- **Don't add fork code changes.** This fork is intentionally minimal after the 2026-05-31 reset (event-loop starvation bug from accumulated drift). If a feature is missing relative to a prior fork iteration (Gitea-hosted skills, PAT support for private skill repos, secret export/import, k8s sandbox-provider plugin, agentId threading), surface the regression — don't pull it back from `git log` without explicit go-ahead.
|
|
- **Don't commit to `local` without going through `dev` first** (and through `master` for upstream syncs). The promotion order is enforced.
|
|
- **Don't recreate `.farhoodlabs/` overlay or `assemble-local.yml`.** That model was retired.
|