docs: add methodology best practices section

Copilot · neilime · Copilot · commit d4b5e1430792 · 2025-12-20T08:43:05.000Z
Co-authored-by: neilime &lt;314088+neilime@users.noreply.github.com&gt;
diff --git a/application/docs/methodology/best-practices/devx-coding-rules.md b/application/docs/methodology/best-practices/devx-coding-rules.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+---
+
+# DevX Coding Rules
+
+Shared commit, branch, and pull request habits keep Hoverkraft repositories releasable and automation-friendly.
+
+## Conventional commits as the contract
+
+- Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `build:`, `ci:`).
+- Enforce the convention at PR time with the [`semantic-pull-request` workflow](../../../projects/ci-github-common/github/workflows/semantic-pull-request) or the workflow validation steps from the [Docker base images golden path](../golden-paths/docker-base-images/03-workflows-setup.md#workflow-overview).
+- Keep PR titles aligned with the conventional prefix to feed release automation and change logs.
+
+## Atomic, reviewable changes
+
+- Prefer **one change per pull request**: new feature, bug fix, refactor, or documentation update—avoid mixing concerns.
+- Keep PRs small and scoped so automated checks (lint, tests, previews) finish quickly and reviewers can focus on signal.
+- Update or add tests alongside code changes; if a behavior changes, document it in the PR body.
+
+## Semantic-release friendly history
+
+- Semantic version bumps flow from commit intent (`feat` → minor, `fix` → patch, `!` or `BREAKING CHANGE` → major). See the release walkthrough in the [Docker base images golden path](../golden-paths/docker-base-images/04-release-publishing.md#release-workflow-overview).
+- Tag releases from CI, not locally. Let automation publish release notes to keep provenance and SBOMs consistent.
+- Avoid squashing after approval if it would merge unrelated scopes—prefer merge strategies that preserve the meaningful prefixes used by release automation.
diff --git a/application/docs/methodology/best-practices/docker-buildkit-buildx.md b/application/docs/methodology/best-practices/docker-buildkit-buildx.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 3
+---
+
+# Dockerfile + BuildKit / Buildx
+
+Guidance for fast, reproducible image builds with security baked in.
+
+## Write Dockerfiles for reuse
+
+- Use multi-stage builds with explicit `ci` and `prod` targets as shown in the [application repository scaffold](../golden-paths/application/02-repo-scaffold.md#dockerfile).
+- Keep base images small and pinned; avoid `latest`. Set `USER` and use `--chown` when copying sources to prevent root-owned artifacts.
+- Externalize config via `ARG`/`ENV` and prefer `COPY` over `ADD`. Keep build arguments minimal and validated in CI.
+
+## Build with BuildKit and Buildx
+
+- Enable BuildKit features such as `RUN --mount=type=cache` for dependency caches and `--mount=type=secret` for one-off credentials. See the cache configuration in the [docker build workflow](../../../projects/ci-github-container/github/workflows/docker-build-images#workflow-call-inputs).
+- Export inline cache and provenance (`BUILDKIT_INLINE_CACHE=1`, `--provenance=true`) so downstream jobs can reuse layers and attach SBOMs, as done in the [release workflow](../../../projects/docker-base-images/github/workflows/release#usage).
+- Build multi-platform images with `docker buildx build --platform linux/amd64,linux/arm64` and push by digest; avoid rebuilding the same target in multiple jobs.
+
+## Secure the build
+
+- Do not bake secrets into images; inject at runtime via environment or secret stores. Prefer `cosign` or similar signing after build—see the [sign-images action](../../../projects/ci-github-container/actions/docker/sign-images/).
+- Run scanners (Trivy, Grype) on built images and fail on critical findings. Keep the Dockerfile linted with Hadolint rules mirrored in CI.
+- Keep a single source of truth for image names and tags; the [application hygiene checklist](../golden-paths/application/05-hygiene.md#operating-principles) shows how to keep Dockerfiles, CI, and Helm values aligned.
diff --git a/application/docs/methodology/best-practices/github-actions.md b/application/docs/methodology/best-practices/github-actions.md
@@ -0,0 +1,30 @@
+---
+sidebar_position: 2
+---
+
+# GitHub Actions & Workflow Practices
+
+Opinionated guardrails for reliable, secure, and maintainable workflows across Hoverkraft projects.
+
+## Design for reuse and clarity
+
+- Prefer reusable workflows (`workflow_call`) for common flows (lint, build, release); see the [`ci-github-*` workflow catalog](../../../projects/ci-github-common/) and the [application golden path](../golden-paths/application/ci-cd/github/index.md#shared-ci-__shared-ciyml).
+- Keep jobs single-responsibility (lint, test, package, deploy) and gate merges on the smallest necessary set of required checks.
+- Use matrices for platform/runtime coverage and [`needs`] to make dependencies explicit.
+
+## Security by default
+
+- Pin actions by commit SHA and scope the `permissions` block to the minimum needed per job.
+- Prefer OIDC + short-lived cloud credentials over long-lived secrets; avoid passing tokens into containers unless required.
+- Run `npm ci`/`pip install --no-cache-dir` inside build steps instead of reusing host caches that may contain untrusted files.
+
+## Performance and determinism
+
+- Cache dependencies and build outputs via `actions/cache` with explicit keys; reuse the cache hints from the [Docker build workflows](../../../projects/ci-github-container/github/workflows/docker-build-images#workflow-call-inputs) when building images.
+- Avoid duplicated work: promote artifacts between jobs (e.g., build once, test with the artifact) and use concurrency controls (`concurrency` group with `cancel-in-progress: true`) for branches.
+- Keep workflow inputs typed and validated; prefer small composite actions for repeated snippets instead of inlining large bash blocks.
+
+## Observability and recovery
+
+- Always upload failing logs, test reports, and artifacts needed for triage. The [release workflows](../golden-paths/docker-base-images/04-release-publishing.md#release-workflow-overview) show the pattern for publishing SBOMs and provenance alongside images.
+- Emit clear step names and link back to the documentation page for the workflow being used so contributors know the source of truth.
diff --git a/application/docs/methodology/best-practices/helm-chart.md b/application/docs/methodology/best-practices/helm-chart.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 4
+---
+
+# Helm Chart Practices
+
+Patterns for reliable, upgrade-friendly charts that stay in sync with built images.
+
+## Structure and values hygiene
+
+- Keep a single chart per deployable service; for multi-service repos, use an umbrella chart plus per-service subcharts as in the [application golden path scaffold](../golden-paths/application/02-repo-scaffold.md#helm-chart).
+- Treat `values.yaml` as defaults and keep environment overlays small; prefer typed inputs with `values.schema.json` to fail fast on unknown keys.
+- Version charts with the same cadence as application releases; surface the image tag (digest when possible) in values to make rollbacks deterministic.
+
+## Templates and security
+
+- Keep templates minimal and parameterized—avoid hard-coded hostnames, storage classes, or secret names.
+- Run containers as non-root, set resource requests/limits, and enable liveness/readiness probes. Mirror the container security posture defined in your Dockerfile.
+- Keep ingress, network policy, and service account definitions optional but documented with sensible defaults.
+
+## CI/CD alignment
+
+- Render and lint charts in CI (`helm lint`, `helm template`) before publishing. The [verification checklist](../golden-paths/application/04-verify.md#what-success-looks-like) shows the validation flow used in golden paths.
+- Publish charts from CI alongside the image build that produced the referenced tag; avoid manual `helm package` from workstations.
+- Document deployment workflows (e.g., Argo CD dispatch in [ci-github-publish](../../../projects/ci-github-publish/github/workflows/deploy-chart)) and link them from the chart README to avoid drift.
diff --git a/application/docs/methodology/best-practices/index.md b/application/docs/methodology/best-practices/index.md
@@ -0,0 +1,20 @@
+---
+sidebar_position: 3
+---
+
+# Best Practices
+
+Hoverkraft best practices centralize the opinionated guidance that shows up across our templates, reusable workflows, and golden paths. Use this section to align teams on shared defaults and to avoid duplicating recommendations in multiple docs.
+
+## How to use this section
+
+1. **Start here** to understand the recommended defaults.
+2. **Follow the links** to the detailed implementations in golden paths and reusable workflow docs.
+3. **Reference instead of duplicating**: when you document a best practice elsewhere, point back to this section.
+
+## Topics
+
+- **[DevX coding rules](./devx-coding-rules.md)** — Conventional commits, atomic changes, and semantic releases
+- **[GitHub Actions & workflow practices](./github-actions.md)** — Secure, maintainable, and cache-aware workflows
+- **[Dockerfile + BuildKit/Buildx](./docker-buildkit-buildx.md)** — Fast, reproducible image builds with caching and security defaults
+- **[Helm charts](./helm-chart.md)** — Chart structure, values hygiene, and release discipline
diff --git a/application/docs/methodology/index.md b/application/docs/methodology/index.md
@@ -35,6 +35,10 @@ Step-by-step golden paths for creating new repositories using Hoverkraft's reusa
 - **[Golden Paths Overview](./golden-paths/)**: Opinionated journeys for bootstrapping new projects
 - **[Docker Base Images Golden Path](./golden-paths/docker-base-images/)**: Create your own Docker base images repository with automated builds and semantic versioning
 
+### Best Practices
+
+- **[Best Practices](./best-practices/)**: Centralized guidance for coding standards, workflows, container builds, and Helm charts to keep recommendations consistent across repositories.
+
 ## Key Principles
 
 ### 1. Infrastructure as Code
