Track Forgejo fork problem space notes

forgejo-forking-problem-space.md

@@ -0,0 +1,255 @@
+# Forgejo Forking Problem Space
+
+Date: 2026-05-12
+
+## Current Setup
+
+Created a jojo.build mirror:
+
+- Repo: https://jojo.build/peezy-tech/jojo
+- SSH: `ssh://git@jojo.build/peezy-tech/jojo.git`
+- Upstream: `https://codeberg.org/forgejo/forgejo.git`
+- Default branch: `forgejo`
+- Mirror interval: `8h`
+
+This is currently a mirror, not a working fork branch. That is a good starting
+point for source inspection and tracking upstream movement. It is not yet a good
+place for custom patches, because mirror updates are expected to follow upstream.
+
+## Executive Summary
+
+Forking Forgejo is feasible, but it is not a small maintenance commitment.
+Forgejo is a full Go web application with a substantial frontend build,
+database migrations, templates, Actions integration, SSH/HTTP Git serving,
+packages, OAuth2, and admin surfaces. A fork is reasonable only if the desired
+customization cannot be achieved through supported configuration, OIDC, reverse
+proxy auth, static assets, or template overrides.
+
+For SIWE specifically, the preferred order remains:
+
+1. Use SIWE through an external OpenID Connect provider.
+2. Use a trusted reverse proxy that performs SIWE and passes identity headers.
+3. Fork Forgejo only if we need first-class SIWE UX or native account semantics.
+
+## Upstream Release Cadence
+
+Forgejo stable releases are published quarterly. LTS releases are published in
+the first quarter of each year and receive critical bugfix/security support for
+one year and three months. The current LTS line is v15.0, released 2026-04-16
+and supported until 2027-07-15.
+
+Implication: a fork has to either:
+
+- Track every quarterly release and absorb breaking changes often.
+- Track only LTS releases and accept slower access to new Forgejo features.
+- Track upstream `forgejo` continuously, which maximizes merge churn.
+
+For a production instance, an LTS-based fork is the most conservative option.
+
+## What A Fork Would Own
+
+At minimum, a maintained fork owns:
+
+- A source branch policy.
+- CI for Go, frontend, templates, linting, and tests.
+- Binary or container image builds.
+- A release/version naming scheme.
+- Security patch intake.
+- Upgrade rehearsals against jojo.build data.
+- Documentation for local patches.
+- A rollback path to upstream Forgejo.
+
+The risky areas are not only code conflicts. They are also database migrations,
+template changes, auth/session behavior, Actions behavior, and generated assets.
+
+## Build And Test Surface
+
+Forgejo source includes:
+
+- `go.mod` for the backend.
+- `package.json` and `webpack.config.js` for frontend assets.
+- `Makefile` for build/test targets.
+- `Dockerfile` and `Dockerfile.rootless`.
+- Published release notes in `release-notes-published/`.
+
+Official build docs require Go, Node.js/npm, and `make`. Older docs mention Go
+1.22+ and Node 20+, but we should verify exact versions from the branch we pin
+before building production artifacts.
+
+Initial local validation target should be:
+
+```bash
+make help
+make deps-frontend
+make frontend
+make test
+make build
+```
+
+Exact target names need confirmation from the current Makefile before scripting.
+
+## Auth Extension Surface
+
+Forgejo has configurable auth sources:
+
+- Local database auth.
+- LDAP via BindDN.
+- LDAP simple auth.
+- SMTP.
+- PAM.
+- OAuth2.
+- OpenID Connect.
+- OpenID.
+- Reverse proxy header auth.
+
+From source inspection, auth source types are compiled into the application.
+OAuth2 providers are registered in Go during init via an internal Goth provider
+registry. That registry is useful for patching Forgejo, but it is not an
+external plugin API.
+
+Native SIWE would likely require one of these approaches:
+
+- Add a first-class OAuth2/OIDC provider if SIWE is presented as OIDC.
+- Add a custom auth flow and routes for EIP-4361 challenge/signature handling.
+- Add account-linking fields for wallet addresses and ENS-derived display data.
+- Add admin settings and migration(s) if wallet addresses become persisted
+  first-class identities.
+
+The more native the SIWE behavior, the more the fork touches security-critical
+surface: sessions, CSRF, account linking, auto-registration, 2FA bypass rules,
+and recovery flows.
+
+## SIWE Fork Design Questions
+
+Before writing code, resolve these:
+
+- Is an Ethereum address the canonical Forgejo username, an external account
+  identifier, or merely a linked credential?
+- Do users need email addresses?
+- Can a wallet create a new Forgejo account automatically?
+- How are lost wallets handled?
+- Can one Forgejo account link multiple wallets?
+- Is ENS only display metadata, or does it influence identity?
+- Are smart-contract wallets/EIP-1271 required?
+- Which chains are accepted?
+- Does SIWE bypass local 2FA, complement it, or become a second factor?
+- How do Git over HTTPS, SSH keys, access tokens, and API auth map to wallet
+  sign-in?
+
+These questions matter more than the login button. Forgejo identity is used by
+Git, issues, packages, Actions, API tokens, and admin permissions.
+
+## Fork Strategies
+
+### Strategy A: No Fork
+
+Use config, OIDC, reverse proxy auth, and supported UI customization.
+
+Best for:
+
+- Branding.
+- Trusted SIWE/OIDC experiment.
+- Avoiding security patch ownership.
+
+Risk:
+
+- Less native UX.
+- Identity model constrained by Forgejo's existing auth flows.
+
+### Strategy B: Patch Branch On LTS
+
+Create a branch like `jojo/v15.0` from the current LTS tag, maintain a minimal
+patch stack, and periodically rebase or merge v15.0 patch releases.
+
+Best for:
+
+- Production stability.
+- Small, well-contained changes.
+- Predictable security patch intake.
+
+Risk:
+
+- Larger jumps when moving to the next LTS.
+- Backport work if desired features land in newer stable releases.
+
+### Strategy C: Patch Branch On Upstream `forgejo`
+
+Maintain `jojo/forgejo` on top of upstream development.
+
+Best for:
+
+- Contributing changes upstream.
+- Early access to Forgejo improvements.
+
+Risk:
+
+- Highest churn.
+- Bad fit for production unless we have strong CI and staging.
+
+### Strategy D: Hard Product Fork
+
+Rename/rebrand deeply, ship independent releases, and diverge freely.
+
+Best for:
+
+- Building a distinct forge product.
+
+Risk:
+
+- Largest maintenance burden.
+- Security, release, migration, and support responsibilities become ours.
+
+This should be avoided unless jojo.build becomes a product-level Forgejo
+distribution.
+
+## Recommended Path
+
+Use the mirror as the upstream intake point. Do not customize the mirror branch.
+
+Next create a working fork branch only when we have a concrete patch to test:
+
+- `jojo/v15.0` from the latest v15.0.x tag for production-minded patches.
+- `jojo/forgejo` from upstream `forgejo` for exploratory upstreamable patches.
+
+For SIWE, first prototype without a Forgejo fork:
+
+1. Configure a SIWE OIDC provider against a test Forgejo instance.
+2. Test user creation, account linking, logout, API tokens, Git over HTTPS, and
+   SSH key management.
+3. Separately test reverse proxy header auth with a toy trusted auth service.
+4. Only fork if those approaches fail on essential UX or identity semantics.
+
+## Maintenance Checklist For Any Fork
+
+- Track upstream release notes and security announcements.
+- Keep a patch inventory with rationale and owner.
+- Rebase/merge upstream into a staging branch first.
+- Run full build and test suite.
+- Run upgrade rehearsal against a copy of production data.
+- Smoke test login, repo browsing, Git SSH, Git HTTPS, Actions, packages,
+  mirrors, and admin pages.
+- Keep a rollback artifact for the previous known-good binary/container.
+- Document every app.ini setting required by the fork.
+
+## Open Questions
+
+- Is jojo.build currently installed from binary, container, package manager, or
+  local build?
+- How is production deployment currently rolled out and rolled back?
+- Do we want custom patches to be private indefinitely, or upstreamable?
+- Would SIWE be required for all users, optional, or only for selected orgs?
+- Is the target experience "login with wallet" or broader onchain identity?
+- Are we willing to run an external IdP such as a SIWE OIDC provider?
+
+## Sources Consulted
+
+- Forgejo mirror created from `https://codeberg.org/forgejo/forgejo.git`.
+- Forgejo auth docs: https://forgejo.org/docs/v11.0/user/authentication/
+- Forgejo OAuth2 provider docs: https://forgejo.org/docs/v13.0/user/oauth2-provider/
+- Forgejo customization docs: https://forgejo.org/docs/next/admin/advanced/customization/
+- Forgejo config cheat sheet: https://forgejo.org/docs/latest/admin/config-cheat-sheet/
+- Forgejo upgrade guide: https://forgejo.org/docs/next/admin/upgrade/
+- Forgejo release schedule: https://forgejo.org/docs/v11.0/admin/release-schedule
+- Forgejo compile-from-source docs: https://forgejo.org/docs/v7.0/developer/from-source/
+- SIWE docs: https://docs.siwe.xyz/
+- SIWE hosted OIDC docs: https://docs.login.xyz/servers/oidc-provider/hosted-oidc-provider