External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update docs site to welcome pull requests and translations

Browse Source 
Rewrite contributing page to match new CONTRIBUTING.md with PR types,
CLA process, and good-first-issue links. Update translation guide to
encourage direct PRs instead of issue-only workflow.
This commit is contained in:
SnapOtter
2026-05-16 16:24:03 +08:00
parent 6e773751f6
commit 7d617a2675
2 changed files with 133 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/guide/contributing.md
+107 -13
View File
@@ -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/<your-username>/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)
apps/docs/guide/translations.md
+26 -10
View File
@@ -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/<your-username>/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: