Establish dev workflow (feature-branch→main) and pull Gitea bootstrap earlier
- Add CONTRIBUTING.md: interim local-git rules (no work on main; every change a feature branch merged into main) and the target state (Gitea-hosted repos, GitOps source cutover, CI/CD via Gitea Actions running the Kyverno gate + Chainsaw conformance Job, PR merge gate). Note the self-hosted-git bootstrapping circularity + off-cluster mirror/backup mitigation. - AGENTS.md: add section 12 (version-control workflow). - docs/05: source-of-truth migration (local bootstrap -> self-hosted Gitea). - docs/13 + roadmap: reprioritize Gitea as bootstrapping-critical, onboarded early (WS-APPS step 2); nextcloud onboarding split out. - task-board: T-6.1a (gitea early), T-6.1b (source+CI migration to Gitea). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
1 parent
e8c555cfeb
commit
de26a53d4b
8 files changed
+126
-6
No files matched your search
@@ -0,0 +1,64 @@
|
||||
# Contributing & Development Workflow
|
||||
|
||||
How work is version-controlled for this repository. This complements the governance rules in
|
||||
[`AGENTS.md`](AGENTS.md) (what agents may/may not change) — this file covers *how changes land in
|
||||
git*.
|
||||
|
||||
## Interim state (now): local git, feature branches → main
|
||||
|
||||
There is **no remote git host on this network today**. (The previous `home-network` Gitea instance is
|
||||
gone from this network; the infrastructure it built still runs but is not reachable here.) So for now:
|
||||
|
||||
- **Local git only.** The repository lives on the workstation; there is no push target yet.
|
||||
- **No work on `main`.** `main` holds only reviewed, completed work. Do **not** commit work-in-
|
||||
progress directly to `main`.
|
||||
- **Every change is a feature branch.** Create `feature/<short-description>` (or `fix/…`, `docs/…`)
|
||||
for any unit of work, commit there, then **merge into `main`** when the work is complete and — for
|
||||
implementation work — its conformance tests pass ([`agents/definition-of-done.md`](agents/definition-of-done.md)).
|
||||
- **Merge to `main` = "done".** Keep `main` always in a coherent, mergeable state.
|
||||
|
||||
### Branch naming
|
||||
- `feature/<slug>` — new capability or spec area
|
||||
- `fix/<slug>` — corrections
|
||||
- `docs/<slug>` — documentation-only changes
|
||||
- `chore/<slug>` — tooling/repo housekeeping
|
||||
|
||||
### Commit hygiene
|
||||
- Small, single-responsibility commits; imperative subject lines.
|
||||
- Reference requirement IDs / ADR numbers / task-board IDs where relevant (they're stable across
|
||||
file moves).
|
||||
- **Never commit plaintext secrets** — secrets are SOPS-encrypted only ([`docs/07-security-and-secrets.md`](docs/07-security-and-secrets.md));
|
||||
the [`.gitignore`](.gitignore) guards common leak paths but is not a substitute for care.
|
||||
|
||||
## Target state (soon): Gitea-hosted, CI/CD-driven GitOps
|
||||
|
||||
The platform will **host its own git**. **Gitea is one of the first services brought online on the
|
||||
cluster** ([`docs/13-service-catalog.md`](docs/13-service-catalog.md), roadmap Phase 6 is pulled
|
||||
early — see [`roadmap/phases.md`](roadmap/phases.md)). Once Gitea is up and stable, the workflow
|
||||
shifts:
|
||||
|
||||
1. **Repos move to Gitea** (`gitea.home.keithjackson.dev`). This local repo is pushed up as the
|
||||
origin of record.
|
||||
2. **GitOps source migrates** from local/bootstrap to Gitea: Flux reconciles the cluster from Gitea
|
||||
([`docs/05-gitops-and-delivery.md`](docs/05-gitops-and-delivery.md)).
|
||||
3. **CI/CD runs in Gitea** (Gitea Actions): the Kyverno L0 policy gate and the trigger for the
|
||||
in-cluster Chainsaw conformance Job run as pipelines on push/PR
|
||||
([`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md)); Renovate opens
|
||||
update PRs ([`docs/11-automated-updates.md`](docs/11-automated-updates.md)).
|
||||
4. **Pull requests become the merge gate** into `main`, with CI (policy + conformance) required
|
||||
green before merge — the same no-work-in-main rule, now enforced by the platform instead of by
|
||||
convention.
|
||||
|
||||
### The bootstrapping caveat (self-hosted git is circular)
|
||||
Gitea runs *on* the cluster that Flux reconciles *from* Gitea — a chicken-and-egg. Handling:
|
||||
- Bring the cluster up from a **bootstrap source** (this local repo / an out-of-band source), stand
|
||||
up Gitea, then **cut Flux's source over to Gitea**.
|
||||
- Because a cluster loss would take its own git host with it, **Gitea is DR-critical**: its repos are
|
||||
backed up **off-cluster** ([`docs/04-storage-and-state.md`](docs/04-storage-and-state.md)), and an
|
||||
off-cluster mirror of the platform repo is kept so the platform can always be rebuilt from a source
|
||||
that outlives the cluster.
|
||||
|
||||
## What does not change
|
||||
- Specs remain **human-owned and immutable to agents** ([`AGENTS.md` §11](AGENTS.md)) regardless of
|
||||
where git is hosted.
|
||||
- "Done" remains a **green, reproducible conformance test**, not "merged."
|
||||
Reference in new issue
Block a user