Enforce Rust formatting: CI gate, pre-commit hook, rustfmt.toml

.githooks/pre-commit

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# Beacon pre-commit hook: reject commits containing unformatted Rust code.
+#
+# Mirrors the `fmt` job in .github/workflows/ci.yml so formatting problems are
+# caught locally instead of failing CI. Install it with `make hooks` (which
+# points core.hooksPath at .githooks/).
+#
+# Bypass for a single commit with `git commit --no-verify` if you must.
+
+set -euo pipefail
+
+# Nothing to check if no Rust files are staged.
+if ! git diff --cached --name-only --diff-filter=ACMR | grep -q '\.rs$'; then
+    exit 0
+fi
+
+if ! command -v cargo >/dev/null 2>&1; then
+    echo "pre-commit: cargo not found on PATH; skipping rustfmt check." >&2
+    exit 0
+fi
+
+if ! cargo fmt -- --check >/dev/null 2>&1; then
+    echo >&2
+    echo "pre-commit: Rust code is not formatted." >&2
+    echo "  Run 'cargo fmt' and stage the changes, then commit again." >&2
+    echo "  (Bypass with 'git commit --no-verify' if you really need to.)" >&2
+    echo >&2
+    exit 1
+fi

.github/workflows/ci.yml

@@ -8,6 +8,29 @@ permissions:
   contents: read
 
 jobs:
+  fmt:
+    name: Rustfmt
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Rust (1.91)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.91"
+          components: rustfmt
+
+      - name: Check formatting
+        # Plain `cargo fmt` (no --all) formats every workspace member but not
+        # their path dependencies, so the vendored beacon-binary-format
+        # submodule (excluded from the workspace) is skipped. It is formatted
+        # in its own upstream repository.
+        run: cargo fmt -- --check
+
   ci:
     name: Clippy, test, and build
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to Beacon
+
+Thanks for your interest in improving Beacon! This guide covers how to get a
+local build going and the checks your pull request needs to pass.
+
+Issues and pull requests are welcome on
+[GitHub](https://github.com/maris-development/beacon/issues). For larger
+changes, please open an issue first so we can discuss the approach.
+
+## Prerequisites
+
+Beacon is a Rust workspace pinned to the toolchain in
+[`rust-toolchain`](rust-toolchain) (currently **1.91**); `rustup` picks it up
+automatically.
+
+The repository uses a git submodule for the binary format crate, so clone
+recursively (or initialise it after cloning):
+
+```bash
+git clone --recursive https://github.com/maris-development/beacon.git
+# or, in an existing checkout:
+git submodule update --init --recursive
+```
+
+Some crates link against system libraries. On Debian/Ubuntu the build
+dependencies are:
+
+```bash
+sudo apt-get install -y \
+  build-essential capnproto cmake curl libclang-dev libhdf5-dev \
+  libnetcdf-dev libsqlite3-dev netcdf-bin protobuf-compiler sqlite3
+```
+
+## Build and test
+
+```bash
+cargo build --workspace
+cargo test --workspace
+```
+
+The admin web UI lives under `clients/` and has its own build; see the
+[`Makefile`](Makefile) (`make help`) for convenience targets such as
+`make run` (serve the API + UI) and `make dev-ui` (Vite hot-reload).
+
+## Code style and checks
+
+CI runs three gates on every push and pull request
+([`.github/workflows/ci.yml`](.github/workflows/ci.yml)); run them locally
+before pushing.
+
+### Formatting
+
+All Rust code must be formatted with `rustfmt`. Beacon uses the **default Rust
+style** (pinned in [`rustfmt.toml`](rustfmt.toml)), which matches
+[Google's Rust style guide](https://google.github.io/styleguide/rust/) — the
+guide mandates rustfmt defaults rather than a custom profile.
+
+```bash
+cargo fmt            # format every workspace crate (or: make fmt)
+cargo fmt -- --check # what CI enforces; fails on unformatted code
+```
+
+Plain `cargo fmt` (rather than `cargo fmt --all`) formats the workspace
+members but not their path dependencies, so the vendored
+`beacon-binary-format` submodule — which lives in its own repository and is
+excluded from the workspace — is left alone.
+
+To catch formatting problems before you commit, install the pre-commit hook
+once per clone:
+
+```bash
+make hooks   # sets core.hooksPath to .githooks/
+```
+
+The hook (`.githooks/pre-commit`) runs the same `cargo fmt -- --check`
+whenever a commit touches Rust files and rejects unformatted changes. Bypass it
+for a single commit with `git commit --no-verify` if you must.
+
+### Lints and tests
+
+```bash
+cargo clippy --workspace --lib --bins --tests
+cargo test --workspace --no-fail-fast --lib --bins --tests
+```
+
+## Pull requests
+
+- Keep the branch focused; unrelated changes are easier to review separately.
+- Make sure `cargo fmt -- --check`, `cargo clippy`, and `cargo test`
+  pass — these are the same checks CI will run.
+- Reference any related issue in the PR description.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [AGPL-3.0 license](LICENSE).