Hacking on zizmor

Important

This page contains information on specific development processes. For more general information on how and what to contribute to zizmor, see our CONTRIBUTING.md.

General development practices

Here are some guidelines to follow if you're working on zizmor:

• Document internal APIs. zizmor doesn't have a public Rust API (yet), but the internal APIs should be documented as if they might become public one day. Plus, well-documented internals make life easier for new contributors.
• Write unit tests. It's easy for small changes in zizmor's internals to percolate into large bugs (e.g. incorrect location information); help us catch these bugs earlier by testing your changes at the smallest unit of behavior.
• Test on real inputs. If you're contributing to or adding a new audit, make sure your analysis is reliable and accurate on non-sample inputs.
• Use conventional commits. These are not mandatory, but they make it easier to quickly visually scan the contents of a change. Help us out by using them!

Requirements

zizmor's only development requirement the Rust compiler.

You can install Rust by following the steps on Rust's official website.

Building zizmor locally

zizmor is a pure Rust codebase, and can be built with a single cargo build:

git clone https://github.com/woodruffw/zizmor && cd zizmor
cargo build
# cargo run -- --help also works
./target/debug/zizmor --help

Similarly, you can build the developer-only documentation with cargo doc:

# build only
cargo doc

# build and open in the local browser
cargo doc --open

Linting

zizmor is linted with cargo clippy and auto-formatted with cargo fmt. Our CI enforces both, but you should also run them locally to minimize unnecessary review cycles:

cargo fmt
cargo clippy --fix

Testing

zizmor uses cargo test:

cargo test

Building the website

zizmor's website is built with MkDocs, which means you'll need a Python runtime to develop against it locally.

The easiest way to do this is to use uv, which is what zizmor's own CI uses. See the uv docs for installation instructions.

Once you have uv, run make site in the repo root to build a local copy of zizmor's website in the site_html directory:

make site

Alternatively, for live development, you can run make site-live to run a development server that'll monitor for changes to the docs:

make site-live

With make site-live, you should see something roughly like this:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.40 seconds
INFO    -  [22:18:39] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [22:18:39] Serving on http://127.0.0.1:9999/zizmor/
INFO    -  [22:18:40] Browser connected: http://127.0.0.1:9999/zizmor/development/

Visit the listed URL to see your live changes.

Adding or modifying an audit

These docs could use help.

For now, please run cargo doc --open and refer to our internal documentation!