6.2 GitHub - Contribuindo para um Projeto

Tony está procurando um código para rodar no seu microcontrolador programável Arduino e encontrou um ótimo arquivo de programa no GitHub em https://github.com/schacon/blink.

O único problema é que a taxa de piscar está muito rápida. Achamos que é muito mais agradável esperar 3 segundos em vez de 1 entre cada mudança de estado. Então, vamos melhorar o programa e enviá-lo de volta ao projeto como uma alteração proposta.

Primeiro, clicamos no botão 'Fork' (Fazer Fork) como mencionado anteriormente para obtermos a nossa própria cópia do projeto. O nosso nome de usuário aqui é “tonychacon”, então a nossa cópia deste projeto está em https://github.com/tonychacon/blink e é lá que podemos editá-lo. Vamos cloná-lo localmente, criar um branch de tópico, fazer a alteração no código e finalmente fazer o push dessa alteração de volta para o GitHub.

Agora, se voltarmos para o nosso fork no GitHub, podemos ver que o GitHub notou que fizemos o push de um novo branch de tópico e nos apresenta um grande botão verde para verificar as nossas alterações e abrir um Pull Request para o projeto original.

Alternativamente, você pode ir para a página “Branches” em https://github.com/<user>/<project>/branches para localizar o seu branch e abrir um novo Pull Request a partir de lá.

Se clicarmos naquele botão verde, veremos uma tela que nos pede para dar um título e uma descrição ao nosso Pull Request. Quase sempre vale a pena colocar algum esforço nisso, já que uma boa descrição ajuda o proprietário do projeto original a determinar o que você estava tentando fazer, se as alterações propostas estão corretas e se a aceitação das alterações melhoraria o projeto original.

Também vemos uma lista dos commits em nosso branch de tópico que estão “à frente” (ahead) do branch master (neste caso, apenas um) e um diff unificado de todas as alterações que serão feitas caso este branch seja mesclado pelo proprietário do projeto.

Quando você clica no botão 'Create pull request' nesta tela, o proprietário do projeto do qual você fez fork receberá uma notificação de que alguém está sugerindo uma alteração e fornecerá um link para uma página que contém todas essas informações.

Neste ponto, o proprietário do projeto pode examinar a alteração sugerida e mesclá-la, rejeitá-la ou comentá-la. Digamos que ele goste da ideia, mas preferisse um tempo um pouco maior para a luz ficar apagada do que acesa.

Onde essa conversa poderia ocorrer por e-mail nos fluxos de trabalho apresentados em Git Distribuído, no GitHub ela acontece online. O proprietário do projeto pode revisar o diff unificado e deixar um comentário clicando em qualquer uma das linhas.

Assim que o mantenedor faz esse comentário, a pessoa que abriu o Pull Request (e, na verdade, qualquer outra pessoa que esteja observando o repositório) receberá uma notificação. Abordaremos a personalização disso mais tarde, mas se tivesse as notificações por e-mail ativadas, Tony receberia um e-mail como este:

Qualquer pessoa também pode deixar comentários gerais sobre o Pull Request. Em Página de discussão de Pull Request podemos ver um exemplo do proprietário do projeto tanto comentando em uma linha de código quanto deixando um comentário geral na seção de discussão. Você pode ver que os comentários de código também são trazidos para a conversa.

Agora o contribuidor pode ver o que precisa fazer para que a sua alteração seja aceita. Felizmente, isso é muito simples. Enquanto por e-mail você pode ter que reescrever (re-roll) a sua série e reenviá-la para a lista de discussão, com o GitHub você simplesmente faz um commit no branch de tópico novamente e faz o push, o que atualizará automaticamente o Pull Request. Em Final do Pull Request, você também pode ver que o comentário do código antigo foi ocultado no Pull Request atualizado, uma vez que foi feito em uma linha que já foi alterada.

Adicionar commits a um Pull Request existente não aciona uma notificação, então, assim que Tony envia as suas correções, ele decide deixar um comentário para informar ao proprietário do projeto que fez a alteração solicitada.

Uma coisa interessante de se notar é que se você clicar na aba “Files Changed” (Arquivos Alterados) neste Pull Request, você obterá o diff “unificado” — isto é, a diferença total agregada que seria introduzida no seu branch principal se este branch de tópico fosse mesclado. Em termos de git diff, ele basicamente mostra automaticamente git diff master…​<branch> para o branch no qual este Pull Request se baseia. Veja Determinando o Que é Introduzido para saber mais sobre esse tipo de diff.

A outra coisa que você notará é que o GitHub verifica se o Pull Request se mescla de forma limpa e fornece um botão para fazer o merge para você no servidor. Este botão só aparece se você tiver acesso de gravação (write access) ao repositório e um merge trivial for possível. Se você clicar nele, o GitHub realizará um merge “non-fast-forward”, o que significa que mesmo que o merge pudesse ser um fast-forward, ele ainda criará um commit de merge.

Se preferir, você pode simplesmente fazer o pull do branch e mesclá-lo localmente. Se você mesclar este branch no branch master e fizer o push para o GitHub, o Pull Request será fechado automaticamente.

Este é o fluxo de trabalho básico que a maioria dos projetos do GitHub usa. Branches de tópico são criados, Pull Requests são abertos neles, uma discussão se segue, possivelmente mais trabalho é feito no branch e, eventualmente, a solicitação é fechada ou mesclada.

É importante entender que muitos projetos não pensam realmente nos Pull Requests como filas de patches perfeitos que devem ser aplicados de forma limpa em ordem, como a maioria dos projetos baseados em lista de discussão pensa das contribuições de séries de patches. A maioria dos projetos no GitHub pensa nos branches de Pull Request como conversas iterativas em torno de uma alteração proposta, culminando em um diff unificado que é aplicado por meio de merge.

Esta é uma distinção importante, porque geralmente a alteração é sugerida antes que o código seja considerado perfeito, o que é muito mais raro com contribuições de séries de patches baseadas em listas de discussão. Isso permite uma conversa mais cedo com os mantenedores para que chegar à solução adequada seja mais um esforço da comunidade. Quando um código é proposto com um Pull Request e os mantenedores ou a comunidade sugerem uma alteração, a série de patches geralmente não é reescrita, mas sim a diferença é enviada como um novo commit para o branch, avançando a conversa com o contexto do trabalho anterior intacto.

Por exemplo, se você voltar e olhar novamente para Final do Pull Request, notará que o contribuidor não fez um rebase do seu commit nem enviou outro Pull Request. Em vez disso, eles adicionaram novos commits e fizeram push para o branch existente. Dessa forma, se você voltar e analisar este Pull Request no futuro, poderá facilmente encontrar todo o contexto do porquê as decisões foram tomadas. Clicar no botão “Merge” no site cria intencionalmente um commit de merge que faz referência ao Pull Request, para que seja fácil voltar e pesquisar a conversa original, se necessário.

Se o seu Pull Request ficar desatualizado ou não puder ser mesclado de forma limpa, você vai querer consertá-lo para que o mantenedor possa mesclá-lo facilmente. O GitHub testará isso para você e informará na parte inferior de cada Pull Request se o merge é trivial ou não.

Se você vir algo como Pull Request não se mescla de forma limpa, você vai querer consertar o seu branch para que ele fique verde e o mantenedor não tenha que fazer trabalho extra.

Você tem duas opções principais para fazer isso. Você pode fazer um rebase do seu branch em cima de qualquer que seja o branch de destino (normalmente o branch master do repositório do qual você fez fork), ou pode mesclar (merge) o branch de destino no seu branch.

A maioria dos desenvolvedores no GitHub escolherá fazer o último, pelas mesmas razões que acabamos de ver na seção anterior. O que importa é o histórico e o merge final, então fazer rebase não está lhe dando muito além de um histórico ligeiramente mais limpo e, em troca, é muito mais difícil e propenso a erros.

Se você quiser mesclar o branch de destino para tornar o seu Pull Request passível de merge, você adicionaria o repositório original como um novo remoto, faria um fetch dele, mesclaria o branch principal daquele repositório no seu branch de tópico, consertaria quaisquer problemas e finalmente faria o push de volta para o mesmo branch em que você abriu o Pull Request.

Por exemplo, digamos que no exemplo do “tonychacon” que estávamos usando antes, o autor original tenha feito uma alteração que criaria um conflito no Pull Request. Vamos percorrer essas etapas.

Assim que você fizer isso, o Pull Request será automaticamente atualizado e verificado novamente para ver se ele se mescla de forma limpa.

Uma das grandes coisas sobre o Git é que você pode fazer isso continuamente. Se você tiver um projeto muito longo, poderá facilmente fazer merge do branch de destino repetidas vezes e só terá que lidar com os conflitos que surgiram desde a última vez que você fez merge, tornando o processo muito gerenciável.

Se você absolutamente deseja fazer rebase do branch para limpá-lo, certamente pode fazê-lo, mas é altamente recomendável não fazer um push forçado (force push) sobre o branch em que o Pull Request já está aberto. Se outras pessoas tiverem feito o pull dele e feito mais trabalho nele, você encontrará todos os problemas descritos em Os Perigos do Rebase (Perils of Rebasing). Em vez disso, faça o push do branch que sofreu rebase para um novo branch no GitHub e abra um Pull Request totalmente novo fazendo referência ao antigo, depois feche o original.

A sua próxima pergunta pode ser “Como faço referência ao Pull Request antigo?”. Acontece que existem muitas, muitas maneiras de referenciar outras coisas em quase qualquer lugar onde você pode escrever no GitHub.

Vamos começar com como fazer referência cruzada a outro Pull Request ou a uma Issue. Todos os Pull Requests e Issues recebem números e eles são únicos dentro do projeto. Por exemplo, você não pode ter o Pull Request #3 e a Issue #3. Se você quiser referenciar qualquer Pull Request ou Issue a partir de qualquer outro, você pode simplesmente colocar #<num> em qualquer comentário ou descrição. Você também pode ser mais específico se a Issue ou Pull Request estiver em outro lugar; escreva username#<num> se estiver se referindo a uma Issue ou Pull Request em um fork do repositório em que você está, ou username/repo#<num> para referenciar algo em outro repositório.

Vamos ver um exemplo. Digamos que fizemos um rebase do branch no exemplo anterior, criamos um novo pull request para ele e agora queremos referenciar o pull request antigo a partir do novo. Nós também queremos referenciar uma issue no fork do repositório e uma issue em um projeto completamente diferente. Podemos preencher a descrição exatamente como em Referências cruzadas em um Pull Request.

Quando submetermos este pull request, veremos tudo isso renderizado como em Referências cruzadas renderizadas em um Pull Request.

Observe que a URL completa do GitHub que colocamos lá foi encurtada apenas para as informações necessárias.

Agora, se Tony voltar e fechar o Pull Request original, podemos ver que, ao mencioná-lo no novo, o GitHub criou automaticamente um evento de trackback (rastreamento) na linha do tempo do Pull Request. Isso significa que qualquer um que visite este Pull Request e veja que ele está fechado pode facilmente encontrar um link para aquele que o substituiu. O link se parecerá com Link de volta para o novo Pull Request na linha do tempo do Pull Request fechado.

Além dos números de issue, você também pode referenciar um commit específico pelo seu SHA-1. Você tem que especificar um SHA-1 completo de 40 caracteres, mas se o GitHub vir isso em um comentário, ele criará um link direto para o commit. Novamente, você pode referenciar commits em forks ou outros repositórios da mesma forma que fez com issues.

A primeira funcionalidade Markdown realmente útil específica do GitHub, especialmente para uso em Pull Requests, é a Lista de Tarefas (Task List). Uma lista de tarefas é uma lista de caixas de seleção de coisas que você deseja que sejam feitas. Colocá-las em uma Issue ou Pull Request normalmente indica coisas que você deseja que sejam feitas antes de considerar o item completo.

Você pode criar uma lista de tarefas como esta:

Se incluirmos isso na descrição do nosso Pull Request ou Issue, o veremos renderizado como em Listas de tarefas renderizadas em um comentário Markdown.

Isso é frequentemente usado em Pull Requests para indicar tudo o que você gostaria de ver feito no branch antes que o Pull Request esteja pronto para o merge. A parte realmente legal é que você pode simplesmente clicar nas caixas de seleção para atualizar o comentário — você não precisa editar o Markdown diretamente para marcar as tarefas como concluídas.

Além do mais, o GitHub procurará por listas de tarefas em suas Issues e Pull Requests e as mostrará como metadados nas páginas que os listam. Por exemplo, se você tem um Pull Request com tarefas e olha na página de visão geral de todos os Pull Requests, pode ver o quanto ele está concluído. Isso ajuda as pessoas a dividirem Pull Requests em subtarefas e ajuda outras pessoas a acompanhar o progresso do branch. Você pode ver um exemplo disso em Resumo da lista de tarefas na lista de Pull Request.

Elas são incrivelmente úteis quando você abre um Pull Request logo no início e o usa para rastrear o seu progresso através da implementação do recurso.

Você também pode adicionar trechos de código (code snippets) aos comentários. Isso é especialmente útil se você quiser apresentar algo que você poderia tentar fazer antes de realmente implementá-lo como um commit no seu branch. Isso também é usado com frequência para adicionar código de exemplo do que não está funcionando ou o que este Pull Request poderia implementar.

Para adicionar um trecho de código você tem que “cercá-lo” (fence) com crases.

Se você adicionar um nome de linguagem como fizemos ali com 'java', o GitHub também tentará destacar a sintaxe do trecho. No caso do exemplo acima, ele acabaria renderizando como em Exemplo de código cercado renderizado.

Se você estiver respondendo a uma pequena parte de um comentário longo, você pode citar seletivamente do outro comentário precedendo as linhas com o caractere >. De fato, isso é tão comum e tão útil que existe um atalho de teclado para isso. Se você destacar texto em um comentário ao qual deseja responder diretamente e pressionar a tecla r, ele citará esse texto na caixa de comentário para você.

As citações se parecem mais ou menos assim:

Uma vez renderizado, o comentário se parecerá com Exemplo de citação renderizado.

Finalmente, você também pode usar emoji em seus comentários. Isso é, na verdade, usado extensivamente em comentários que você vê em muitas Issues e Pull Requests no GitHub. Há até mesmo um assistente de emoji no GitHub. Se você estiver digitando um comentário e começar com um caractere :, um recurso de autocompletar ajudará a encontrar o que você está procurando.

Os emojis assumem a forma de :<name>: em qualquer lugar no comentário. Por exemplo, você poderia escrever algo assim:

Quando renderizado, ficaria parecido com Comentários repletos de emoji.

Não que isso seja incrivelmente útil, mas adiciona um elemento de diversão e emoção a um meio no qual, de outra forma, é difícil transmitir emoção.

Isso não é tecnicamente GitHub Flavored Markdown, mas é incrivelmente útil. Além de adicionar links de imagens Markdown aos comentários, que podem ser difíceis de encontrar e incorporar URLs, o GitHub permite que você arraste e solte imagens em áreas de texto para incorporá-las.

Se você olhar para Arraste e solte imagens para carregá-las e incorporá-las automaticamente, poderá ver uma pequena dica “Parsed as Markdown” (Analisado como Markdown) acima da área de texto. Clicar nela lhe dará um guia de referência completo de tudo o que você pode fazer com Markdown no GitHub.