From 3dc0166cf78823182dda1666acc55373489eaffd Mon Sep 17 00:00:00 2001 From: OneNoted Date: Wed, 15 Apr 2026 11:35:29 +0200 Subject: [PATCH] chore: run CI-equivalent checks before push Add a local CI script, an installable pre-push hook, and contributor docs so contributors can run the same high-signal format, lint, test, feature-matrix, packaging, and release-bundle checks locally before opening or pushing a PR. Constraint: Local workflow should stay as close to GitHub CI as practical without requiring a perfectly clean working tree Constraint: README-linked contributor docs should also ship in local package and release artifact docs Rejected: Keep pre-push guidance ad hoc in docs only | too easy to skip and drift from CI Confidence: high Scope-risk: narrow Reversibility: clean Directive: When CI steps change, update scripts/local-ci.sh, the hook installer, and contributor docs in the same change Tested: scripts/install-git-hooks.sh; scripts/local-ci.sh; cargo fmt --all -- --check; cargo clippy --all-targets -- -D warnings; cargo test; cargo check --no-default-features; cargo check --no-default-features --features osd; cargo check --no-default-features --features local-rewrite; cargo package --locked --allow-dirty; cargo check --no-default-features --features cuda; cargo check --no-default-features --features cuda,local-rewrite; scripts/build-release-bundle.sh Not-tested: Hook execution from a separate fresh clone --- .githooks/pre-push | 5 ++++ Cargo.toml | 1 + README.md | 1 + docs/contributing.md | 46 ++++++++++++++++++++++++++++++++ scripts/build-release-bundle.sh | 2 ++ scripts/install-git-hooks.sh | 11 ++++++++ scripts/local-ci.sh | 47 +++++++++++++++++++++++++++++++++ 7 files changed, 113 insertions(+) create mode 100755 .githooks/pre-push create mode 100644 docs/contributing.md create mode 100755 scripts/install-git-hooks.sh create mode 100755 scripts/local-ci.sh diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100755 index 0000000..4f47cf0 --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)" +exec "$repo_root/scripts/local-ci.sh" diff --git a/Cargo.toml b/Cargo.toml index 42f8032..5e847d3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,6 +16,7 @@ include = [ "docs/install.md", "docs/cli.md", "docs/troubleshooting.md", + "docs/contributing.md", "LICENSE", "NOTICE", "config.example.toml", diff --git a/README.md b/README.md index cb6793e..b62b3c2 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,7 @@ bindsym $mod+Alt+d exec whispers - [Installation guide](docs/install.md) — package choices, prerequisites, config path, and feature notes. - [CLI guide](docs/cli.md) — command groups, examples, and newer rewrite-policy commands. - [Troubleshooting](docs/troubleshooting.md) — `wl-copy`, `/dev/uinput`, cloud checks, and hang diagnostics. +- [Contributor workflow](docs/contributing.md) — install the local pre-push hook and mirror CI before opening a PR. - [config.example.toml](config.example.toml) — the canonical config template. ## Troubleshooting diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..5224bb2 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,46 @@ +# Contributor workflow + +Before you push or open a PR, run the local CI workflow so you catch the same failures that GitHub Actions would catch later. + +## Install the pre-push hook + +Run this once in your local clone: + +```sh +scripts/install-git-hooks.sh +``` + +That configures: + +- `core.hooksPath=.githooks` +- `.githooks/pre-push` to run `scripts/local-ci.sh` + +## Run the full local CI workflow manually + +```sh +scripts/local-ci.sh +``` + +By default it mirrors the repo's main CI workflow as closely as practical: + +- `cargo fmt --all -- --check` +- `cargo clippy --all-targets -- -D warnings` +- `cargo test` +- `cargo check --no-default-features` +- `cargo check --no-default-features --features osd` +- `cargo check --no-default-features --features local-rewrite` +- `cargo package --locked --allow-dirty` +- CUDA feature checks when `nvcc` is available +- `scripts/build-release-bundle.sh` + +## Useful overrides + +You can skip expensive local-only steps with environment variables: + +```sh +WHISPERS_LOCAL_CI_SKIP_CUDA=1 scripts/local-ci.sh +WHISPERS_LOCAL_CI_SKIP_PACKAGE=1 scripts/local-ci.sh +WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE=1 scripts/local-ci.sh +``` + +These are meant for local iteration only; the default workflow should stay as close to CI as possible before you open a PR. diff --git a/scripts/build-release-bundle.sh b/scripts/build-release-bundle.sh index 85b3793..f8a694b 100755 --- a/scripts/build-release-bundle.sh +++ b/scripts/build-release-bundle.sh @@ -72,6 +72,8 @@ install -Dm644 docs/cli.md \ "$stage_dir/$bundle_name/share/doc/whispers/docs/cli.md" install -Dm644 docs/troubleshooting.md \ "$stage_dir/$bundle_name/share/doc/whispers/docs/troubleshooting.md" +install -Dm644 docs/contributing.md \ + "$stage_dir/$bundle_name/share/doc/whispers/docs/contributing.md" install -Dm644 config.example.toml \ "$stage_dir/$bundle_name/share/doc/whispers/config.example.toml" install -Dm644 LICENSE \ diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh new file mode 100755 index 0000000..ad384f8 --- /dev/null +++ b/scripts/install-git-hooks.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_root" + +git config core.hooksPath .githooks +chmod +x .githooks/pre-push + +printf 'Configured git hooks path: %s\n' "$(git config --get core.hooksPath)" +printf 'Installed pre-push hook: %s/.githooks/pre-push\n' "$repo_root" diff --git a/scripts/local-ci.sh b/scripts/local-ci.sh new file mode 100755 index 0000000..885b377 --- /dev/null +++ b/scripts/local-ci.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_root" + +skip_cuda="${WHISPERS_LOCAL_CI_SKIP_CUDA:-0}" +skip_package="${WHISPERS_LOCAL_CI_SKIP_PACKAGE:-0}" +skip_release_bundle="${WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE:-0}" + +run_step() { + local label="$1" + shift + printf '\n==> %s\n' "$label" + "$@" +} + +run_step "Check formatting" cargo fmt --all -- --check +run_step "Clippy (default features)" cargo clippy --all-targets -- -D warnings +run_step "Test (default features)" cargo test + +run_step "Check no default features" cargo check --no-default-features +run_step "Check osd feature only" cargo check --no-default-features --features osd +run_step "Check local rewrite feature only" cargo check --no-default-features --features local-rewrite + +if [[ "$skip_package" != "1" ]]; then + run_step "Package crate" cargo package --locked --allow-dirty +else + printf '\n==> Skipping cargo package (--allow-dirty) because WHISPERS_LOCAL_CI_SKIP_PACKAGE=1\n' +fi + +if [[ "$skip_cuda" == "1" ]]; then + printf '\n==> Skipping CUDA checks because WHISPERS_LOCAL_CI_SKIP_CUDA=1\n' +elif command -v nvcc >/dev/null 2>&1; then + run_step "Check cuda feature only" cargo check --no-default-features --features cuda + run_step "Check cuda + local rewrite features" cargo check --no-default-features --features cuda,local-rewrite +else + printf '\n==> Skipping CUDA checks because nvcc is not available on PATH\n' +fi + +if [[ "$skip_release_bundle" != "1" ]]; then + run_step "Build release bundle" scripts/build-release-bundle.sh +else + printf '\n==> Skipping release bundle because WHISPERS_LOCAL_CI_SKIP_RELEASE_BUNDLE=1\n' +fi + +printf '\nAll local CI checks passed.\n'