Contribuindo

Obrigado pelo seu interesse em contribuir. Este guia cobre como participar, o que aceitamos e como começar.

Formas de contribuir

Issues (sem configuração necessária)

• Relatórios de bugs - Algo quebrado? Abra um relatório de bug com passos de reprodução.
• Solicitações de recursos - Tem uma ideia? Comece uma discussão para que a comunidade possa opinar e votar nela.
• Problemas de tradução - Encontrou uma tradução errada ou faltando? Abra uma issue de tradução.
• Problemas de documentação - Algo errado na documentação? Abra uma issue de documentação.

Código (requer CLA)

Aceitamos pull requests para:

Tipo	Processo
Correções de bugs	Abra um PR diretamente (referencie a issue, se houver)
Novas traduções	Abra um PR diretamente (veja o Guia de Tradução)
Melhorias na documentação	Abra um PR diretamente
Melhorias na cobertura de testes	Abra um PR diretamente
Novas ferramentas ou recursos	Comece uma discussão primeiro; um mantenedor converte ideias aprovadas em uma issue rastreada antes de você escrever código
Refatorações ou mudanças de arquitetura	Comece uma discussão primeiro e aguarde a aprovação de um mantenedor antes de escrever código

O que não aceitamos

• Mudanças em workflows de CI/CD, configuração de release ou configuração do linter/compilador
• PRs sem um Contributor License Agreement assinado
• PRs com mais de 400 linhas de alteração (divida trabalhos grandes em PRs menores)
• Recursos que não foram discutidos e aprovados antes
• Mudanças em packages/ai/ sem discussão prévia

Contributor License Agreement

Antes de podermos fazer merge do seu primeiro PR, você precisa assinar nosso CLA Individual. Este é um requisito único.

Por quê: O SnapOtter tem licença dupla (AGPLv3 + comercial). O CLA nos concede o direito de distribuir suas contribuições sob ambas as licenças. Você mantém a titularidade total dos direitos autorais do seu trabalho.

Como: Quando você abrir seu primeiro PR, o bot CLA Assistant comentará com um link. Clique nele, revise o acordo e assine com sua conta do GitHub. Leva 30 segundos.

Se você está contribuindo em nome do seu empregador e ele detém os direitos de propriedade intelectual sobre seu trabalho, entre em contato com [email protected] para providenciar um CLA Corporativo antes de enviar.

Começando

Pré-requisitos

• Node.js 22+
• pnpm 9+
• Python 3.11+ (apenas para ferramentas de IA)
• Docker (opcional, para testes de integração completos)

Configuração

# Fork and clone
git clone https://github.com/<your-username>/snapotter.git
cd snapotter

# Start Postgres + Redis for local dev
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
pnpm install

# Start dev servers (web on :1349, API on :13490)
pnpm dev

Executando as verificações

Antes de enviar um PR, garanta que todas as verificações passem localmente:

pnpm lint          # Biome lint + format check
pnpm typecheck     # TypeScript across monorepo
pnpm test          # Vitest unit + integration tests

Processo de pull request

1. Faça um fork do repositório e crie um branch a partir de main (feat/my-feature ou fix/issue-123)
2. Faça suas mudanças em commits focados e revisáveis usando conventional commits
3. Adicione ou atualize testes para suas mudanças
4. Execute pnpm lint && pnpm typecheck && pnpm test localmente
5. Abra um PR contra main e preencha o template
6. Assine o CLA se solicitado
7. Aguarde o CI passar e um mantenedor revisar

Expectativas de revisão

• Buscamos responder a PRs em até 7 dias
• PRs pequenos e focados são revisados mais rápido
• Se você não tiver retorno em 7 dias, deixe um comentário marcando a thread
• Podemos solicitar mudanças, sugerir uma abordagem diferente ou fechar o PR se ele não estiver alinhado com a direção do projeto

Depois que seu PR for mesclado

Sua contribuição será incluída no próximo release e creditada no changelog.

Boas primeiras issues

Procurando algo para trabalhar? Veja nossas boas primeiras issues para tarefas amigáveis a iniciantes, ou help wanted para itens maiores em que agradeceríamos a ajuda da comunidade.

Estilo de código

• O Biome cuida da formatação e do linting (aspas duplas, ponto e vírgula, indentação de 2 espaços)
• O hook de pre-commit executa biome check --write nos arquivos em stage automaticamente
• Se o linter reclamar, corrija o código (não modifique a configuração do Biome)
• Módulos ES em todos os lugares (import/export)
• Conventional commits: feat:, fix:, refactor:, docs:, test:, chore:

Para detalhes completos de arquitetura, veja o Guia do Desenvolvedor.

Segurança

Não abra um PR ou issue público para vulnerabilidades de segurança. Reporte-as em privado através dos GitHub Security Advisories ou por e-mail para [email protected]. Veja SECURITY.md para detalhes completos.

Dúvidas?

• Documentação
• Discord
• GitHub Discussions