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]>
3.7 KiB
3.7 KiB
Contributing & Development Workflow
How work is version-controlled for this repository. This complements the governance rules in
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.mainholds only reviewed, completed work. Do not commit work-in- progress directly tomain. - Every change is a feature branch. Create
feature/<short-description>(orfix/…,docs/…) for any unit of work, commit there, then merge intomainwhen the work is complete and — for implementation work — its conformance tests pass (agents/definition-of-done.md). - Merge to
main= "done". Keepmainalways in a coherent, mergeable state.
Branch naming
feature/<slug>— new capability or spec areafix/<slug>— correctionsdocs/<slug>— documentation-only changeschore/<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); the.gitignoreguards 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, roadmap Phase 6 is pulled
early — see roadmap/phases.md). Once Gitea is up and stable, the workflow
shifts:
- Repos move to Gitea (
gitea.home.keithjackson.dev). This local repo is pushed up as the origin of record. - GitOps source migrates from local/bootstrap to Gitea: Flux reconciles the cluster from Gitea
(
docs/05-gitops-and-delivery.md). - 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); Renovate opens update PRs (docs/11-automated-updates.md). - 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), 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) regardless of where git is hosted. - "Done" remains a green, reproducible conformance test, not "merged."