99 lines
5 KiB
Markdown
99 lines
5 KiB
Markdown
|
---
|
||
|
|
repo: prj-forgejo-org-refactor
|
||
|
|
repo_flavor: project
|
||
|
|
project_status: draft
|
||
|
|
started: "2026-08-11"
|
||
|
|
reviewed: "2026-08-11"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Project goal
|
||
|
|
|
||
|
|
## Outcome
|
||
|
|
|
||
|
|
Split the single `coulomb/` Forgejo organization into stewardship organizations
|
||
|
|
— `railiance`, `netkingdom`, `helixforge`, `binky`, `experimental`, with
|
||
|
|
`coulomb` retained for what genuinely belongs to it — so that organization
|
||
|
|
membership expresses **discoverability and responsibility** instead of
|
||
|
|
expressing nothing.
|
||
|
|
|
||
|
|
Today all 112 repositories with a Forgejo origin sit under `coulomb/`,
|
||
|
|
including `net-kingdom`, `helix-forge`, the whole `railiance-*` family, and the
|
||
|
|
`rail-*` / `rapp-*` / `reef-*` families. An organization that contains
|
||
|
|
everything draws no boundary and grants no useful access control.
|
||
|
|
|
||
|
|
The migration must complete **without breaking a running system**. That is the
|
||
|
|
hard part, and it is why this is a project rather than a workplan.
|
||
|
|
|
||
|
|
## Why this is deferred
|
||
|
|
|
||
|
|
Operator decision, 2026-08-11: seed now, execute later. The migration is only
|
||
|
|
safe once the surrounding structure is stable enough that side-effect
|
||
|
|
complications can be *tested for* rather than discovered in production. The
|
||
|
|
entry gate below makes that condition checkable instead of a feeling.
|
||
|
|
|
||
|
|
## Invariants
|
||
|
|
|
||
|
|
1. **No silent breakage.** Every reference that moves is inventoried before it
|
||
|
|
moves, and verified after.
|
||
|
|
2. **Organization membership is a stewardship grouping**, not a legal-entity
|
||
|
|
grouping and not a deployment grouping. Legal attribution stays with
|
||
|
|
`LICENSE`, copyright headers, and contribution records
|
||
|
|
(`contribution-convention_v0.1`), which survive repo moves. Deployment
|
||
|
|
grouping stays with rapp contexts, which are a separate dimension by
|
||
|
|
ratified decision (`d07ee5f9-90d6-4e04-85d7-772103bc95f0`, OAS P1).
|
||
|
|
3. **Reversible in stages.** No stage may leave the fleet in a state that
|
||
|
|
cannot be rolled back to the previous stage.
|
||
|
|
4. **The running cluster keeps running.** GitOps sync and image pulls must not
|
||
|
|
depend on a rename landing everywhere simultaneously.
|
||
|
|
5. **This repo hosts no production implementation.** It coordinates; the
|
||
|
|
changes land in the repos that own them.
|
||
|
|
|
||
|
|
## Known blast radius
|
||
|
|
|
||
|
|
Verified 2026-08-11. This is the evidence that made the effort project-sized.
|
||
|
|
|
||
|
|
| Surface | Finding | Why it hurts |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| Git remotes | 112 repos with `coulomb/` origin | Every local clone, every CI checkout |
|
||
|
|
| ArgoCD sources | `repoURL: https://forgejo.coulomb.social/coulomb/<repo>.git` in Application manifests | GitOps stops syncing if the path 404s |
|
||
|
|
| **Container registry** | `repository: forgejo.coulomb.social/coulomb/core-hub` in chart values | Forgejo's package registry is **org-scoped** — a rename moves image paths for **already-running pods**, so a node reschedule or restart can fail to pull long after the rename "succeeded" |
|
||
|
|
| Chart metadata | `home:` / `sources:` URLs in `Chart.yaml` | Cosmetic but fleet-wide |
|
||
|
|
| Submodules / CI configs | not yet inventoried | Unknown until the inventory task runs |
|
||
|
|
| Hostname | `forgejo.coulomb.social` is itself coulomb-branded | Open question: does the host stay while orgs split? |
|
||
|
|
|
||
|
|
The container-registry finding is the one that makes a naive "rename and fix
|
||
|
|
the remotes" approach unsafe. It is a *deferred* failure — it does not show up
|
||
|
|
at rename time, it shows up at the next pod reschedule.
|
||
|
|
|
||
|
|
## Success gates
|
||
|
|
|
||
|
|
- [ ] **G1 — Complete inventory.** Every `coulomb/` reference across git
|
||
|
|
remotes, ArgoCD sources, chart image paths, chart metadata, submodules,
|
||
|
|
and CI configs is enumerated by a re-runnable command, not by hand.
|
||
|
|
- [ ] **G2 — Org taxonomy agreed.** Each repo has an assigned target org with a
|
||
|
|
stated reason, and the criteria for assignment are written down so later
|
||
|
|
repos can be placed without re-litigating.
|
||
|
|
- [ ] **G3 — Redirect behavior verified.** Forgejo's actual behavior on org
|
||
|
|
rename / repo transfer — for Git paths *and* for the package registry —
|
||
|
|
is established by test against a throwaway org, not assumed from docs.
|
||
|
|
- [ ] **G4 — Rollback proven.** A repo can be moved and moved back with GitOps
|
||
|
|
and image pulls recovering, demonstrated on a low-stakes repo first.
|
||
|
|
- [ ] **G5 — Migration executed.** All repos sit in their target org.
|
||
|
|
- [ ] **G6 — No stale references.** The G1 inventory command returns clean, and
|
||
|
|
the cluster has survived a deliberate pod reschedule on migrated images.
|
||
|
|
- [ ] **G7 — Convention documented in a permanent home.** The org-assignment
|
||
|
|
criteria are promoted out of this project repo, so future repos are
|
||
|
|
created in the right org by default rather than by memory.
|
||
|
|
|
||
|
|
## Project retirement
|
||
|
|
|
||
|
|
This repository may be archived when:
|
||
|
|
|
||
|
|
1. every success gate has accepted evidence;
|
||
|
|
2. residuals have live work records in permanent repos;
|
||
|
|
3. the org-assignment convention is promoted to a durable home (canon or
|
||
|
|
`railiance-master`), per G7;
|
||
|
|
4. workplans are finished or cancelled with rationale;
|
||
|
|
5. a completion record exists under `history/`;
|
||
|
|
6. `project_status` is set to `completed`, then `archived`.
|