Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (102 loc) · 4.4 KB

CONTRIBUTING.md

File metadata and controls

139 lines (102 loc) · 4.4 KB
Raw

contributing

use of AI

we follow the Astral AI policy verbatim. in short:

  • AI is welcome as a coding tool, but you own the code you publish and we own what we merge. the bar for contributions is the same regardless of how the diff was produced.
  • write your own issue descriptions, PR bodies, and review replies. do not paste AI-generated prose into conversations with maintainers. comments that look autogenerated will be hidden.
  • a human in the loop must understand the change. autonomous-agent PRs (no human review before submit) will be closed.
  • if you want to quote an AI interaction for context, put it in a > block, label it as AI, and add your own commentary. no long snippets.
  • non-native English speakers using AI to polish phrasing: great — just make sure the result is in your own voice. for translation, keep the original in your language and put the translation in a quote block.

please read the full policy at the link above before opening a PR.

local development

run maturin develop to build the rust extension and install it into the active virtualenv so you can import and test the python bindings locally.

python tests

run cargo run -- test to test tryke's own python code, using tryke

rust tests

we use cargo-nextest for the rust test suite. install it once:

cargo install cargo-nextest --locked

then run the suite with:

cargo nextest run --workspace --all-features

updating CLI docs

run cargo run -p tryke_dev --bin generate-cli-docs -- after changing the Rust CLI definitions or their help text. this rewrites docs/reference/cli.md from the clap metadata in crates/tryke/src/cli.rs.

pre-commit regenerates the file locally, and CI fails if the checked-in docs are out of sync with the Rust code.

updating snapshot tests

  1. run cargo nextest run — new or changed snapshots are written to crates/tryke/tests/snapshots/ as .snap.new files
  2. review pending snapshots: cargo insta review (interactive) or accept all: cargo insta accept
  3. commit the .snap files alongside code changes

playground

the browser playground lives in playground/. to run it locally:

cd playground
bun install
bun run dev

to deploy manually to Cloudflare Pages:

cd playground
bun run build
bunx wrangler pages deploy dist --project-name=tryke-playground

this creates a preview deployment at a unique URL (e.g. <hash>.tryke-playground.pages.dev). to deploy straight to production, add --branch main — this is just metadata passed to Cloudflare and works from any local branch:

bunx wrangler pages deploy dist --project-name=tryke-playground --branch main

pushes to main that touch the playground or WASM crates deploy automatically to production via the playground GitHub Actions workflow.

manual release

  1. start from a clean main branch with the latest CI passing

  2. run the release helper with the bump type:

    scripts/release.sh patch

    use minor or major instead of patch as needed.

    the helper checks that the Cargo workspace version and pyproject.toml's bump-my-version current_version match, computes the next v<version> tag, and prepends release notes to CHANGELOG.md with:

    uv run git-cliff --tag v0.2.0 --unreleased --prepend CHANGELOG.md

    if git-cliff cannot fetch GitHub PR metadata, export a GITHUB_TOKEN and rerun the helper.

  3. when the helper pauses, review and edit the generated CHANGELOG.md entry. press Enter to continue once it looks right.

  4. the helper runs markdown hooks for CHANGELOG.md, commits the changelog, runs bump-my-version to update pyproject.toml, the workspace version in Cargo.toml, and uv.lock, creates the release commit and v<version> tag, then pushes both:

    git push origin HEAD
git push origin v0.2.0

  5. the release workflow triggers automatically on the v* tag. it builds linux, macOS, and windows wheels, publishes them to PyPI with uv publish, and then creates the GitHub release notes from git-cliff using the tagged commits.

  6. monitor the workflow at https://github.com/thejchap/tryke/actions

  7. once the github-release job completes, verify PyPI has the new version:

    uv tool install --force tryke==0.2.0
tryke --version