tegwick
660c429838
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0e782-9f45-7382-afff-77ad665b88ec
115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
---
|
|
repo: prj-forgejo-org-refactor
|
|
repo_flavor: project
|
|
project_status: draft
|
|
started: "2026-08-11"
|
|
reviewed: "2026-09-28"
|
|
---
|
|
|
|
# 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.
|
|
|
|
At the August 11 seed review, 112 repositories with a forge origin sat under `coulomb/`,
|
|
including `net-kingdom`, `helix-forge`, the whole `railiance-*` family, and the
|
|
`rail-*` / `rapp-*` / `reef-*` families. An organization that contains
|
|
everything draws no useful stewardship boundary. The September 28 local scan
|
|
finds 151 `coulomb` origins; neither count is a current server census.
|
|
|
|
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 in `ORGREF-WP-0001` makes that condition checkable instead of a feeling.
|
|
|
|
Reviewed September 28: the family validator runs green locally; fresh deployable
|
|
coverage, a stable full reference inventory and transfer rollback proof remain
|
|
missing. Authorized preparation has now produced a partial repeatable inventory
|
|
and stewardship matrix; T01/T02 wait on the documented evidence and decisions.
|
|
Fresh platform coverage reports 52 unclaimed workload names. T03 onward stays deferred. See the
|
|
[readiness review](history/2026-09-28-readiness-review.md), including the circular
|
|
dependency between the rollback prerequisite and T04. Preparation artifacts:
|
|
[inventory](inventory/README.md), [taxonomy](taxonomy/README.md), and
|
|
[preparation record](history/2026-09-28-preparation.md).
|
|
|
|
## 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
|
|
|
|
Historical seed evidence, 2026-08-11. Reconcile current endpoints and runtime
|
|
version before using it: forge owner docs still distinguish Gitea operation from
|
|
a future Forgejo migration. The org split does not include that product migration.
|
|
|
|
| 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** — changed or unavailable package paths can break a later node reschedule or restart; actual package transfer/redirect behavior remains unverified |
|
|
| 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.
|
|
Include package consumers, GitOps access policies, release/retention
|
|
inputs and rollback references; reconcile server repos with local clones.
|
|
- [ ] **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 reports no unexplained
|
|
operational references to moved paths (approved `coulomb` assignments and
|
|
immutable historical evidence are accounted for), 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`.
|