From ccf1d800a839f76789eb7053fd1801b8fe7ce239 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Han?= <seb@redhat.com>
Date: Wed, 3 Jun 2026 15:17:51 +0200
Subject: [PATCH] docs: add sccache shared build cache section to getting
 started
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a new "Developing" section to the MkDocs site with a getting started
guide that documents sccache setup for shared build caching. This helps
contributors avoid full dependency rebuilds when switching branches or
working across worktrees.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Sébastien Han <seb@redhat.com>
---
 docs/developing/getting-started.md | 74 ++++++++++++++++++++++++++++++
 mkdocs.yaml                        |  2 +
 2 files changed, 76 insertions(+)
 create mode 100644 docs/developing/getting-started.md

diff --git a/docs/developing/getting-started.md b/docs/developing/getting-started.md
new file mode 100644
index 0000000..dbc423d
--- /dev/null
+++ b/docs/developing/getting-started.md
@@ -0,0 +1,74 @@
+# Getting Started
+
+## Prerequisites
+
+- Rust toolchain (MSRV 1.85)
+- [pre-commit](https://pre-commit.com/)
+
+## Building
+
+Install pre-commit hooks and build the project:
+
+```console
+pre-commit install
+cargo build
+```
+
+## Testing
+
+```console
+cargo test
+```
+
+## Linting and Formatting
+
+```console
+cargo clippy --all-targets -- -D warnings   # lint
+cargo fmt                                     # format
+cargo fmt -- --check                          # check formatting only
+```
+
+To run all pre-commit hooks manually:
+
+```console
+pre-commit run --all-files
+```
+
+## Shared Build Cache with sccache
+
+[sccache] caches compiled artifacts so that switching
+branches, cleaning `target/`, or working across
+multiple git worktrees does not require rebuilding
+every dependency from scratch.
+
+### Setup
+
+[Install sccache][sccache-install], then add the
+following to your shell profile (`~/.bashrc`,
+`~/.zshrc`, etc.):
+
+```sh
+export RUSTC_WRAPPER=$(which sccache)
+```
+
+### Warming the cache
+
+After setting up sccache, run a full clippy pass in any
+worktree to populate the cache:
+
+```console
+cargo clippy --workspace --all-targets
+```
+
+Subsequent builds reuse the cached artifacts
+automatically. Cargo still prints `Compiling` /
+`Checking` for every crate, but cache-hit compilations
+complete in milliseconds instead of seconds.
+
+Check hit rates with `sccache --show-stats`. See
+[sccache usage][sccache-usage] for more configuration
+options.
+
+[sccache]: https://github.com/mozilla/sccache
+[sccache-install]: https://github.com/mozilla/sccache#installation
+[sccache-usage]: https://github.com/mozilla/sccache#usage
diff --git a/mkdocs.yaml b/mkdocs.yaml
index 8e66221..527c25e 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -92,6 +92,8 @@ markdown_extensions:
 nav:
   - Home: index.md
   - API Reference: api/index.md
+  - Developing:
+    - Getting Started: developing/getting-started.md
   - Community: community/index.md
 
 extra: