Como fazer uma solicitação pull
As solicitações pull são uma funcionalidade que facilita a colaboração dos desenvolvedores usando o Bitbucket. Elas oferecem uma interface da web fácil de usar para discutir as mudanças propostas antes de integrá-las ao projeto oficial.
Em sua forma mais simples, as solicitações pull são um mecanismo para um desenvolvedor notificar os membros da equipe de que ele ou ela concluiu um recurso. Depois que a ramificação de recurso estiver pronta, o desenvolvedor arquiva uma solicitação pull por meio de sua conta do Bitbucket. Essa ação informa a todos os envolvidos que eles precisam revisar o código e fazer o merge dele para ramificação main.
Mas a solicitação pull é mais que apenas uma notificação—é um fórum dedicado para discutir o recurso proposto. Se houver algum problema com as alterações, os colegas de equipe podem publicar feedback na solicitação pull e até mesmo ajustar o recurso enviando confirmações de sequência. Toda essa atividade é rastreada diretamente dentro da solicitação pull.
Comparada a outros modelos de colaboração, esta solução formal para compartilhar confirmações faz um fluxo de trabalho muito mais simplificado. SVN e Git podem enviar automaticamente e-mails de notificação com um script simples; no entanto, quando se trata de discutir alterações, os desenvolvedores geralmente têm que confiar em segmentos de e-mail. Isso pode se tornar aleatório, especialmente quando confirmações de sequência estão envolvidas. As solicitações pull colocam toda essa funcionalidade em uma interface da web fácil de usar perto de seus repositórios do Bitbucket.
Anatomia de uma solicitação pull
Ao arquivar uma solicitação pull, o que você está fazendo é solicitar que outro desenvolvedor (por exemplo, o mantenedor do projeto) puxe uma ramificação do seu repositório no repositório dele. Isto significa que você precisa fornecer 4 informações para arquivar uma solicitação pull: o repositório de origem, a ramificação de origem, o repositório de destino e a ramificação de destino.
Muitos desses valores vão ser definidos como um padrão sensível pelo Bitbucket. No entanto, dependendo do fluxo de trabalho de colaboração, a equipe talvez precise especificar valores diferentes. O diagrama acima mostra uma solicitação pull que pede para fazer o merge de uma ramificação de recursos na ramificação principal oficial, mas existem muitas outras maneiras de usar solicitações pull.
Como funciona
As solicitações pull podem ser usadas em conjunto com o Fluxo de ramificação de funcionalidade, com o Fluxo de trabalho do Git ou com o Fluxo de trabalho de bifurcação. Mas uma solicitação pull requer duas ramificações distintas ou dois repositórios distintos, para que eles não trabalhem com o Fluxo de trabalho centralizado. Usar solicitações pull com cada um destes fluxos de trabalho é levemente diferente, mas o processo geral é o seguinte:
Um desenvolvedor cria o recurso em uma ramificação dedicada no repositório local.
O desenvolvedor envia a ramificação para um repositório público do Bitbucket.
O desenvolvedor arquiva uma solicitação pull pelo Bitbucket.
O resto da equipe revisa, discute e altera o código.
O mantenedor do projeto mescla o recurso no repositório oficial e fecha a solicitação pull.
O restante desta seção descreve como as solicitações pull podem ser aproveitadas em relação a fluxos de trabalho de colaboração diferentes.
Fluxo de trabalho de ramificação de recurso com solicitações pull
O fluxo de trabalho de ramificação de recurso usa um repositório compartilhado de Bitbucket para gerenciamento de colaboração, e os desenvolvedores criam recursos em ramificações isoladas. Contudo, em vez de fazer o merge de imediato na main, os desenvolvedores devem abrir uma solicitação pull para iniciar uma discussão sobre o recurso antes que ele seja integrado à base de código principal.
Existe apenas um repositório público no fluxo de trabalho da ramificação de recurso, então o repositório de destino da solicitação pull e o repositório de origem sempre vão ser os mesmos. Em geral, o desenvolvedor vai especificar sua ramificação de recurso como a ramificação de origem e a ramificação main como a de destino.
Depois de receber a solicitação pull, o mantenedor do projeto precisa decidir o que fazer. Se o recurso estiver pronto, ele pode fazer o merge do recurso na main e fechar a solicitação pull. Entretanto, se houver algum problema com as alterações propostas, ele pode postar um feedback na solicitação pull. Os commits de acompanhamento vão aparecer ao lado dos comentários relevantes.
É possível também arquivar uma solicitação pull para um recurso que está incompleto. Por exemplo, se um desenvolvedor está com problemas para implementar um requisito particular, ele pode arquivar uma solicitação pull que contém o trabalho em andamento. Outros desenvolvedores podem, então, fornecer sugestões dentro da solicitação pull ou até corrigir eles mesmos o problema com confirmações adicionais.
Fluxo de trabalho de Gitflow com solicitações pull
O Fluxo de trabalho de Gitflow é semelhante ao Fluxo de trabalho de ramificação de recurso, mas define um modelo estrito de ramificação projetado em torno do lançamento do projeto. Adicionar solicitações pull ao Fluxo de trabalho de Gitflow dá aos desenvolvedores um local conveniente para falar sobre uma ramificação de lançamento ou uma ramificação de manutenção enquanto estão trabalhando nela.
A mecânica de solicitações pull no Fluxo de trabalho de Gitflow é exatamente igual à seção anterior: um desenvolvedor simplesmente arquiva uma solicitação pull quando uma ramificação de recurso, lançamento ou hotfix precisa ser revisada e o restante da equipe será notificado via Bitbucket.
O merge dos recursos em geral é feito na ramificação develop, enquanto o das ramificações de lançamento e hotfix é feito tanto na ramificação develop, quanto na main. As solicitações pull podem ser usadas para o gerenciamento formal de todos esses merges.
Fluxo de trabalho de bifurcação com solicitações pull
No fluxo de trabalho de bifurcação, um desenvolvedor coloca uma funcionalidade completa em seu próprio repositório, em vez de em um compartilhado. Depois disso, ele arquiva uma solicitação pull para avisar ao mantenedor do projeto que ele está pronto para revisão.
O aspecto de notificação de solicitações pull é particularmente útil nesse fluxo de trabalho porque o mantenedor do projeto não tem como saber quando outro desenvolvedor adicionou confirmações ao repositório do Bitbucket.
Como cada desenvolvedor tem seu próprio repositório público, o repositório de origem da solicitação pull vai ser diferente do seu repositório de destino. O repositório de origem é o repositório público do desenvolvedor e a ramificação de origem é aquela que contém as alterações propostas. Se o desenvolvedor estiver tentando fazer o merge do recurso na base de código principal, então o repositório de destino vai ser o projeto oficial e a ramificação de destino vai ser a main.
As solicitações pull também podem ser usadas para colaborar com outros desenvolvedores fora do projeto oficial. Por exemplo, se um desenvolvedor estava trabalhando em uma funcionalidade com um companheiro de equipe, eles poderiam arquivar uma solicitação pull usando o repositório de Bitbucket do companheiro para o destino, em vez do projeto oficial. Então, eles usariam a mesma ramificação de funcionalidade para as ramificações de origem e destino.
Os dois desenvolvedores podem discutir e desenvolver o recurso dentro da solicitação pull. Quando terminarem, um deles pode arquivar outra solicitação pull pedindo para fazer o merge do recurso na ramificação principal oficial. Esse tipo de flexibilidade faz das solicitações pull uma ferramenta de colaboração muito poderosa no Fluxo de trabalho de bifurcação.
Exemplo
O exemplo abaixo demonstra como as solicitações pull podem ser usadas no Fluxo de trabalho de bifurcação. É igualmente aplicável aos desenvolvedores que trabalham em equipes pequenas e a um desenvolvedor de terceiro que contribui para um projeto de software aberto.
No exemplo, Mary é um desenvolvedor e John é o mantenedor do projeto. Os dois têm seus próprios repositórios públicos do Bitbucket e o de John contém o projeto oficial.
Mary bifurca o projeto oficial
Para começar a trabalhar no projeto, Mary precisa primeiro bifurcar o código fonte do repositório de Bitbucket do John. Ela pode fazer isso se registrando no Bitbucket, navegando até o repositório de John e clicando no botão Fork.
Depois de preencher o nome e a descrição do repositório bifurcado, ela terá uma cópia do lado do servidor do projeto.
Mary clona seu repositório do Bitbucket
Em seguida, Mary precisa clonar o repositório do Bitbucket que acabou de bifurcar. Isso dará a ela uma cópia ativa do projeto em sua máquina local. Ela pode fazer isso executando o seguinte comando:
git clone https://user@bitbucket.org/user/repo.gitLembre-se que o clone de git cria automaticamente uma origem remota que aponta de volta para o repositório bifurcado da Mary.
Mary desenvolve um novo recurso
Antes de começar a escrever qualquer código, Mary precisa criar uma nova ramificação para o recurso. Essa ramificação é o que ela vai usar como a ramificação de origem da solicitação pull.
git checkout -b some-feature
# Edit some code
git commit -a -m "Add first draft of some feature"Mary pode usar quantos commits precisar para criar a funcionalidade. E, se o histórico da funcionalidade for mais bagunçado do que ela gostaria, ela pode usar um rebase interativo para remover ou suprimir commits desnecessários. Para projetos maiores, limpar o histórico de uma funcionalidade torna mais fácil ao mantenedor do projeto visualizar o que está acontecendo na solicitação pull.
Mary envia o recurso para seu repositório do Bitbucket
Depois que sua funcionalidade estiver completa, Mary coloca a ramificação de funcionalidade em seu próprio repositório de Bitbucket (não no repositório oficial) com um simples git push:
git push origin some-branchIsso disponibiliza suas alterações para o mantenedor do projeto (ou qualquer colaborador que possa precisar de acesso a elas).
Mary cria a solicitação pull
Depois que o Bitbucket tiver sua ramificação de funcionalidade, Mary pode criar a solicitação pull pela conta do Bitbucket navegando para seu repositório bifurcado e clicando no botão Pull request [Solicitação pull] no canto superior direito. O formulário resultante configura automaticamente o repositório de Mary como o repositório de origem e pede a ela para especificar a ramificação de origem, o repositório de destino e a ramificação de destino.
Mary quer fazer o merge do seu recurso na base de código principal, para que a ramificação de origem seja a ramificação de recurso, o repositório de destino seja o repositório público do John e que a ramificação de destino seja a main. Ela também vai precisar informar um título e uma descrição para a solicitação pull. Se existirem outras pessoas que precisem aprovar o código além de John, elas podem ser acrescentadas no campo Reviewers.
Depois que ela cria a solicitação pull, uma notificação é enviada para John através de seu feed do Bitbucket e (opcionalmente) por e-mail.
John revisa a solicitação pull
John pode acessar todas as solicitações pull que as pessoas arquivaram, clicando na guia Pull request [Solicitação pull] no seu próprio repositório de Bitbucket. Clicar nas solicitações pull da Mary mostrará a ele uma descrição da solicitações pull, o histórico de commits da funcionalidade e um diff de todas as alterações que ele contém.
Se ele achar que o recurso está pronto para o merge no projeto, tudo o que ele precisa fazer é clicar no botão Merge para aprovar a solicitação pull e fazer o merge do recurso da Mary à sua ramificação main.
Mas, para este exemplo, vamos dizer que John encontrou um bug pequeno no código de Mary e precisa que ela o corrija antes de fazer a mesclagem. Ele pode publicar um comentário na solicitação pull como um todo ou pode selecionar uma confirmação específica no histórico do recurso para comentar.
Mary adiciona uma confirmação de sequência
Se Mary tiver alguma pergunta sobre o feedback, ela pode responder dentro da solicitação pull, tratando-a como um fórum de discussão para o recurso.
Para corrigir o erro, Mary adiciona outra confirmação à sua ramificação de recurso e a envia para seu repositório do Bitbucket, exatamente como ela fez da primeira vez. Esta confirmação é automaticamente adicionada à solicitação pull original e John pode revisar novamente as alterações, bem ao lado de seu comentário original.
John aceita a solicitação pull
Por fim, John aceita as mudanças, faz o merge da ramificação de recurso à principal e fecha a solicitação pull. O recurso agora está integrado ao projeto, e quaisquer outros desenvolvedores trabalhando nele podem enviar pull para seus próprios repositórios locais, usando o comando padrão git pull.
Onde ir a partir daqui
Agora você possui todas as ferramentas necessárias para começar a integrar solicitações pull em seu fluxo de trabalho existente. Lembre-se, as solicitações pull não substituem nenhum dos fluxos de trabalho de colaboração baseados em git, apenas são adições convenientes a eles para tornar a colaboração mais acessível a todos os membros da sua equipe.
