Git e Github - Do clone ao pull request
Você tem uma conta no Github, acompanha projetos open source, gostaria de colaborar com algum deles, mas não sabe como fazer? Como criar uma nova feature? Como preparar o repositório? O que é git push?
Se você tem essas dúvidas, esse artigo é pra você!
Alguns devs já me perguntaram como seria o workflow correto para colaborar com um projeto open source. Como criar uma nova branch, porque fazer isso, como enviar um pull request, como saber se o que você está fazendo está de acordo com o propósito do repositório.
Seguindo a dica do Rômulo, esse artigo é para você que quer aprender desde o básico necessário de git, até a submissão de um pull request, com um ajuste ou nova funcionalidade para um projeto no Github!
Primeiros passos com Git
Eu poderia escrever aqui todos os passos necessários para você instalar o git, criar seu projeto, criar um repositório local, criar branchs, etc. Mas o Roger Dudler já fez um ótimo trabalho que você encontra nesse link, traduzido por brasileiros :)
Escolhendo o repositório
Após seguir os passos acima, você já estará apto para fazer alterações em qualquer projeto e submeter o seu pull request!
E a primeira coisa que você tem que fazer é clonar o repositório que você quer colaborar!
Mas qual repositório eu escolho?
Se você não sabe em qual repositório pode colaborar, acesse o perfil de seus amigos no Github, veja os repositórios que eles têm e/ou seguem, e escolha algum que utilize uma linguagem que você está familiarizado, ou que quer aprender.
Fuce no código que está no repositório. Ele está ali para que você possa aprender com ele. Baixe, teste, procure por falhas! Quando encontrar algo que possa ser melhorado, é hora de você fazer a sua parte e enviar um pull request :D
Vamos pegar como exemplo o repositório do Gulp. Vamos fazer todos os passos e enviar nosso pull request através desse repositório.
Forkando o repositório
A primeira coisa a fazer é forkar o repositório. Acesse a página do repositório no Github, e clique no botão Fork:
O que significa forkar?
A tradução literal de fork é garfo. Então, você dá uma “garfada” no repositório, dá aquela enrolada no garfo, e traz ele pra sua conta xD
Quando você forkar o repositório, repare que, abaixo do nome do repositório é mostrado o repositório original, ou seja, de onde ele foi forkado:
Você agora pode fazer o que quiser com esse repositório (tomando cuidado com a licença sob a qual ele foi liberado). A ideia aqui é resolver um problema e enviar o pull request com a correção para o repositório original. Como você não tem permissão para comitar diretamente no repositório principal, você precisa forkar e alterar no seu, para então submeter a correção.
Após forkar, vamos fazer nossas alterações!
Clonando o repositório
Agora você precisa baixar os arquivos do repositório para que você possa alterar. A primeira coisa a fazer é copiar a URL do repositório daqui:
Confira se o texto de cima do input está como SSH clone URL. Se não estiver, clique no link SSH que aparece abaixo do input.
Após copiar a URL, abra seu terminal, crie um diretório onde você vai guardar o projeto, e digite git clone <url-do-repositorio>:
1 | git clone git@github.com:fdaciuk/gulp.git |
O comando git clone pega o repositório como ele está no Github, já iniciado e com todo o histórico de commits atualizado. Seria o mesmo que você executar os comandos:
1 | $ git init |
Pronto! Já temos nosso projeto clonado em nossa máquina local! Com esse comando (git clone), será criado um diretório com o mesmo nome do repositório. Entrando nele (cd gulp), vamos começar a codar!
Criando a branch para codar a feature
Agora vamos criar uma nova branch para a nossa feature. Digamos que vamos melhorar o método watch() do Gulp. Vamos criar uma branch com um nome que diga o que será feito. Antes de tudo, garanta que você está na branch master, executando o comando:
1 | git branch |
A resposta deve ser:
1 | * master |
Porque precisa estar na master?
Por convenção, o git utiliza a branch master como padrão, para o código estável do projeto. Então, tudo o que estiver nessa branch, em qualquer repositório, teóricamente é código estável. Logo, você nunca irá mexer diretamente nela, mas em outras branchs, para então fazer merge com a master.
Agora vamos criar a branch com nossa feature. Temos duas formas de fazer isso. A forma mais rápida é:
1 | git checkout -b improve_method_watch |
improve_method_watch é o nome da nossa branch. A outra forma de criar um repositório é com os comandos:
1 | $ git branch improve_method_watch |
O primeiro comando cria a branch. O segundo comando troca da branch master para a branch improve_method_watch.
Mas o primeiro comando que executamos (git checkout -b improve_method_watch), já faz essas duas coisas em um comando só: cria a branch (-b) e já muda para a branch criada (git checkout).
Ok. Agora podemos trabalhar! Vamos codar o que for necessário para deixar essa feature funcionando!
Tá, mas porque eu preciso criar uma nova branch? Se tudo irá para a master, porque não posso codar direto ali?
Como eu disse, a branch master é a branch com o código final do projeto, estável. Criando uma nova branch, se você submeter o pull request para o repositório original, mas ele não for aceito, as alterações não estarão na sua branch master. Dessa forma, se você quiser manter sempre os dois repositórios atualizados e sincronizados, você só precisa apagar a branch que você criou e fez a feature. As duas master vão continuar iguaizinhas :)
Dicas para um bom Pull Request
Quando você for fazer um pull request, a pessoa que é responsável pelo repositório terá de conferir se o código que você está enviando está de acordo com os padrões definidos para aquele projeto. Por isso, tenha em mente que o seu pull request deve ter pouco código. Se a funcionalidade que você quer implementar for muito grande, quebre em partes menores, e envie pull requests pequenos, com o mínimo de alterações possíveis.
Isso vai facilitar a conferência do código, e a sua feature terá maiores chances de ser aceita e fazer parte do projeto principal :)
Após codar sua alteração, é hora de enviar para o seu fork. Primeiro você precisa commitar sua alteração:
1 | $ git add --all |
Coloque uma mensagem que defina exatamente o que você fez. De preferência, a cada pequena parte que você codar, comite com uma mensagem que diga o que está sendo feito até ali. Exemplo:
1 | $ git add --all |
1 | $ git add --all |
Só alguns exemplos de mensagens de commit. Disserte um pouco sobre a funcionalidade que você está criando. Não precisa ser nada muito formal, mas escreva de uma forma que qualquer pessoa que ler, entenda.
Lembrando que, se você estiver fazendo uma alteração para um projeto em inglês, a mensagem de commit deve ser nessa língua.
Após comitar, nossa alteração já está na árvore do git. Vamos agora subir para o nosso repositório forkado:
1 | git push origin improve_method_watch |
Você vai rodar esse comando, trocando improve_method_watch pelo nome da sua branch, obviamente.
Fazendo isso, acesse a conta do repositório original no Github, e você verá uma mensagem como essa:
Depois é só clicar no botão verde Compare & Pull Request.
Você tá falando de Pull Request desde que começou esse tutorial, mas afinal, o que é Pull Request?
Pull Request é quando você envia uma sugestão de melhoria para o repositório.
Quando você quer trazer, pegar, puxar algo para o seu repositório usando o git, você usa o comando git pull. Então, um pull request nada mais é do que uma requisição, ou pedido para que aquele repositório faça um pull com as suas alterações. :)
Após clicar no botão Compare & Pull Request, você será direcionado para a tela onde você vai criar o pull request, e pode conferir se as alterações que aparecem realmente correspondem às alterações que você fez:
Na imagem acima você pode ver:
- Onde diz base fork é o diretório padrão. No meu caso, está em gulpjs/gulp.
- Ao lado, a branch para a qual eu vou enviar meu pull request. Vou enviar direto para a master do repositório padrão.
- head fork é o seu repositório, que você forkou. Na imagem, é o fdaciuk/gulp.
- E por fim, a branch onde eu fiz a alteração: _compare improve_method_watch_
Depois disso, você vai colocar um título no seu pull request, para que, ao visualizar a listagem de pull requests, fique fácil saber do que se trata. Normalmente, quando você só tem uma mensagem de commit, esse título é assumido com a mensagem. Ajuste conforme a necessidade.
Não esqueça também de comentar porque você está fazendo esse pull request, e porque esse ajuste que você fez, faz sentido para o repositório. Uma boa defesa pode ajudar a fazer com que seu pull request seja aceito.
Antes de clicar no botão Create Pull Request, confira os dados da imagem abaixo:
Rolando um pouco, você vai ver os commits que você fez. Confira se está na branch correta, e que você está enviando somente aquilo que você alterou. Se você escolher uma branch errada para enviar, você verá milhares de outras alterações - ou talvez nenhuma, se for a mesma branch - que não fará sentido de ser feito o merge do pull request.
No meu caso, eu fiz só uma alteração no README.md, adicionando um plugin do Gulp (gulp-util) na sessão de plugins recomendados.
Depois de tudo verificado, clique no botão Creat Pull Request e aguarde a resposta! Você será avisado por e-mail - se você não desabilitou as notificações - se houver qualquer atividade nesse pull request: comentários tanto no pull request como nos códigos, para que você possa modificar algo, se a branch for fechada, porque o autor achou que a alteração não fez sentido, ou ainda se o merge for feito.
Se ele fez o merge, então sua alteração já faz parte do repositório principal, e você aparecerá na guia Contributors do repositório principal:
Como você viu na imagem acima, aparece quantos commits você fez, quanto código você adicionou e quanto você removeu!
Manter o projeto sempre atualizado
Para que o seu projeto tenha sempre as últimas alterações do repositório principal, siga as instruções desse link.
Agora você não tem mais desculpas para não colaborar com algum projeto no Github! Cada vez que você colabora para um projeto open source, você ganha conhecimento e cresce como profissional! Siga a dica do E.T. Bilú: busque conhecimento!
Ficou alguma dúvida? Comente!
Sobre o #1postperday: https://blog.da2k.com.br/2014/12/31/um-post-por-dia/
Tem alguma sugestão para os próximos posts do #1postperday? Deixe ela aqui: https://github.com/fdaciuk/fdaciuk.github.io/issues/1