diff --git a/apps/docs/guide/contributing.md b/apps/docs/guide/contributing.md index 0c3b9215..a6a5cdb8 100644 --- a/apps/docs/guide/contributing.md +++ b/apps/docs/guide/contributing.md @@ -1,29 +1,123 @@ --- -description: How to contribute to SnapOtter. Bug reports, feature requests, and community guidelines. +description: How to contribute to SnapOtter. Bug reports, feature requests, pull requests, and CLA requirements. --- # Contributing -Thanks for your interest in SnapOtter. Community feedback helps shape the project, and there are several ways to get involved. +Thanks for your interest in contributing. This guide covers how to participate, what we accept, and how to get started. -## How to contribute +## Ways to contribute -The best way to contribute is through [GitHub Issues](https://github.com/snapotter-hq/snapotter/issues): +### Issues (no setup required) -- **Bug reports** - Found something broken? Open a bug report with steps to reproduce, your Docker setup, and what you expected to happen. -- **Feature requests** - Have an idea for a new tool or improvement? Describe the problem you want solved and why it matters to you. -- **Feedback** - Thoughts on the UI, workflow, documentation, or anything else? We want to hear it. +- **Bug reports** - Something broken? Open a [bug report](https://github.com/snapotter-hq/snapotter/issues/new?template=bug_report.yml) with reproduction steps. +- **Feature requests** - Have an idea? Open a [feature request](https://github.com/snapotter-hq/snapotter/issues/new?template=feature_request.yml) describing the problem it solves. -## Pull requests +### Code (requires CLA) -We do not accept pull requests. All development is handled internally to maintain architectural consistency and code quality across the project. +We accept pull requests for: -If you have found a bug, open an issue describing it rather than submitting a fix. If you have a suggestion for how something should work, describe it in a feature request. Your input is valuable even without a code contribution. +| Type | Process | +|------|---------| +| Bug fixes | Open a PR directly (link the issue if one exists) | +| New translations | Open a PR directly (see [Translation Guide](/guide/translations)) | +| Documentation improvements | Open a PR directly | +| Test coverage improvements | Open a PR directly | +| New tools or features | Open an issue first, wait for the `approved` label before writing code | +| Refactors or architecture changes | Open an issue first, wait for the `approved` label before writing code | -## Forking +### What we will not accept -You are welcome to fork the project for your own use under the terms of the [AGPLv3 license](https://github.com/snapotter-hq/snapotter/blob/main/LICENSE). The [Developer Guide](/guide/developer) covers setup, architecture, and how to add new tools. +- Changes to CI/CD workflows, release config, or linter/compiler config +- PRs without a signed [Contributor License Agreement](#contributor-license-agreement) +- PRs over 400 lines of change (break large work into smaller PRs) +- Features that were not discussed and approved in an issue first +- Changes to `packages/ai/` without prior discussion + +## Contributor License Agreement + +Before we can merge your first PR, you must sign our [Individual CLA](https://github.com/snapotter-hq/snapotter/blob/main/CLA.md). This is a one-time requirement. + +**Why:** SnapOtter is dual-licensed (AGPLv3 + commercial). The CLA grants us the right to distribute your contributions under both licenses. You retain full copyright ownership of your work. + +**How:** When you open your first PR, the CLA Assistant bot will comment with a link. Click it, review the agreement, and sign with your GitHub account. Takes 30 seconds. + +If you are contributing on behalf of your employer and your employer retains IP rights over your work, contact contact@snapotter.com to arrange a Corporate CLA before submitting. + +## Getting started + +### Prerequisites + +- Node.js 22+ +- pnpm 9+ +- Python 3.11+ (only for AI tools) +- Docker (optional, for full integration testing) + +### Setup + +```bash +# Fork and clone +git clone https://github.com//snapotter.git +cd snapotter + +# Install dependencies +pnpm install + +# Start dev servers (web on :1349, API on :13490) +pnpm dev +``` + +### Running checks + +Before submitting a PR, ensure all checks pass locally: + +```bash +pnpm lint # Biome lint + format check +pnpm typecheck # TypeScript across monorepo +pnpm test # Vitest unit + integration tests +``` + +## Pull request process + +1. Fork the repo and create a branch from `main` (`feat/my-feature` or `fix/issue-123`) +2. Make your changes in focused, reviewable commits using [conventional commits](https://www.conventionalcommits.org/) +3. Add or update tests for your changes +4. Run `pnpm lint && pnpm typecheck && pnpm test` locally +5. Open a PR against `main` and fill out the template +6. Sign the CLA if prompted +7. Wait for CI to pass and a maintainer to review + +### Review expectations + +- We aim to respond to PRs within 7 days +- Small, focused PRs get reviewed faster +- If you have not heard back in 7 days, leave a comment pinging the thread +- We may request changes, suggest a different approach, or close the PR if it does not align with project direction + +### After your PR is merged + +Your contribution will be included in the next release and credited in the changelog. + +## Good first issues + +Looking for something to work on? Check our [good first issues](https://github.com/snapotter-hq/snapotter/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for beginner-friendly tasks, or [help wanted](https://github.com/snapotter-hq/snapotter/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) for larger items where we'd appreciate community help. + +## Code style + +- Biome handles formatting and linting (double quotes, semicolons, 2-space indent) +- Pre-commit hook runs `biome check --write` on staged files automatically +- If the linter complains, fix the code (do not modify Biome config) +- ES modules everywhere (`import`/`export`) +- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:` + +For full architecture details, see the [Developer Guide](/guide/developer). ## Security -If you discover a security vulnerability, please report it privately through [GitHub Security Advisories](https://github.com/snapotter-hq/snapotter/security/advisories/new) rather than opening a public issue. +**Do not open a public PR or issue for security vulnerabilities.** Report them privately through [GitHub Security Advisories](https://github.com/snapotter-hq/snapotter/security/advisories/new) or email contact@snapotter.com. See [SECURITY.md](https://github.com/snapotter-hq/snapotter/blob/main/SECURITY.md) for full details. + +## Questions? + +- [Documentation](https://docs.snapotter.com/) +- [Discord](https://discord.gg/hr3s7HPUsr) +- [GitHub Discussions](https://github.com/snapotter-hq/snapotter/discussions) diff --git a/apps/docs/guide/translations.md b/apps/docs/guide/translations.md index b9a08f07..f29dca44 100644 --- a/apps/docs/guide/translations.md +++ b/apps/docs/guide/translations.md @@ -75,23 +75,35 @@ function MyComponent() { } ``` -## Requesting a translation +## Contributing a translation -To request a new language or report a mistranslation, open a [GitHub Issue](https://github.com/snapotter-hq/SnapOtter/issues) with: +We welcome translation PRs directly. You can improve an existing locale or add a new one. -- The language name and locale code (e.g., German / `de`) -- Any specific strings or sections you want translated -- If you have a translation ready, paste the translated strings directly in the issue +To report a mistranslation without submitting code, open a [GitHub Issue](https://github.com/snapotter-hq/SnapOtter/issues) with the language, the incorrect string, and the suggested fix. -## How to create a translation (for your own fork) +::: tip +Translation PRs do not require prior approval. Fork the repo, make your changes, and open a PR. See the [Contributing Guide](/guide/contributing) for the full PR process and CLA requirement. +::: -### 1. Copy the reference file +## How to create or update a translation + +### 1. Fork and clone + +```bash +git clone https://github.com//snapotter.git +cd snapotter +pnpm install +``` + +### 2. Copy the reference file (new language only) + +Skip this step if you are improving an existing translation. ```bash cp packages/shared/src/i18n/en.ts packages/shared/src/i18n/XX.ts ``` -### 2. Translate the strings +### 3. Translate the strings Open your new file and translate every string value. Keep the object structure and keys exactly the same. @@ -115,7 +127,7 @@ Rules: - Arrays (`rotatingPhrases`, `progressMessages`) must have the same number of entries - Do not translate: SnapOtter, JPEG, PNG, WebP, EXIF, API, and other technical terms -### 3. Register the locale +### 4. Register the locale (new language only) Add your locale to `SUPPORTED_LOCALES` in `packages/shared/src/i18n/index.ts`: @@ -123,7 +135,7 @@ Add your locale to `SUPPORTED_LOCALES` in `packages/shared/src/i18n/index.ts`: { code: "xx", name: "Language Name", nativeName: "Native Name", dir: "ltr" }, ``` -### 4. Verify +### 5. Verify ```bash pnpm typecheck # catches missing or mistyped keys @@ -131,6 +143,10 @@ pnpm lint # formatting check pnpm dev # manually verify strings appear correctly ``` +### 6. Submit + +Open a PR against `main` with a title like `feat(i18n): add Swedish translation` or `fix(i18n): correct German typos`. The CLA bot will ask you to sign on your first contribution. + ## Adding new translation keys When adding a new feature that needs new UI strings: