mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
Siddharth Kumar Sah
9f68960eda
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.
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# 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](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](https://www.conventionalcommits.org/) 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](https://siddharthksah.github.io/Stirling-Image/guide/developer). The short version:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://siddharthksah.github.io/Stirling-Image/guide/developer) 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](https://siddharthksah.github.io/Stirling-Image/guide/translations).
|
|
|
|
## 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](LICENSE).
|