release: v0.0.5

COMMON/proposals/bootstrap-cicd.md

@@ -0,0 +1,68 @@
+**Bootstrap CI/CD Proposal (Phase 1)**
+
+- Scope: Local developer parity via Docker-first tooling and hooks, minimal CI placeholders (no runners required yet). Applies to this repo (docs/scripts/docker-compose), with an easy path to template for others.
+
+**Checks To Implement Now (Local via Docker)**
+
+- Stacks: shell, Dockerfiles/Compose, Markdown/Docs, YAML; Python/Node optional later.
+- Formatters/Linters:
+  - shell: shfmt + shellcheck
+  - docker: hadolint
+  - markdown: markdownlint + prettier
+  - yaml: yamllint + actionlint (for workflows)
+- Tests: none for now (lint-only baseline).
+- Security: skip for this repo now.
+
+**Execution Model**
+
+- Docker-only: all checks run inside a pinned `ci` image. Host only orchestrates Docker/Compose.
+- Single entrypoint: `scripts/ci` with phases: `format`, `lint`, `build` (compose validate), `test` (no-op for now), `security` (no-op), `all`.
+- Compose file: `docker/ci.compose.yml` defines `ci` service that mounts repo and executes `scripts/ci <phase>`.
+
+**Hooks Parity**
+
+- Provide Git hooks via pre-commit framework and native Git hooks:
+  - pre-commit: run `format`, `lint`, and commit message check (Conventional Commits).
+  - pre-push: run `build` (compose config validation) and keep `test`/`security` as no-ops for now.
+- Commit message style: Conventional Commits via `commitlint` rule-set; enforce in CI later and locally via `commit-msg` hook.
+
+**Minimal CI (Deferred Enablement)**
+
+- Workflows will be prepared but can stay disabled until runners are available:
+  - `.gitea/workflows/ci.yml`: mirrors local `lint` + `build` using the same `ci` image; triggered on PRs when enabled.
+  - `.gitea/workflows/release.yml`: on `main` merges, tags with `vYYYY.MM.DD-HHMM` and (optionally) creates release notes; can be enabled later.
+  - `.gitea/workflows/nightly.yml`: scheduled dependency/lint refresh; optional for later.
+- All jobs execute inside the `ci` container image; no host package installs.
+
+**Caching & Matrix**
+
+- Matrix: single Linux image for now.
+- Caching: enable Docker layer cache when CI runners are available; no special local caching required.
+
+**Concurrency & Timeouts (defaults for later)**
+
+- Cancel in-progress on same ref: enabled for PRs.
+- Job timeout: 30 minutes.
+
+**Protected Check Names (for later enforcement)**
+
+- `ci / lint`, `ci / build`, `ci / commitlint`. Tests/Security can be added when introduced.
+
+**Files To Add (upon approval)**
+
+- `scripts/ci` (bash) — phases and Docker/host detection (host executes Docker only).
+- `ci.Dockerfile` — pinned versions: shfmt, shellcheck, hadolint, yamllint, markdownlint-cli, prettier, actionlint, commitlint.
+- `docker/ci.compose.yml` — `ci` service to run checks.
+- `.pre-commit-config.yaml` — wire to `scripts/ci` phases; enable `commit-msg` hook for commitlint.
+- `commitlint.config.cjs` — Conventional Commits rules.
+- `.gitea/workflows/ci.yml`, `release.yml`, `nightly.yml` — prepared but can be disabled until runners are ready.
+- `Makefile` — `check`, `quick`, `lint`, `format`, `build` targets mapping to scripts.
+
+**Rollout Plan**
+
+1) Implement local tooling and hooks on `bootstrap-cicd`.
+2) Document quickstart in [docs/engineering/ci-cd.md](docs/engineering/ci-cd.md).
+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 [COMMON/bootstrap-cicd.md](COMMON/bootstrap-cicd.md).

COMMON/questions/bootstrap-cicd.md

@@ -0,0 +1,110 @@
+Bootstrap CI/CD – Questions
+
+Goal: define initial CI/CD checks and local Docker-parity hooks for this repo (docs/site, scripts, docker-compose), and a template usable by other repos.
+
+Answer style: short codes + notes, e.g. `1:a,c 2:b 3:docker`.
+
+1) Stacks present now (select all):
+   - a) Shell scripts
+   - b) Dockerfiles/Compose
+   - c) Markdown/Docs
+   - d) YAML (workflows/config)
+   - e) Python
+   - f) Node/JS
+   - g) Other (specify)
+
+   a,b,c,d potentially e. 
+
+2) Formatters/linters per stack:
+   - shell: a) shfmt b) shellcheck c) both
+   - docker: a) hadolint
+   - markdown: a) markdownlint b) prettier c) both
+   - yaml: a) yamllint b) actionlint (for workflows) c) both
+   - python (if used): a) black b) ruff c) pytest (tests)
+   - node (if used): a) eslint b) prettier c) jest (tests)
+   
+   shell: c
+   docker: a
+   markdown: c
+   yaml: c
+
+   I will leave python/node testing up to you. It isn't needed for this repo unless you create python scripts at some point.
+
+3) Testing scope now:
+   - a) none (docs/scripts only)
+   - b) smoke tests for scripts (bats/pytest-sh)
+   - c) unit tests for scripts (specify framework)
+
+   A (other then linting)
+
+4) Security scanning:
+   - a) trivy fs
+   - b) grype
+   - c) bandit (python)
+   - d) npm audit (node)
+   - e) skip for this repo
+
+   e
+
+5) Execution environment for CI:
+   - a) run inside repo’s `ci.Dockerfile`
+   - b) run on runner host with packages
+   - c) mix (specify)
+
+   All execution MUST be done in docker containers. Absolutely no work must be done on the host beyond git operations and docker orchestration.
+
+6) Matrix needs (now):
+   - a) none (single Linux image)
+   - b) multiple language versions (specify)
+   - c) OS matrix (Linux only for now?)
+
+   Um. I don't know. I think just a simle Linux environment can be assumed? 
+
+7) Caching:
+   - a) enable tool caches (pip/npm) in CI
+   - b) enable Docker layer cache
+   - c) none
+
+   I guess docker layer cache? It will be two weeks before I'm working on software (and therefore setup gitea CI runners etc). 
+
+8) Check names to protect on branches (final labels):
+   - a) ci / lint
+   - b) ci / test
+   - c) ci / build
+   - d) ci / security
+   - e) ci / commitlint
+
+   I don't know, leave it up to you
+
+9) Hooks parity:
+   - pre-commit: run format+lint+commitlint? (y/n) y
+   - pre-push: run test+build+security (fast profile)? (y/n) y
+
+10) Concurrency & timeouts:
+   - cancel in-progress on new commits to same PR? (y/n)
+   - default job timeout (minutes)?
+
+11) Release flow details:
+   - generate release notes from merged PRs since last tag? (y/n)
+   - attach built artifacts (site tarball, etc)? (y/n)
+
+12) Coverage gates (if tests exist):
+   - threshold % to require? (number or skip)
+
+13) Auto-merge bot to `integration`:
+   - bot account/name (or use Gitea built-in)?
+   - automerge conditions beyond green checks? (labels, size)
+
+14) Notifications:
+   - a) none
+   - b) email
+   - c) webhook/Chat (specify)
+
+15) Future extensibility:
+   - template these workflows for other repos? (y/n)
+   - segregate language-specific jobs behind conditions? (y/n)
+
+Notes: add any constraints about runners, container registry, or build tools.
+
+
+Lets just ignore all things CI for now? I'm brand new to CI. Use your best judgement/adopt best practices and/or ignore CI as needed. Do track that it's an outstanding item to go in depth on though. I don't want it to block moving forward with the dozen or so docs repos I need to use this LLM workflow with though.