jakman85andClaude Opus 4.8
de26a53d4b
- 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]>
65 lines
3.7 KiB
Markdown
65 lines
3.7 KiB
Markdown
# 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."
|