From a873fb29822c6bea16c151c557560b3ee0f2659c Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 10 Sep 2025 16:18:24 -0500 Subject: [PATCH] docs: capture finalized instructions for git workflow and bootstrap CI/CD; update TODO with runner revisit date --- TODO.md | 14 +++++++------ instructions/bootstrap-cicd.md | 36 +++++++++++++++++++++++++++++++++ instructions/git-workflow.md | 37 ++++++++++++++++++++++++++++++++++ 3 files changed, 81 insertions(+), 6 deletions(-) create mode 100644 instructions/bootstrap-cicd.md create mode 100644 instructions/git-workflow.md diff --git a/TODO.md b/TODO.md index 240df8a..8bd754e 100644 --- a/TODO.md +++ b/TODO.md @@ -3,7 +3,7 @@ TODO - Git workflow - [x] Questions gathered and answered - [x] Proposal iteration 2 drafted - - [ ] Finalize approval and capture in instructions/git-workflow.md + - [x] Finalize approval and capture in instructions/git-workflow.md - Branches - [x] Create integration, release, bootstrap from main @@ -13,15 +13,18 @@ TODO - CI/CD bootstrap - [x] Create branch bootstrap-cicd from main - [x] Add questions at questions/bootstrap-cicd.md - - [ ] Draft proposal based on answers - - [ ] Implement parity tooling: scripts/ci, ci.Dockerfile, docker/ci.compose.yml - - [ ] Add .gitea/workflows: ci.yml, release.yml, nightly.yml - - [ ] Add commitlint.config.cjs, .pre-commit-config.yaml, Makefile, CODEOWNERS + - [x] Draft proposal based on answers + - [x] Implement parity tooling: scripts/ci, ci.Dockerfile, docker/ci.compose.yml + - [x] Add .gitea/workflows: ci.yml, release.yml, nightly.yml + - [x] Add commitlint.config.cjs, Makefile + - [ ] Optional: add .pre-commit-config.yaml (defer for now) + - [ ] Optional: add CODEOWNERS - Protections & settings (in Gitea UI) - [ ] Protect main and integration with required checks - [ ] Enable auto-merge on green for feature→integration - [ ] Require 1 approval for integration→main + - [ ] Revisit enabling CI and protections after runners are ready (target: 2025-09-24) - Releases - [ ] Tag format vYYYY.MM.DD-HHMM (UTC) in release workflow @@ -29,4 +32,3 @@ TODO - Docs - [ ] Write docs/engineering/git-workflow.md with diagrams and examples - diff --git a/instructions/bootstrap-cicd.md b/instructions/bootstrap-cicd.md new file mode 100644 index 0000000..9ccf1fe --- /dev/null +++ b/instructions/bootstrap-cicd.md @@ -0,0 +1,36 @@ +Bootstrap CI/CD – Finalized Instructions (Phase 1) + +Goal +- Provide Docker‑only local checks and Git hooks with parity to future CI. CI workflows are prepared but may remain disabled until runners are ready. + +Requirements +- Docker + Docker Compose v2 on the development machine. No host packages beyond Docker are required. + +Local Checks +- Entry point: `scripts/ci ` where phase ∈ {format, lint, build, test, security, all}. +- Always runs inside the ci container using `docker/ci.compose.yml`. +- Tools pinned in `ci.Dockerfile`: shfmt, shellcheck, hadolint, yamllint, actionlint, prettier, markdownlint, commitlint. + +Hooks +- Install hooks: `make hooks-setup` (copies .githooks/* into .git/hooks). +- pre-commit: runs format + lint. +- commit-msg: runs commitlint (Conventional Commits). +- pre-push: runs build; test and security are present but currently no‑ops. + +Convenience Targets +- `make quick` → format + lint. +- `make check` → all phases. +- `make build` → compose validation. + +CI (Prepared, optional enablement later) +- .gitea/workflows/ci.yml: builds ci image; runs lint + build. +- .gitea/workflows/release.yml: on pushes to main, creates annotated tag vYYYY.MM.DD-HHMM (UTC). +- .gitea/workflows/nightly.yml: nightly lint run. +- All jobs run inside the ci image; no runner host package installs. + +Protected Checks (when CI is enabled) +- Protect: ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when they exist. + +Future Extensions +- Add tests/security phases per repo stack; enable CI branch protections once runners are ready; optionally add pre-commit framework as an alternative to native hooks. + diff --git a/instructions/git-workflow.md b/instructions/git-workflow.md new file mode 100644 index 0000000..8edd3cb --- /dev/null +++ b/instructions/git-workflow.md @@ -0,0 +1,37 @@ +Git Workflow – Finalized Instructions + +Scope +- Applies to this repo. Users typically consume tagged releases; contributors work via branches/PRs. CI/CD config is Gitea‑native; no GitHub/GitLab. + +Branches +- main: production; default branch. +- integration: development. Equivalent to develop. +- Working branches: feature/, fix/, chore/ from integration. +- Hotfix: hotfix/ from main; PR back to main, then forward-merge into integration. +- Release branch: not long‑lived. Optionally maintain a lightweight release branch fast‑forwarded to the latest tag via CI. + +Merges & Approvals +- Feature → integration: squash merge; bot auto‑merge on green (no human approval). Self‑merge allowed. +- integration → main: squash merge; require 1 approval; self‑merge not allowed. +- Force pushes disabled on protected branches; PRs required. + +Commit Style +- Conventional Commits for PR titles and commit messages. + +Versioning & Tags +- Calendar tags: vYYYY.MM.DD-HHMM (UTC). Annotated tags only on main after release. + +Release Flow +1) Feature branches PR into integration; checks pass → auto‑merge. +2) PR integration → main; 1 approval required; on merge, deploy and tag release. +3) Optional: CI fast‑forwards a release branch pointer to the new tag. + +Protected Checks (to enable when runners are ready) +- ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security if/when introduced. + +CODEOWNERS +- Keep minimal; require your review for integration → main. + +Notes +- No secrets required for this repo. Future repos should integrate Vault for secrets. +