Skip to content

Development Workflow

Jump to bottom
stbrumm edited this page Sep 8, 2026 · 2 revisions

Development Workflow

English · Deutsch · Español

This page describes how Rivulet development is organized and, in particular, how the local pre-push hook protects develop from broken pushes. The same workflow is documented in the repository at CONTRIBUTING.md; the repository copy is the normative source.

Basics

  • Work on a feature branch from develop, commit with conventional commit messages (feat:, fix:, docs:, ci:, ...).
  • Push and open a PR against develop.
  • CI runs the required checks: lint (fmt + clippy), the full test suite, pinning tests, smoke tests (RIST/SRT/OBS WebSocket), and more.
  • feat:/fix: (and releasable build/chore) commits automatically build and publish an alpha release.

Local pre-push hook

A committed git hook (.githooks/pre-push) mirrors the CI Lints (Fmt & Clippy) job locally, so a push can never break the required checks.

What it runs, in order:

  1. cargo fmt --all --check
  2. cargo clippy --workspace --all-targets -- -D warnings
  3. Fast-guard stage (default on): cargo test -p rivulet-core --test ci_pinning plus the Lints-job script self-tests (action-pin check, parity-checklist/release-notes/theme-contrast checks, generate-release-notes.sh --self-test).

Why -D warnings matters: a plain cargo clippy only warns on lints such as clippy::field_reassign_with_default. Commit 06792c6 shipped four GUI tests that were clean locally yet failed the CI Lints job; the hook uses the exact CI flags so that class of failure happens before the push.

Installation

Enable the hook once per clone:

git config core.hooksPath .githooks

After that, every git push runs the checks automatically.

Toggles

Goal Command
Skip the fast-guard stage for one push RIVULET_PRE_PUSH_FAST_TESTS=0 git push
Skip the whole hook for one push RIVULET_SKIP_PRE_PUSH=1 git push
Skip the whole hook (git-native) git push --no-verify

Troubleshooting

  • The hook does not run. The core.hooksPath setting is per clone — run git config core.hooksPath .githooks in the checkout you push from, then verify with git config core.hooksPath (must print .githooks).
  • bash not found on Windows during the syntax check. The hook itself runs from git, which uses Git for Windows bash. The ci_pinning guard pre_push_hook_is_valid_bash prefers an explicit C:\Program Files\Git\bin\bash.exe; when no Git Bash is installed the guard is skipped locally (CI on ubuntu still enforces it).
  • Clippy feels slow. The workspace clippy run is incremental — the first invocation compiles everything, later pushes are fast. Use RIVULET_PRE_PUSH_FAST_TESTS=0 if only the lint stage should run.
  • The push is blocked by the hook. Read the failing check output — cargo fmt/cargo clippy report the exact file and lint. Fix it, do not bypass; the same failure would break the CI Lints job.
  • Remove the hook again. git config --unset core.hooksPath restores the default .git/hooks directory (which contains no Rivulet hooks).

Last reviewed: 2026-09-03

Clone this wiki locally