diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md new file mode 100644 index 0000000..8f3dff8 --- /dev/null +++ b/BOOTSTRAP.md @@ -0,0 +1,15 @@ +The purpose of this repository is to create a re-usable set of prompts for use in AI chat intefaces and with agentic AI. + +This file is being created at the very start of the repository in an attempt to provide full traceability. It will be passed to codex as a prompt. + +Codex instructions: + +- Remain in planning mode only. Ask questions and gather data. +- Create a propsoals directory and write out proposals to it for me to review and approve. +- Do not undertake any work unless I ask you for a proposal and I approve the proposal. +- Ask questions with numbers and allow them to be answered like 1:y 2:n or (for multiple choice) 1:a 2:b and so forth. +- Keep the chat message output short. Use proposal files that I can view in my editor (vsCode). +- The directory you are in is one level up from the git repository. This is so that git worktree can be used, to help mitigate issues with git branching. The repository is in a child directory called LLMScaffolding. + +Your first concreate action: +- Please help me establish a git workflow (via the proposal/approval process I have outlined). This workflow should follow best practices, it should presume the use of CI/CD via Gitea (Gitlab/Github are banned, never produce anything for those platforms). \ No newline at end of file diff --git a/instructions/.gitkeep b/instructions/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/instructions/.gitkeep @@ -0,0 +1 @@ + diff --git a/proposals/.gitkeep b/proposals/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/proposals/.gitkeep @@ -0,0 +1 @@ + diff --git a/proposals/git-workflow.md b/proposals/git-workflow.md new file mode 100644 index 0000000..bc485d1 --- /dev/null +++ b/proposals/git-workflow.md @@ -0,0 +1,121 @@ +**Git Workflow Proposal (Iteration 2)** + +- Scope: LLMScaffolding monorepo; solo human + AI-assisted roles; Gitea Actions runners on Debian 12 with Docker; envs: dev and prod only; on-demand releases; artifacts: for this repo docs/site, CI workflows, scripts. + +**Branch Strategy** + +- Permanent branches: `main` (prod), `integration` (dev). Yes, `develop == integration`. +- Working branches: `feature/`, `chore/`, `fix/` cut from `integration`. +- Release branches for this repo: NO long-lived release branch; publish via tags on `main`. Optionally maintain a fast‑forwarded `release` convenience branch pointing to the latest tagged release (CI will move it on each release). +- Hotfix branches: `hotfix/` cut from `main` for urgent fixes; PR back to `main` and forward‑merge to `integration`. + +**Protection Rules (Gitea)** + +- Protect `main` and `integration`: + - Require status checks: lint, format, tests, build, security scan, commitlint. + - Restrict direct pushes; require PRs. + - Approvals: + - feature → integration: allow bot auto-merge on green (no human approval required). + - integration → main: require 1 approval. + - Self-merge: allowed for feature → integration only; not allowed for integration → main. + - Disallow force-push; admins bypass only if needed. + +**Merge Strategy** + +- Use squash merges into `integration` and `main` to keep a linear history per change while preserving full details in the PR. Rationale: clean history for high-frequency deploys; Conventional Commits retained via squash title. +- Allow rebase for personal branches (unprotected) to keep them up-to-date. + +**Commit Conventions** + +- Adopt Conventional Commits. Enforce via: + - Commitlint on CI for PR titles. + - Optional local hook via `pre-commit` to run formatting/linters. + +**Versioning and Tags** + +- Calendar-based releases. Tag format: `vYYYY.MM.DD-HHMM` (UTC). Example: `v2025.09.10-1540`. +- Annotated tags only; created on `main` after successful deployment. +- Optionally create GitHub-style (Gitea) release objects with notes autogenerated from merged PRs since last tag. + +**Release Flow** + +- Normal release (most frequent): + 1) PR feature branches → `integration`; CI runs; on green, bot auto-merges (no approval). + 2) PR `integration` → `main` when ready; require 1 approval; checks re-run; merge deploys to prod. + 3) CI tags `main` with calendar version and publishes release notes; optionally fast‑forwards `release` branch to the tagged commit. +- Stabilization release (rare): + - If needed, cut `release/` from `integration`; accept only fixes; then PR into `main`; tag upon merge; forward‑merge back into `integration`. +- Hotfix: + - Branch `hotfix/` from `main`; PR back to `main`; tag and deploy; forward‑merge to `integration`. + +**Required CI Checks (Gitea Actions)** + +- Lint/Format: run linters and formatters; fail on diff. +- Tests: unit and integration (as applicable). +- Build: container/build artifacts as needed. +- Security: dependency scan (e.g., Trivy/Grype) and SAST linters where applicable. +- Conventional Commit/commitlint: enforce PR title style. + +**Gitea Actions Structure** + +- Place workflows under `.gitea/workflows/` (Gitea-native path). +- Example pipelines: + - `ci.yml` (PRs to any branch): lint, test, build, security, commitlint. + - `release.yml` (on push to `main`): tag creation, release notes, deploy, optional fast‑forward of `release` branch. + - `nightly.yml` (scheduled): dependency and vulnerability report. + +**Developer Parity & Hooks** + +- Single entrypoint script: `scripts/ci` orchestrates phases: `format`, `lint`, `test`, `build`, `security`, `all`. +- Dual mode execution for parity: + - Docker mode (preferred): `docker compose -f docker/ci.compose.yml run --rm ci scripts/ci `. + - Host mode (fallback): `scripts/ci ` runs native tools if Docker is unavailable. +- Git hooks (optional but provided): + - `pre-commit`: `scripts/ci format && scripts/ci lint && commitlint`. + - `pre-push`: `scripts/ci test && scripts/ci build && scripts/ci security` (fast scan profile). +- CI uses the same `scripts/ci` phases, ensuring checks in hooks and CI are equivalent. Contributors without Docker can rely on CI only; protected branches still enforce checks server-side. +- Convenience: `make check` (`all`), `make quick` (`format+lint`), `make test`, `make security`. + +Tooling for this repository (docs/scripts): `shfmt`, `shellcheck`, `hadolint`, `yamllint`, `markdownlint`, `prettier`, `actionlint`, `trivy`/`grype` (fast mode), `commitlint`. + +**Secrets and Runners** + +- No secrets required for this repo’s workflows; design pipelines to run without secrets. For future repos, plan a migration path to Hashicorp Vault rather than Gitea secrets. +- Runners: Debian 12 Docker-capable; set `container`-based jobs for isolation. + +**Branch Naming and Examples** + +- `feature/add-gitea-actions` +- `fix/typo-bootstrap-docs` +- `chore/ci-cache-tuning` +- `release/2025-09-10-1540` (if stabilization branch used) +- `hotfix/2025-09-10-1610` + +**Protections and CODEOWNERS** + +- Add minimal `CODEOWNERS` (you as owner) to enable required review on `integration → main`. +- Protect `main` and `integration` with required checks named: `ci / lint`, `ci / test`, `ci / build`, `ci / security`, `ci / commitlint`. + +**Defaults and Consumption** + +- Default branch: keep `main` as default for contribution clarity. Most users will consume tagged releases; CI also keeps `release` (if enabled) pointing at the latest tag for clone-and-go users. + +**What This Adds (upon approval)** + +- Repo config: + - Branch protections for `main`, `integration` per above. + - Default branch remains `main`. +- Files to add: + - `.gitea/workflows/ci.yml` + - `.gitea/workflows/release.yml` + - `.gitea/workflows/nightly.yml` + - `scripts/ci` (bash) with phases and Docker/host detection + - `docker/ci.compose.yml` with a `ci` service mounting the repo + - `ci.Dockerfile` pinning tool versions for parity + - `.pre-commit-config.yaml` wired to `scripts/ci` phases and `commitlint` + - `commitlint.config.cjs` (Conventional Commits) + - `Makefile` convenience targets + - `CODEOWNERS` + - `docs/engineering/git-workflow.md` (narrative + diagrams) + +If approved, I will scaffold the files and protections, and capture the finalized process in `instructions/git-workflow.md`. diff --git a/questions/git-workflow.md b/questions/git-workflow.md new file mode 100644 index 0000000..e2f8389 --- /dev/null +++ b/questions/git-workflow.md @@ -0,0 +1,132 @@ +Git Workflow – Questions + +Answer format: use concise codes, e.g. `1:b 2:a 3:sq`. + +1) Team size and roles? + - a) Solo + - b) Small (2–5) + - c) Medium (6–15) + - d) Large (16+) + +For now, solo (myself as a human) and I want to use AI for every other role (lawyer/cpa/software architect,developer/QA tester/devops/sre etc). Ultimately this repository / workflows etc will be used in dozens of projects I am managing, heavily leveraging AI. As such this is absolutely critical to get right early. + +2) Branching model? + - a) Git Flow (feature/develop/release/hotfix) + - b) Trunk-based (short-lived feature branches) + - c) Lightweight: main + release branches + +A looks good to me. Is devleop == integration (where feature branches get (auto) merged to? + +3) Merge strategy for protected branches? + - a) Squash merges (sq) + - b) Rebase-and-merge (rb) + - c) Merge commits (mc) + + I don't know what those mean, I'll leave it to your judgement as a senior level platform IT resource based on the other answers i've given. + +4) Versioning + tags? + - a) SemVer (e.g. v1.2.3) + - b) Calendar (e.g. 2025.09) + - c) None/undecided + + Calendar of YYYY-MM-DD with current time. + +5) Commit style? + - a) Conventional Commits + - b) Free-form + + Conventional Commits please. + +6) Required CI checks on PRs? + - a) Lint + Format + - b) Unit/Integration Tests + - c) Build/Package + - d) Security/Dependency scan + - e) All of the above + + E + +7) Environments and cadence? + - a) dev → stage → prod + - b) dev → prod only + - c) Other (specify) + - Release cadence: weekly/biweekly/on-demand? + + B + On-demand + +I have found that having any other environment besides (containerized/CI/CD etc) dev and prod leads to too many issues and tech debt. I expect to be releasing to prod dozens of times a day. + + +8) Code review policy? + - a) 1 approval + - b) 2 approvals + - c) CODEOWNERS required for affected paths + - d) Allow self-merge? (y/n) + + 1 approval + Yes Allow self merge + +9) Repo structure? + - a) Monorepo + - b) Multi-repo + - c) Uses submodules/worktrees (details?) + +I would want to set that per project/business. For this repository, monorepo (with three major focus areas: + +- Chief Technology And Product Officer +- Chief Operations Officer +- Chief Commons Officer) + +10) Gitea CI specifics? + - Runners available (OS/arch)? + - Secrets management approach? + - Required status checks to protect? + + Yes I have Linux Debian 12 x64 runners available that can spawn docker containers + Do not currently have secrets management in place but will be using Hashicorp Vault when I begin developing software soon. + +11) Release artifacts? + - a) Docker images + - b) Binaries/packages + - c) Helm charts/manifests + - d) Docs/site + + All of the above. For this repository only docs/site and gitea workflows and docker-compose files and shell/python scripts. + +12) Compliance needs? + - a) Signed commits (GPG/SSH) + - b) DCO sign-off + - c) Audit logs/approvals + + No compliance needs for this repo + +Notes: Add free-text under any item as needed. + +--- + +Follow-ups (please answer inline here): + +F1) Release branches: keep a permanent `release` branch, or use ephemeral `release/` branches only when needed for stabilization? Options: a) permanent `release` b) ephemeral `release/*` c) none (direct from `integration` to `main`). + +I am not sure. Can we do release/x.y.z ? Keep in mind, that for this repo in particular, it will be consumed by users downloading a tagged release since they will most likely be importing it into a new git repo and firing up an AI. Only folks that want to hack on the prompts/scripts/docker environment will clone / fork this repo or open a PR. I would say it's 95% users downloading a release, 5% hacking on the repo itself. Or should the release tags be kept in main? Or should we keep a long running release branch and set the default branch in gitea to release? I am agnostic to any particular solution, go with whatever works best for this repository. Now, for other repos, for the instructions, the release branching will be highly project/repo specific (as will monorepo or not etc). Remember, we have a bit of a bootstrapping issue here, where this repo needs to "eat it's own doggood" (as we are bootstrapping) but its ultimate goal is to be used by other repos/projects as a set of templates/core instructions. I struggle to keep it straight myself! Hence turning to AI! :) + +F2) Calendar tag format: prefer `vYYYY.MM.DD-HHMM` or `YYYYMMDD.HHMMSS`? If different, specify exact regex. + +The first one is fine + +F3) Auto-merge to `integration`: allow bots to auto-merge passing PRs from feature branches, or require manual approval every time? Options: a) auto-merge on green b) 1 approval required. + +a + +F4) Self-merge scope: allow self-merge on feature→integration only, or also on integration→main? Options: a) feature only b) both c) neither. + +a + +F5) Hotfixes: create `hotfix/` from `main` with direct PR back to `main` and a forward-merge to `integration` after release? Options: a) yes b) no. + +a + +F6) Secrets until Vault: OK to use Gitea organization/repo secrets for now with a migration plan to Vault later? Options: a) yes b) no (pause secret-using automation until Vault). + +b . This repo and the next couple I'm working on are all docs/sites and have no secrets management needed. \ No newline at end of file