Contributing

Contributions are welcome: bug reports, fixes, features and documentation. For anything larger than a small fix, please open an issue first, so we can agree on the approach before you invest time.

Development setup

You need Rust 1.85 or newer. With Nix, nix develop provides the toolchain.

git clone https://github.com/samox73/jotter
cd jotter
cargo run -- showcase.ipynb

showcase.ipynb exercises most features. To run it you need a Python with ipykernel, for example uv venv && uv pip install ipykernel numpy matplotlib tqdm.

Checks

CI runs these on every pull request; run them before you push:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

A few tests need a real kernel or Neovim and are marked #[ignore]. Run them with cargo test -- --ignored.

Commits

Commit messages follow Conventional Commits: feat: …, fix: …, docs: …, refactor: …. The changelog is generated from them.

Documentation

The site you’re reading lives in docs/ and is built with Starlight.

cd docs
npm ci
npm run dev        # live preview at http://localhost:4321/jotter/

• Pages are MDX files in docs/src/content/docs/.

• The Keybindings, Configuration and Command line pages are generated from the source code by jotter --generate, which npm run dev and npm run build run first. Edit HELP in src/ui.rs, the doc comments on Config in src/config.rs, or the Args in src/main.rs; not the generated files.

• A test fails if a config option has no doc comment.

• Clips and screenshots are recorded by docs/media/record.nu and committed in docs/public/media/. After a change that shows on screen, re-record the affected scenes and commit the results:

  nix develop .#docs -c nu docs/media/record.nu            # all scenes
  nix develop .#docs -c nu docs/media/record.nu hero plots # some

  Each scene is a short script in docs/media/scenes/; docs/media/lib.nu has the commands they use.

• The build fails on broken internal links.

Releases

1. Bump version in Cargo.toml (the Nix flake reads it from there) and run cargo check so Cargo.lock follows.

2. Regenerate the changelog, naming the new tag, and commit both:

   git cliff --tag v0.3.0 -o CHANGELOG.md
   git commit -am "chore: release v0.3.0"

3. Tag and push. The tag must match the version in Cargo.toml:

   git tag v0.3.0
   git push origin main v0.3.0

The release workflow then builds static binaries and .deb, .rpm and .apk packages for x86_64 and aarch64, creates the GitHub release with notes from git-cliff, and publishes the crate to crates.io.