mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

Siddharth Kumar Sah 9f68960eda docs: rewrite README, add CONTRIBUTING.md, developer and translation guides

Rewrite README to remove AI writing patterns (em dashes, promotional
language, vague claims). Make Quick Start section explicit about default
credentials and forced password change. Add Contributing section linking
to CONTRIBUTING.md, developer guide, and translation guide.

Create CONTRIBUTING.md with issue guidelines, PR workflow, commit
conventions, and development setup. Add developer guide (dev setup,
project structure, how to add a tool) and translation guide (how the
i18n system works, step-by-step for adding a language) to VitePress
docs. Register both new pages in the docs sidebar.

2026-03-28 12:14:24 +08:00

3.7 KiB

Raw Blame History

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

Open an issue first. Describe what you want to change and why. Wait for a maintainer to confirm the direction before writing code.
Fork the repo and create a branch from main.
Make your changes. Follow the conventions in CLAUDE.md (formatting, file structure, commit style).
Test your changes. Run pnpm test and pnpm lint before pushing. If you changed UI, run pnpm test:e2e too.
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/siddharthksah/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:

Backend route in apps/api/src/routes/tools/ using createToolRoute() from the tool factory.
Frontend settings component in apps/web/src/components/tools/ with the tool's UI controls.
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.

3.7 KiB Raw Blame History