Como contribuir para projetos de código aberto

Neste artigo, você aprenderá a contribuir com um projeto de software livre trabalhando em um exemplo. Vamos guiar você em fazer uma contribuição para o repositório github/docs: familiarizar-se com o repositório, encontrar uma área para contribuir, fazer e enviar uma pull request e trabalhar com mantenedores para que suas alterações sejam aceitas.

Orientando-se com as diretrizes do projeto

Antes de começar, é importante entender as diretrizes e os requisitos do projeto.

Por que as diretrizes são importantes?

Cada projeto tem as próprias convenções, padrões de codificação e processos de contribuição que você precisará seguir:

• Requisitos de estilo de código e formatação: como o código deve ser formatado, convenções de nomenclatura e regras de linting
• Diretrizes de teste: como executar testes, quais testes são necessários para novos recursos e convenções de teste
• Processo de pull request: como estruturar sua pull request, quais informações incluir e examinar as expectativas
• Configuração de desenvolvimento: como configurar seu ambiente de desenvolvimento local, dependências necessárias e processos de build
• Relatório de problemas: como relatar bugs, solicitar recursos ou fazer perguntas
• Canais de comunicação: onde fazer perguntas, discutir alterações ou obter ajuda de mantenedores

Reservar um tempo para ler isso poupará tempo, tanto para você quanto para os mantenedores, e aumentará a probabilidade de sua contribuição ser aceita.

Como localizar as diretrizes

Para acessar essas diretrizes e requisitos, navegue até a lista de verificação Community Standards na guia Insights. Para nosso exemplo, usaremos os Padrões da Comunidade github/docs.

• LEIAME: fornece uma visão geral do projeto. O conteúdo pode variar, mas o LEIAME ajuda os usuários e colaboradores a entender rapidamente o que é o projeto e como usá-lo, juntamente com links para outra documentação.

• Código de Conduta: define padrões de comportamento aceitáveis para colaboradores do projeto e membros da comunidade e estabelece expectativas e procedimentos para lidar com violações.

• Contribuição: fornece diretrizes e instruções para colaboradores do projeto. Ajuda a simplificar o processo de contribuição definindo expectativas claras e incentivando a colaboração consistente.

• Licença: define legalmente como outras pessoas podem usar, modificar e distribuir o código, protegendo os mantenedores e os usuários definindo termos claros para direitos autorais e permissões.

  • Por exemplo, o repositório github/docs usa a Licença Creative Commons para a documentação, que é um tipo de licença especificamente para trabalhos criativos. O código de software no github/docs está sob a licença MIT, que é uma licença permissiva que permite que qualquer pessoa use o código contido ali.
  • Você pode aprender sobre outros tipos de licença comuns com a ferramenta Choose a license.

• Política de segurança: fornece instruções para relatar vulnerabilidades de segurança aos mantenedores do repositório.

Examine cada um dos recursos disponíveis para o repositório github/docs.

Como localizar uma área para contribuir

Ao contribuir pela primeira vez para um projeto, começar com pequenas correções, como melhorias na documentação ou pequenos relatórios de bugs, pode ajudar você a se familiarizar com a base de código e o fluxo de trabalho do colaborador. Neste exemplo, você procurará problemas usando os rótulos help wanted e good first issue para detectar problemas específicos abertos para colaboradores externos. Em seguida, você usará o Copilot para ajudar contextualizar o problema.

1. Navegue até a guia Issues do repositório github/docs, use o filtro Labels e selecione "help wanted" para exibir problemas abertos que os mantenedores marcaram especificamente como precisando de ajuda da comunidade.

2. Examine a lista de problemas e encontre um em que você esteja interessado em trabalhar.

3. Na parte superior direita de qualquer página no GitHub, clique no botão ao lado da barra de pesquisa.

   A versão imersiva de página inteira do Copilot Chat é exibida.

4. Na caixa de prompt, insira o seguinte prompt:

   Text

   Can you summarize the key points and next steps from this issue?
   

5. Leia o contexto do Copilot fornecido, além dos comentários de outros colaboradores e mantenedores para ver se você deseja trabalhar no problema. Se você tiver perguntas específicas, poderá fazê-las diretamente no problema ou no Discord, IRC ou Slack do projeto, se aplicável.

Criando sua cópia de um projeto

Agora você está pronto para começar a contribuir. Como você não tem acesso para editar o repositório, primeiro precisa criar um fork: sua própria cópia do repositório em que você pode fazer alterações com segurança e enviá-las de volta para revisão do mantenedor. Neste exemplo, vamos analisar a criação de um fork do repositório github/docs.

1. Navegue até o projeto GitHub Docs em https://github.com/github/docs.

2. No canto superior direito da página, clique em Criar Fork.

3. Em "Proprietário", selecione o menu suspenso e clique em um proprietário do repositório com fork.

4. Por padrão, os forks são nomeados da mesma forma que os respectivos repositórios pai. Opcionalmente, para distinguir ainda mais o fork, no campo "Nome do repositório", digite um nome.

5. Opcionalmente, no campo "Descrição", digite uma descrição do fork.

6. Opcionalmente, selecione Copiar somente o branch PADRÃO.

   Para muitos cenários de bifurcação, como contribuir para projetos de código aberto, você só precisa copiar o branch padrão. Se você não selecionar essa opção, todos os branches serão copiados para o novo fork.

7. Clique em Criar bifurcação.

Como clonar um fork de um projeto

Agora você tem um fork do repositório github/docs em sua conta, mas precisa obtê-lo em seu computador local para começar a trabalhar em suas alterações.

1. No GitHub, acesse seu fork do repositório github/docs.

2. Acima da lista de arquivos, clique em Código.

   

3. Copie a URL do repositório.

   • Para clonar o repositório usando HTTPS, em "HTTPS", clique em .

   • Para clonar o repositório usando uma chave SSH, incluindo um certificado emitido pela autoridade de certificação SSH da sua organização, clique em SSH e em .

   • Para clonar um repositório usando a GitHub CLI, clique em GitHub CLI e em .

     

4. No Mac ou Linux, abra o Terminal. No Windows, abra o Git Bash.

5. Altere o diretório de trabalho atual para o local em que deseja ter o diretório clonado.

6. Digite git clone e cole a URL já copiada. Ela terá esta aparência, com seu nome de usuário do GitHub em vez de YOUR-USERNAME:

   Shell

   git clone https://github.com/YOUR-USERNAME/docs
   

7. Pressione Enter. Seu clone local estará criado.

Como fazer alterações em um branch de tópico

Agora é hora de fazer alterações! Antes de começar, é uma boa ideia criar um branch de tópico com um nome descritivo no fork. O uso de uma ramificação de tópico permite manter seu trabalho separado do branch padrão do repositório.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

Depois de alternar para o branch de tópicos, abra seu IDE ou editor de texto favorito e comece a codificar. Siga estas práticas recomendadas:

• Use Copilot para dar sugestões de código, dando a você confiança em suas alterações.
• Documente seu código e escreva testes. Eles geralmente são negligenciados e podem ajudar a garantir que sua contribuição seja mesclada.
• Faça ao Copilot perguntas sobre o problema para ajudar você a entender melhor os requisitos de implementação.
• Use o Copilot para examinar suas alterações para garantir que atendam aos requisitos de documentação e estilo de codificação do projeto.
• Use o Copilot para ajudar com instruções para compilar e testar o projeto em seu computador local.

Enviando e fazendo push das suas alterações

Quando suas alterações estão prontas, você pode preparar e efetuar commit delas em seu repositório. Ao escrever uma mensagem de commit, use um título de confirmação claro e conciso com menos de 50 caracteres que resume o que o commit faz. Agrupe alterações relacionadas em commits individuais quando possível, mas mantenha alterações não relacionadas em commits separados.

git add .
git commit -m "a short description of the change"

git add .
git commit -m "a short description of the change"

Tente manter linhas de descrição de commit com menos de 72 caracteres para melhorar a legibilidade. Quando você terminar de efetuar o commit das alterações locais e estiver pronto para enviar por push para o GitHub, envie suas alterações por push para o remoto.

git push

git push

Enviar uma solicitação de pull

Agora que você enviou suas alterações por push para GitHub, está pronto para abrir uma pull request. Você pode abrir uma pull request para revisão mesmo que não tenha finalizado as alterações feitas em seu branch. Abrir uma pull request no início do processo de contribuição informa os mantenedores e permite que eles forneçam comentários iniciais sobre suas alterações.

1. Vá para o repositório com fork no GitHub. Por exemplo, https://github.com/YOUR-USERNAME/docs.
2. Você deverá ver um prompt para "Comparar e efetuar a pull request" para o branch enviado recentemente. Clique.
3. Caso contrário, vá para a guia "Pull requests" e clique em "New pull request".
4. Verifique se o repositório base é github/docs e se o branch base é o branch principal (por exemplo, main).
5. Verifique se o repositório principal é seu fork (YOUR-USERNAME/docs) e se o branch de comparação é seu branch.
6. Digite um título e uma descrição para a pull request. Na descrição, faça referência ao problema que sua pull request fechará. Por exemplo, Closes: #15. Isso fornecerá contexto para sua pull request e fechará automaticamente o problema depois que a pull request for mesclada.

Como trabalhar com mantenedores de projeto

Depois que sua pull request for enviada, a próxima etapa será que um mantenedor de projeto examine e forneça comentários. Os mantenedores de projeto podem solicitar alterações para corresponder ao estilo ou à arquitetura da base de código, às vezes exigindo que você refatore partes substanciais do seu trabalho.

• Quando chegarem comentários sobre sua pull request, responda de modo imediato e profissional, mesmo que as críticas pareçam duras. Os mantenedores normalmente se concentram na qualidade do código.
• Se forem solicitadas alterações para sua pull request, não abra uma nova pull request para resolver as alterações. Manter a pull request atual aberta e fazer alterações nela ajuda a impedir que os mantenedores percam o contexto.
• Se sua pull request não for abordada por semanas, acompanhe com educação um comentário pedindo um retorno. Não mencione diretamente os identificadores dos mantenedores. Os mantenedores geralmente equilibram o trabalho de software livre com responsabilidades de turno integral, e compreender as restrições de tempo deles promove uma melhor colaboração.
• Se sua contribuição não for aceita, peça comentários aos mantenedores para que você possa ter esse contexto na próxima vez que quiser fazer uma contribuição.

Próximas etapas

Agora você sabe como identificar os problemas certos para trabalhar, criar contribuições que os mantenedores desejam mesclar e como navegar no processo de revisão de pull request. A comunidade de software livre em GitHub está pronta para sua perspectiva e habilidades únicas. Encontre um novo projeto empolgante, identifique um problema no qual trabalhar e comece a contribuir.