Skip to Content
DocumentaçãoHow To Contribute With Pull Requests

Como Contribuir com Pull Requests

🌐 EN | PT | ES

Novo no GitHub e em pull requests? Este guia irá orientá-lo através dos conceitos básicos passo a passo.

O Que é um Pull Request?

Um pull request (PR) é como você propõe mudanças para um projeto no GitHub. Pense nisso como dizer “Aqui estão algumas mudanças que eu gostaria de fazer - por favor, revise e considere adicioná-las ao projeto principal.”

Antes de Começar

⚠️ Importante: Por favor, mantenha suas contribuições pequenas e focadas! Preferimos muitas mudanças pequenas e claras ao invés de uma única mudança massiva.

Obrigatório antes de submeter PRs:

Guia Passo a Passo

1. Fazer Fork do Repositório

  1. Vá para o repositório Synkra AIOS 
  2. Clique no botão “Fork” no canto superior direito
  3. Isso cria sua própria cópia do projeto

2. Clonar Seu Fork

# Substitua SEU-USUARIO pelo seu nome de usuário real do GitHub
git clone https://github.com/SEU-USUARIO/@synkra/aios-core.git
cd @synkra/aios-core

3. Criar uma Nova Branch

Nunca trabalhe diretamente na branch main! Sempre crie uma nova branch para suas mudanças:

# Criar e mudar para uma nova branch
git checkout -b fix/typo-in-readme
# ou
git checkout -b feature/add-new-agent

Dicas de nomenclatura de branches:

  • fix/descricao - para correções de bugs
  • feature/descricao - para novas funcionalidades
  • docs/descricao - para mudanças na documentação

4. Fazer Suas Mudanças

  • Edite os arquivos que você deseja alterar
  • Mantenha as mudanças pequenas e focadas em uma coisa
  • Teste suas mudanças se possível

5. Fazer Commit das Suas Mudanças

# Adicionar suas mudanças
git add .
 
# Commit com uma mensagem clara
git commit -m "Corrigir erro de digitação no README.md"

Boas mensagens de commit:

  • “Corrigir erro de digitação nas instruções de instalação”
  • “Adicionar exemplo de uso de novo agente”
  • “Atualizar link quebrado na documentação”

Más mensagens de commit:

  • “coisas”
  • “mudanças”
  • “atualizar”

6. Fazer Push para Seu Fork

# Fazer push da sua branch para seu fork
git push origin fix/typo-in-readme

7. Criar o Pull Request

  1. Vá para seu fork no GitHub
  2. Você verá um botão verde “Compare & pull request” - clique nele
  3. Selecione a branch de destino correta:
    • Branch next para a maioria das contribuições (features, docs, melhorias)
    • Branch main apenas para correções críticas
  4. Preencha a descrição do PR usando o template em CONTRIBUTING.md:
    • O Quê: 1-2 frases descrevendo o que mudou
    • Por Quê: 1-2 frases explicando o motivo
    • Como: 2-3 bullets sobre a implementação
    • Testes: Como você testou
  5. Referencie o número da issue relacionada (ex: “Fixes #123”)

8. Aguardar Revisão

  • Um mantenedor irá revisar seu PR
  • Eles podem pedir mudanças
  • Seja paciente e responsivo ao feedback

O Que Torna um Pull Request Bom?

✅ PRs Bons:

  • Mudam uma coisa por vez
  • Têm títulos claros e descritivos
  • Explicam o quê e por quê na descrição
  • Incluem apenas os arquivos que precisam mudar

❌ Evite:

  • Mudar a formatação de arquivos inteiros
  • Múltiplas mudanças não relacionadas em um PR
  • Copiar seu projeto/repositório inteiro no PR
  • Mudanças sem explicação

Erros Comuns a Evitar

  1. Não reformate arquivos inteiros - mude apenas o que é necessário
  2. Não inclua mudanças não relacionadas - foque em uma correção/feature por PR
  3. Não cole código em issues - crie um PR apropriado ao invés disso
  4. Não submeta seu projeto inteiro - contribua com melhorias específicas

Precisa de Ajuda?

Exemplo: PRs Bons vs Ruins

😀 Exemplo de PR Bom

Título: “Corrigir link quebrado para guia de instalação” Mudanças: Um arquivo, uma linha alterada Descrição: “O link no README.md estava apontando para o arquivo errado. Atualizado para apontar para o guia de instalação correto.”

😞 Exemplo de PR Ruim

Título: “Atualizações” Mudanças: 50 arquivos, codebase inteira reformatada Descrição: “Fiz algumas melhorias”

Lembre-se: Estamos aqui para ajudar! Não tenha medo de fazer perguntas. Todo especialista já foi iniciante um dia.

Git Workflow GuideIde Integration