Contribution Guidelines

Code of Conduct

Varve is committed to providing a welcoming, inclusive, and harassment-free experience for everyone. All participants — contributors, maintainers, and community members — are expected to:

• Be respectful of differing viewpoints, experience levels, and backgrounds
• Be inclusive — use welcoming language, avoid exclusionary jokes or comments
• Be constructive — focus on what is best for the project and the community
• Show empathy towards other community members, especially when giving feedback

Harassment, trolling, personal attacks, and other disrespectful behavior will not be tolerated. If you experience or witness unacceptable behavior, please report it by opening a GitHub issue or reaching out directly.

Getting Started

Before making your first contribution, set up your development environment. Varve requires:

• Rust toolchain — rustc 1.96+ / cargo 1.96+, available at ~/.cargo/bin
• pnpm 11.9+ — with PNPM_HOME configured and on your PATH
• Node 26+ with npm 11.16+
• WASM target installed for wasm32-unknown-unknown
• System dependencies — WebKitGTK 2.52+, GTK 3.24+, librsvg, openssl, fontconfig, fuse2

Read AGENTS.md for the complete environment setup guide, including toolchain verification, environment variables, and platform-specific notes. Run just check-env after setup to verify your toolchain is correct.

Finding Work

Not sure where to start? There are several ways to find work that fits your skills:

• Good first issues — tagged with the good first issue label on GitHub, these are small, well-scoped tasks ideal for new contributors
• Help wanted — issues labeled help wanted indicate the maintainer would appreciate community assistance
• Discussion threads — the GitHub Discussions board has ideas, feature requests, and architecture conversations seeking input
• Documentation gaps — if you find something confusing or undocumented, improving it is always welcome

If you're interested in working on an issue, comment on it first to avoid duplicate work. The maintainer will assign it to you. For new features or significant changes, please open a discussion before writing code to ensure alignment with the project direction.

Making Changes

Follow this workflow for all contributions:

1. Create a branch — fork the repository and create a feature branch from master. Use a descriptive name like fix/text-alignment or feat/gradient-picker
2. Write tests first — Varve follows Test-Driven Development. Write failing tests before implementing your change. This applies to both Rust (cargo test) and TypeScript (pnpm test) code
3. Follow existing patterns — read the surrounding code to understand conventions. Match the code style, use existing libraries and utilities, and follow the project's architectural patterns
4. Keep changes focused — each pull request should address a single concern. If you find yourself fixing multiple unrelated issues, split them into separate PRs
5. Run just gate before committing — this runs the full quality gate: format check, lint, tests, token audit, and emoji audit. All must pass for code to be accepted

Pull Request Process

• Open against master — all pull requests should target the master branch
• Keep changes focused — a single PR should address one issue or feature. Smaller PRs are reviewed faster
• Write a clear description — explain what the change does, why it's needed, and how it was tested. Include screenshots or recordings for UI changes
• Reference related issues — use GitHub keywords like Closes #123 or Related to #456 in the description
• Be patient with review — Varve is developed by a solo developer. Review times may vary depending on availability. If you haven't received feedback in a week, feel free to politely bump the PR
• Respond to feedback — when changes are requested, address them promptly. If you disagree with a suggestion, explain your reasoning

Testing Requirements

All contributions must pass the following checks before they can be merged:

• pnpm test — all TypeScript/JavaScript tests across all packages must pass
• cargo test --workspace — all Rust workspace tests must pass (75+ tests across varve-core, varve-engine, varve-layout, varve-print, varve-sync, varve-trace)
• cargo test (Tauri) — desktop-specific tests (currently 7+) must pass
• pnpm typecheck — TypeScript type-checking must produce zero errors across all 15 packages
• pnpm lint — Biome must report zero errors on new and modified files
• pnpm audit:tokens — all 93+ WCAG-AA token pairs across all 3 themes must pass
• pnpm audit:emoji — zero emoji violations (emojis are not permitted anywhere in the codebase)
• pnpm format — code formatting must be consistent with the project style

These quality gates are not optional. Each catches a different class of error. If you're unsure how to resolve a failing check, ask in the PR or in GitHub Discussions.

Commit Messages

Varve follows the Conventional Commits format. This produces clear, structured commit history and enables automated changelog generation.

feat: add gradient fill support
fix: correct text alignment in multiline paragraphs
docs: update API reference for export module
refactor: extract color math to shared utility
test: add 12 coverage tests for curve editor
chore: update dependencies to latest versions

Common types include:

• feat: — a new feature or capability
• fix: — a bug fix
• docs: — documentation changes only
• refactor: — code restructuring without functional change
• test: — adding or updating tests
• chore: — build process, dependencies, tooling
• style: — formatting, whitespace, missing semicolons
• perf: — performance improvements

Keep the first line under 72 characters. Add a blank line then a detailed body for complex changes.

Licensing & DCO

Varve is licensed under the Functional Source License, Version 1.1, MIT Future License (FSL-1.1-MIT) with a change licence of MIT after two years. See the license page for full terms.

You retain copyright to your contributions. Once contributions open, by contributing you will agree that your work is distributed under FSL-1.1-MIT (and later under the MIT change licence). All contributions will require a Developer Certificate of Origin (DCO) sign-off.

To sign off, add Signed-off-by: Your Name <your.email@example.com> to your commit message. This certifies that you have the right to submit the work and that you understand it will be distributed under the project's licence. Use git commit -s to add this automatically.

If you have questions about licensing implications for your contribution, please ask in a discussion thread before submitting.

Non-Code Contributions

Code is only one way to contribute. Non-code contributions are equally valued and welcomed:

• Testing — test Varve on different platforms, file detailed bug reports with reproduction steps, verify fixes for regressions
• Documentation — improve existing docs, write tutorials, fix typos, add examples and screenshots
• Design — create UI mockups, design icons, improve the website, design marketing materials
• Accessibility review — audit the application for accessibility issues, test with screen readers, suggest improvements
• Translations — translate documentation, the website, or in-app text into other languages
• Community support — answer questions in GitHub Discussions, help other contributors, triage issues

No contribution is too small. A typo fix, a clearer error message, or a well-written bug report all make the project better for everyone.