Worktree docs contributing tools

docs/contributing.md

@@ -33,13 +33,36 @@ We welcome suggestions for improvements. Please use the issue tracker to submit
 
 ### Prerequisites
 
-- A container runtime (docker, podman, etc.)
+- [Go 1.26+](https://go.dev/dl/) (matches `go.mod`/CI) — required for `make build`, `make test`, `make vet`, `golangci-lint`, and `go install` of tools such as `dlv`
+- Docker with [Buildx](https://docs.docker.com/build/buildx/) and Compose — the `make upgrade-*-kind` and `make test` targets are docker-specific (`docker buildx build --load`, `kind load docker-image`, `docker compose`)
 - Git
 - [Kind](https://kind.sigs.k8s.io/)
 - [Helm](https://helm.sh/)
 - [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl)
 - [`yq`](https://github.com/mikefarah/yq)
 - `make`
+- [`golangci-lint`](https://golangci-lint.run/) (optional, recommended) — has no `make` target; run `golangci-lint run ./...` before pushing (CI enforces it)
+
+`controller-gen`, `kustomize`, and `setup-envtest` are installed automatically into `./bin` by the relevant `make` targets — no manual install needed.
+
+For UI development you also need [Node.js 24](https://nodejs.org/) and Yarn (classic) — see [`ui/AGENTS.md`](https://github.com/padok-team/burrito/blob/main/ui/AGENTS.md) for the UI workflow.
+
+#### Using mise (recommended)
+
+This repository ships a [`mise.toml`](https://github.com/padok-team/burrito/blob/main/mise.toml) that pins the exact versions of the tools above with [mise](https://mise.jdx.dev/), so every contributor gets an identical environment. After [installing mise](https://mise.jdx.dev/getting-started.html), run from the repository root:
+
+```bash
+mise install        # install all pinned tools (Go, Node, Yarn, kubectl, helm, kind, yq, golangci-lint, uv)
+```
+
+Docker (with Buildx and Compose), `make` and Git are system-level tools and are **not** managed by mise — install them yourself.
+
+`mise.toml` also defines a few tasks:
+
+```bash
+mise run lint          # golangci-lint run ./...
+mise run mkdocs-serve  # live docs preview (see "Building the Documentation Locally")
+```
 
 To run an instance of Burrito, you will need a Kubernetes cluster. This tutorial uses Kind as a local development Kubernetes cluster.
 
@@ -187,6 +210,26 @@ It is strongly recommended to create a GitHub token with no specific rights to b
 - Please follow the convention described by [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 - If you don't, the CI pipeline will fail.
 
+### Building the Documentation Locally
+
+The documentation site is built with [MkDocs](https://www.mkdocs.org/).
+
+If you use [mise](#using-mise-recommended), the toolchain (`uv`) is already available and a task is provided:
+
+```bash
+mise run mkdocs-serve   # installs deps into .venv, then serves at http://127.0.0.1:8000
+```
+
+Otherwise, with Python 3 directly:
+
+```bash
+pip install -r requirements.txt   # mkdocs + material theme + plugins
+mkdocs serve                      # live preview at http://127.0.0.1:8000
+mkdocs build --strict             # what CI runs; fails on broken links
+```
+
+CI also lints Markdown with `markdownlint-cli2` using `docs/.markdownlint.jsonc`.
+
 ## Additional Resources
 
 - [Controller-runtime documentation](https://pkg.go.dev/sigs.k8s.io/controller-runtime) (Burrito heavily relies on this package)

mise.toml

@@ -0,0 +1,34 @@
+[tools]
+# Language runtimes — matched to the Dockerfile build images so dev == build
+go = "1.26.3"      # Dockerfile golang builder (>= go.mod 1.26.0)
+node = "24.16.0"   # Dockerfile node builder / ci-frontend NODE_VERSION
+yarn = "1.22.22"   # classic, matches ui/yarn.lock
+
+# Kubernetes & dev CLIs — pinned for a reproducible environment
+kubectl = "1.36.2"      # aligns with ENVTEST_K8S_VERSION (1.36.0)
+helm = "4.2.0"
+kind = "0.32.0"
+yq = "4.53.3"           # mikefarah
+golangci-lint = "2.12.2"
+
+# Docs toolchain
+uv = "0.11.19"
+
+# Not managed here (system-level): docker + buildx/compose, make, git.
+
+[env]
+# Automatic virtualenv activation for the docs toolchain
+_.python.venv = { path = ".venv", create = true }
+
+[tasks.install]
+description = "Install documentation dependencies"
+run = "uv pip install -r requirements.txt"
+
+[tasks.mkdocs-serve]
+depends = "install"
+description = "Serve MkDocs documentation locally"
+run = "uv run mkdocs serve"
+
+[tasks.lint]
+description = "Run golangci-lint (no make target exists for it)"
+run = "golangci-lint run ./..."