12/10/2015
Como contribuir com um projeto no GitHub
Em 24/09/2015, o Rob Allen, mais conhecido no Twitter como @akrabat, escreveu um artigo sobre o tema: The beginner’s guide to contributing to a GitHub project.
Passo 1: Defina uma cópia de trabalho (working copy) no seu computador
Primeiramente, você precisa de um fork local do projeto na sua máquina, vá direto no GitHub e aperte o botão “fork”. Ele criará uma cópia do repositório em sua própria conta do GitHub, e você verá um aviso de que ele foi forkado abaixo do nome do projeto:
Agora, você precisa de uma cópia local. Procure por “HTTPS clone URL” ou “SSH clone URL” do lado direito do site e use esse endereço para fazer o clone local usando um terminal:
$ git clone git@github.com:akrabat/zend-validator.git
O resultado será parecido com este aqui:
Entre no diretório do novo projeto:
$ cd zend-validator
Por fim, você precisa definir um novo remoto (remote) apontando para o projeto original. Dessa forma, você consegue trazer as mudanças e colocá-las dentro de sua cópia local. Acesse o link do repositório original – ele está marcado com “Forked from” no topo da página do GitHub. Isso vai te levar para a página principal do GitHub do projeto, onde você encontra a “HTTPS clone URL” ou a “SSH clone URL” e deve usá-la para criar o novo remoto, que chamaremos de upstream.
$ git remote add upstream git@github.com:zendframework/zend-validator.git
Agora você tem dois remotos para esse projeto no disco:
- o origin, que aponta para seu fork do projeto no GitHub. Você tem acesso de leitura e gravação nesse remoto.
- o upstream, que aponta para o repositório principal do projeto no GitHub. Você só tem acesso de leitura nesse remoto.
Passo 2: Faça suas modificações
Essa é a parte divertida onde você começa a contribuir com o projeto. Em geral, é melhor começar arrumando um problema que está te atrapalhando ou algum bug que você encontrou no issue tracker do projeto. Se estiver procurando um lugar para começar, vários projetos usam a marcação “easy pick” label (ou alguma variação) para indicar que a issue pode ser resolvida por alguém novo no projeto.
Branch!
A regra número um é colocar cada pedaço do seu trabalho em seu próprio branch. Se o projeto estiver usando o git-flow, ele terá tanto um branch master quanto um branch develop. A regra padrão é que se você estiver consertando um bug, você criará um branch a partir do master, e se você estiver adicionando uma nova funcionalidade, criará um branch a partir do develop. Se o projeto tiver apenas o branch master, é de lá que você criará o branch novo. Alguns projetos, como o Slim, usam os nomes dos branches baseados em um número de versão (2.x e 3.x na situação deles). Nesse caso, escolha o branch que for relevante.
Neste exemplo, vamos supor que você está arrumando um bug no zend-validator, então vamos fazer um branch a partir do master:
$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update
Primeiramente, vamos garantir que estamos no branch master. Dessa forma o comando git pull irá sincronizar nossa cópia local com o projeto upstream, e o git push irá sincronizá-lo com nosso projeto forkado no GitHub. Por fim, criamos nosso novo branch. Você pode nomear o branch como quiser, mas ajuda se o nome for significativo. Incluir o número da issue também é útil. Se o projeto usar o git-flow tal qual o zend-validator, existem convenções de nomenclatura para prefixar os branches com “hotfix/” ou “feature/”.
Agora você pode fazer suas alterações.
Tenha certeza de que você apenas arrume o código onde estiver trabalhando. Não ceda à tentação de arrumar outras coisas que for achando durante suas alterações, pois assim seu PR (Pull Request) provavelmente será rejeitado. Certifique-se de que você faça commits em blocos lógicos. Cada uma das mensagens de commit deve ser sensata. Leia o artigo do Tim Pope A Note About Git Commit Messages (ou, se preferir em português do Brasil, desde 2011 em RogerioPradoJ.com: Uma Nota Sobre as Mensagens do Git Commit).
Passo 3: Crie o PR (Pull Request)
Para criar um PR, você precisa fazer o push de seu branch para o remoto origin e depois apertar alguns botões no GitHub.
Para fazer o push de um branch novo:
$ git push -u origin hotfix/readme-update
O comando cria um branch em seu projeto no GitHub. A flag -u faz a amarração desse branch com seu remoto; assim, no futuro, você pode simplesmente digitar git push origin.
Volte ao navegador e acesse o fork do seu projeto (https://github.com/akrabat/zend-validator no meu caso) e você verá que seu novo branch está listado no topo com um conveniente botão “Compare & pull request”:
Vá em frente e aperte o botão!
Se você vir uma caixa amarela como esta:
Clique no link que te levará ao arquivo CONTRIBUTING do projeto e o leia! Ele contém informação valiosa sobre como trabalhar com a base de código do projeto e ajudará para que sua contribuição seja aceita.
Na página a seguir, assegure que o “base fork” aponta para o repositório e para o branch correto. Então, certifique-se de fornecer um título bom e sucinto para seu pull request e explique por que você o criou na caixa de descrição. Adicione todos os números de issue caso os tenha.
Se você rolar a tela um pouco, verá um diff das suas alterações. Verifique mais de uma vez se ele contém o que era esperado.
Quando estiver satisfeito, aperte o botão “Create pull request” e você terá terminado.
Passo 4: Revisão dos mantenedores
Para que seu trabalho seja integrado ao projeto, os mantenedores fazem a revisão do que você fez e então solicitam alterações ou fazem o merge.
O artigo da Lorna Mitchell Code Reviews: Before You Even Run The Code trata dos pontos com que os mantenedores se preocupam. Por isso, vá lá dar uma lida e assegure que você facilitou as coisas para os mantenedores o máximo possível.
Resumindo
Isso é tudo! As partes fundamentais são as seguintes:
- Faça o fork do projeto & o clone local.
- Crie um remoto upstream e sincronize com sua cópia local antes de criar o branch.
- Faça um branch para cada pedaço separado de trabalho.
- Faça as alterações, escreva boas mensagens de commit e leia o arquivo CONTRIBUTING quando ele existir.
- Faça o push para seu repositório origin.
- Crie em novo PR (Pull Request) no GitHub.
- Responda a todos os feedbacks recebidos durante a revisão do código.
fonte: https://imasters.com.br/desenvolvimento/como-contribuir-com-um-projeto-no-github
