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 aGitHub issue or reaching out directly.

Getting Started

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

• Rust toolchain — rustc 1.97+ / cargo 1.97+, 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

Code work is not currently being assigned to external contributors. For useful work today:

• Bug reports — search existing Issues, then provide a minimal reproduction and environment details
• Workflow proposals — use Discussions for feature ideas, architecture questions, and design feedback
• Cross-platform testing — record OS, architecture, package type, version, and exact actions
• Documentation and examples — point out stale or confusing content and suggest a replacement or workflow recipe

Please do not start an implementation based only on an issue label. For a future feature or significant change, open a Discussion first so the scope and direction can be agreed before code is written.

Making Changes When Code Opens

Once external code contributions reopen, follow this workflow:

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 the narrowest useful tests — follow the closest existing test pattern. Canvas, pointer, drag, and rendering changes also require real Playwright E2E coverage
3. Follow existing patterns — read the surrounding code and the nearest architecture document. Match the code style, use existing libraries and utilities, and follow the project's boundaries
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 the impact-aware gate — begin with pnpm verify:plan, then run pnpm verify:affected and record the exact commands in the pull request

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

Validation is selected by impact. The affected plan may add package tests, typechecks, audits, or E2E coverage:

• pnpm verify:plan — inspect the selected checks before running them
• pnpm verify:affected — default Tiers 0–4 validation for the affected closure
• Feature-specific checks — for example pnpm test:website, pnpm audit:docs, pnpm audit:tokens, or a scoped Playwright test
• Full gate only when escalated — pnpm verify:full requires VARVE_FULL_GATE_REASON and is reserved for high-impact changes or an explicit request

Skipping a selected affected check is not a valid shortcut. If a check fails or the plan looks broader than the change, include the output in the pull request and ask in GitHub Discussions rather than silently omitting it.

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 theFunctional Source License, Version 1.1, MIT Future License(FSL-1.1-MIT) with a change licence of MIT after two years. See thelicense 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 adiscussion 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.