diff --git a/CCO/.gitkeep b/CCO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CCO/.gitkeep @@ -0,0 +1 @@ + diff --git a/COMMON/README.md b/COMMON/README.md new file mode 100644 index 0000000..365c897 --- /dev/null +++ b/COMMON/README.md @@ -0,0 +1,13 @@ +COMMON + +Purpose +- Foundational, shared practices usable across projects. +- Opinionated but adaptable; intended as a base layer. + +Contents (initial) +- Git workflow (branching, merges, commit style) +- CI/bootstrap parity guidance + +Notes +- Keep content generic and reusable; project-specific overrides should live in the target repo. + diff --git a/COMMON/bootstrap-cicd.md b/COMMON/bootstrap-cicd.md new file mode 100644 index 0000000..25ee240 --- /dev/null +++ b/COMMON/bootstrap-cicd.md @@ -0,0 +1,21 @@ +Local CI Parity & Bootstrap + +Purpose +- Provide a portable CI toolchain via a Dockerized image and compose file so that format/lint/build checks run identically locally and in CI. + +Components +- `ci.Dockerfile` – builds the CI image with shellcheck, shfmt, hadolint, actionlint, yamllint, Node tools. +- `docker/ci.compose.yml` – runs the CI container mounting the repo at `/workspace`. +- `scripts/ci` – wrapper for phases: `format`, `lint`, `build`, `test`, `security`, `all`. +- Git hooks – `.githooks/*` installed via `scripts/setup-hooks`. + +Usage +- Install hooks: `make hooks-setup` +- Quick checks: `make quick` (format + lint) +- Full pass: `make check` (all phases) + +Notes +- Pre-commit hook runs format/lint and commit message checks. +- Pre-push hook runs build/test/security placeholders. +- CI workflow runs on integration and protected branches when runners are enabled. + diff --git a/instructions/git-workflow.md b/COMMON/git-workflow.md similarity index 60% rename from instructions/git-workflow.md rename to COMMON/git-workflow.md index 127a92f..5aa2774 100644 --- a/instructions/git-workflow.md +++ b/COMMON/git-workflow.md @@ -1,14 +1,14 @@ 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. +- Applies across projects. Contributors work via branches/PRs. CI/CD is Gitea‑native. Branches - main: production; default branch. Protected. - integration: development (unprotected; merges auto on green). - Working branches: `feature/`, `fix/`, `chore/` from integration. -- Hotfix: `hotfix/` from main; PR back to main, then forward-merge into integration. -- Release branch: ephemeral or lightweight `release/*`. Protect when present; optionally fast‑forward to latest tag via CI. +- Hotfix: `hotfix/` from main; PR back to main, then forward‑merge into integration. +- Release branch: ephemeral or lightweight `release/*`. Protect when present; may fast‑forward to latest tag via CI. Merges & Approvals - Feature → integration: squash merge; auto‑merge on green (no human approval). Self‑merge allowed. @@ -19,18 +19,20 @@ 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. +- Calendar tags: `vYYYY.MM.DD-HHMM` (UTC) for traceability. +- Release tags: semantic or milestone tags (e.g., `v0.0.1-Bootstrap`). 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. +3) Optional: CI fast‑forwards a `release` branch pointer to the new tag. -Protected Checks (to enable when runners are ready) -- On protected branches (`main`, `release/*`): ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security if/when introduced. +Protected Checks (enable when runners are ready) +- On protected branches (`main`, `release/*`): ci / lint, ci / build, ci / commitlint. Add ci / test and ci / security when introduced. CODEOWNERS -- Keep minimal; require your review for integration → main. +- Keep minimal; require review for integration → main. Notes -- No secrets required for this repo. Future repos should integrate Vault for secrets. +- No secrets in this base repo. Future repos should integrate Vault for secrets. + diff --git a/COO/.gitkeep b/COO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/COO/.gitkeep @@ -0,0 +1 @@ + diff --git a/CTO/.gitkeep b/CTO/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CTO/.gitkeep @@ -0,0 +1 @@ + diff --git a/DISCUSS.md b/DISCUSS.md new file mode 100644 index 0000000..0eef302 --- /dev/null +++ b/DISCUSS.md @@ -0,0 +1,43 @@ +DISCUSSION – Areas, Structure, Ownership + +Context +- This repo hosts generic, foundational practices reusable across projects. +- Areas: COMMON (shared practices), CTO (shared technical standards), COO (business ops), CCO (deferred; placeholder only). + +Decisions Confirmed +- Area directories are uppercase: COMMON, CTO, COO, CCO. +- Shared practices and base guidance live under COMMON. +- CCO is deferred for now; placeholder directory only. + +Open Questions to Confirm +- Naming conventions within areas + - File naming: keep kebab-case (e.g., git-workflow.md) or use TitleCase? + - Per-area `README.md` vs. `INDEX.md` expectations. +- Scope boundaries + - COMMON: include Git workflow, CI/bootstrap parity, templates (PR/issue), documentation style guide, ADR pattern, security/privacy baselines? + - CTO: preferred tech stacks, language/runtime versions, container base image policy, local dev environment patterns (devcontainers/Make), testing strategy, quality bars? + - COO: operating rhythm (cadences, ceremonies), roles/RACI, OKR/KPI templates, onboarding, procurement/vendor-lite guidance, documentation templates? + - CCO: when in scope, include customer journey templates, support/SLA baselines, enablement playbooks, feedback loops? Any overlap rules with COO/CTO? +- Consumers and audience + - Internal only or some content public-facing? Any confidentiality/compliance constraints (esp. COO/CCO)? +- Reuse strategy + - Copy into new repos vs. reference centrally? Provide “adoption guides” per area? Offer minimal vs. advanced profiles? +- Ownership & change control + - CODEOWNERS per area? Who approves updates across COMMON/CTO/COO? + - Labels and PR templates per area; contribution guidelines? +- Document shape and standards + - Prescriptive checklists vs. narrative guidance; include “10-minute quickstart” per area? + - Standardize front‑matter, headers, and ADR structure? +- Cross‑cutting policies + - Where to maintain shared policies (security, privacy, accessibility) — under COMMON? +- CI for docs + - Keep current markdown/yaml linters repo‑wide; add link checker/spellcheck? +- Migration of existing docs + - Which existing files beyond Git workflow and CI bootstrap should move under COMMON now vs. later (e.g., proposals, questions, RESUME.md, TODO.md)? + +Proposed Next Steps (pending answers) +- Seed per‑area README with scope, audiences, adoption guidance. +- Create COMMON/templates/ for reusable checklists, PR/issue templates, ADRs. +- Map/move additional shared docs into COMMON and update references. +- Define CODEOWNERS and contribution norms per area. + diff --git a/RESUME.md b/RESUME.md index 726e303..0f725c7 100644 --- a/RESUME.md +++ b/RESUME.md @@ -41,8 +41,8 @@ Branches on remote - git branch -f release main && git push -f origin release 8) Docs & parity -- Git workflow: instructions/git-workflow.md -- Local CI parity: instructions/bootstrap-cicd.md +- Git workflow: COMMON/git-workflow.md +- Local CI parity: COMMON/bootstrap-cicd.md 9) Defer CI enablement for two weeks - Track in TODO.md: Revisit enabling runners and protected checks on 2025-09-24 @@ -50,4 +50,3 @@ Branches on remote 10) Next tasks - Answer any outstanding questions in questions/* - On approval, implement further proposals and update instructions/* - diff --git a/TODO.md b/TODO.md index 15933ed..e5f2696 100644 --- a/TODO.md +++ b/TODO.md @@ -3,7 +3,7 @@ TODO - Git workflow - [x] Questions gathered and answered - [x] Proposal iteration 2 drafted - - [x] Finalize approval and capture in instructions/git-workflow.md +- [x] Finalize approval and capture in COMMON/git-workflow.md - Branches - [x] Create integration, release, bootstrap from main diff --git a/instructions/bootstrap-cicd.md b/instructions/bootstrap-cicd.md deleted file mode 100644 index 9ccf1fe..0000000 --- a/instructions/bootstrap-cicd.md +++ /dev/null @@ -1,36 +0,0 @@ -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/proposals/bootstrap-cicd.md b/proposals/bootstrap-cicd.md index 1c5b44b..57612f7 100644 --- a/proposals/bootstrap-cicd.md +++ b/proposals/bootstrap-cicd.md @@ -65,5 +65,4 @@ 3) Later: enable Gitea workflows when runners are ready; add protected checks. 4) Optionally expand with tests/security scanners and language stacks per repo. -If this matches your intent, I will scaffold the above on `bootstrap-cicd` and then capture the finalized process in `instructions/bootstrap-cicd.md`. - +If this matches your intent, I will scaffold the above on `bootstrap-cicd` and then capture the finalized process in `COMMON/bootstrap-cicd.md`.