SnapOtter/CONTRIBUTING.md

Contributing to Stirling Image

Thanks for your interest in contributing. There are many ways to help beyond writing code: reporting bugs, suggesting features, improving docs, and adding translations.

Issues

Before opening an issue, search existing ones to avoid duplicates.

• Bug reports: Include steps to reproduce, expected vs. actual behavior, and your environment (OS, Docker version, browser).
• Feature requests: Describe the problem you want solved, not just the solution. Context helps.
• Questions: Open an issue. We will do our best to respond quickly.

Pull requests

1. Open an issue first. Describe what you want to change and why. Wait for a maintainer to confirm the direction before writing code.
2. Fork the repo and create a branch from main.
3. Make your changes. Follow the conventions in CLAUDE.md (formatting, file structure, commit style).
4. Test your changes. Run pnpm test and pnpm lint before pushing. If you changed UI, run pnpm test:e2e too.
5. Submit a PR. Reference the issue number. Keep the title short and descriptive.

Commit messages

We use Conventional Commits for automated releases:

• feat: new feature (triggers a minor version bump)
• fix: bug fix (triggers a patch version bump)
• docs: documentation only
• test: adding or fixing tests
• refactor: code change that doesn't fix a bug or add a feature
• chore: maintenance (CI, deps, config)

Example: feat: add HEIC to PNG conversion support

What makes a good PR

• One logical change per PR. If you need to refactor something to add a feature, that can be one PR, but don't mix unrelated changes.
• Clear commit messages that explain why, not just what.
• Tests for new behavior when possible.
• No unrelated formatting changes (Biome handles formatting).

Development setup

Full instructions are in the Developer Guide. The short version:

git clone https://github.com/stirling-image/stirling-image.git
cd stirling-image
pnpm install
pnpm dev        # starts both frontend and backend

The frontend runs at http://localhost:1349 and proxies API calls to the backend on port 13490.

Running tests

pnpm lint           # Biome lint + format check
pnpm typecheck      # TypeScript across all workspaces
pnpm test           # unit + integration tests
pnpm test:e2e       # Playwright end-to-end tests

All of these run in CI on every PR. Make sure they pass locally first.

Adding a new tool

Tools follow a consistent pattern. You will need to touch three places:

1. Backend route in apps/api/src/routes/tools/ using createToolRoute() from the tool factory.
2. Frontend settings component in apps/web/src/components/tools/ with the tool's UI controls.
3. i18n entry in packages/shared/src/i18n/en.ts with the tool's name and description.

See the Developer Guide for a walkthrough.

Translations

We currently ship English only, but the i18n system is designed for easy extension. If you want to add a language, see the Translation Guide.

Code style

Biome handles formatting and linting. The rules are in biome.json and enforced by a pre-commit hook. Don't modify the Biome or TypeScript config files to silence warnings. Fix the code instead.

Quick summary:

• Double quotes, semicolons, 2-space indentation
• ES modules everywhere
• Zod for API input validation
• No any types without justification

License

By contributing, you agree that your contributions will be licensed under the MIT License.