Making a pull request

Como fazer uma solicitação pull

As solicitações pull são um recurso que facilita a colaboração dos desenvolvedores usando o Bitbucket. Elas fornecem uma interface da web fácil de usar para discutir alterações propostas antes de integrá-las ao projeto oficial.

Git Workflows: Pull Request in Bitbucket

Em sua forma mais simples, as solicitações pull são um mecanismo para um desenvolvedor notificar membros da equipe de que concluíram um recurso. Depois que a ramificação do recurso está pronta, o desenvolvedor arquiva uma solicitação pull através de sua conta do Bitbucket. Isso informa a todos os envolvidos que eles precisam revisar o código e mesclá-lo à ramificação mestre.

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.

Git Workflows: Activity inside a pull request

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

Quando você arquiva uma solicitação pull, você está simplesmente solicitando que outro desenvolvedor (por exemplo, o mantenedor do projeto) envie uma ramificação do seu repositório para o repositório dele. Isso significa que você precisa fornecer 4 partes de informação 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.

Git Workflows: Pull Requests

Muitos desses valores serão definidos para um padrão sensível pelo Bitbucket. No entanto, dependendo do seu fluxo de trabalho de colaboração, sua equipe pode precisar especificar valores diferentes. O diagrama acima mostra uma solicitação pull que pede para mesclar uma ramificação de recursos na ramificação mestre oficial, mas há muitas outras maneiras de usar solicitações pull.

Como funciona

As solicitações pull podem ser usadas juntamente com o Fluxo de trabalho de ramificação de recurso, o Fluxo de trabalho de Gitflow ou o Fluxo de trabalho de bifurcação. Mas uma solicitação pull requer duas ramificações distintas ou dois repositórios distintos, então, elas não funcionarão com o Fluxo de trabalho centralizado. Usar solicitações pull com cada um desses fluxos de trabalho é um pouco diferente, mas o processo geral é o seguinte:

  1. Um desenvolvedor cria o recurso em uma ramificação dedicada em seu repositório local.

  2. O desenvolvedor envia a ramificação para um repositório público do Bitbucket.

  3. O desenvolvedor arquiva uma solicitação pull via Bitbucket.

  4. O restante da equipe revisa o código, discute-o e o altera.

  5. 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 do Bitbucket para gerenciar a colaboração e os desenvolvedores criam recursos em ramificações isoladas. Mas, em vez de mesclá-las imediatamente no mestre, 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.

Pull Request: Feature Branch workflow

Há apenas um repositório público no Fluxo de trabalho de ramificação de recurso, então, o repositório de destino e o repositório de origem da solicitação pull serão sempre iguais. Geralmente, o desenvolvedor vai especificar sua ramificação de recurso como a ramificação de origem e a ramificação mestre como a ramificação de destino.

Depois de receber a solicitação pull, o mantenedor do projeto deve decidir o que fazer. Se o recurso estiver pronto, ele pode simplesmente mesclá-lo ao mestre e fechar a solicitação pull. Mas se houver problemas com as alterações propostas, ele pode publicar o feedback na solicitação pull. As confirmações de sequência serão exibidas 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.

Pull Requests: Gitflow Workflow Pull Requests: Gitflow Workflow 2

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.

Os recursos, geralmente, são mesclados na ramificação de desenvolvimento, enquanto as ramificações de lançamento e de hotfix são mescladas em desenvolvimento e mestre. As solicitações pull podem ser usadas para gerenciar formalmente todas essas mesclagens.

Fluxo de trabalho de bifurcação com solicitações pull

No Fluxo de trabalho de bifurcação, um desenvolvedor envia um recurso completo para seu próprio repositório público em vez de um compartilhado. Depois disso, arquiva uma solicitação pull para que o mantenedor do projeto saiba 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.

Pull Requests: Forking workflow

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 mesclar o recurso à base de código principal, o repositório de destino será o projeto oficial e a ramificação de destino será mestre.

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 um recurso com um colega de equipe, eles poderiam arquivar uma solicitação pull usando o repositório do Bitbucket do colega para o destino em vez do projeto oficial. Eles poderiam, então, usar a mesma ramificação de recurso para as ramificações de origem e de destino.

Pull Requests: Forking workflow

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 mesclar o recurso na ramificação mestre 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

Pull Requests: Fork the project

Para começar a trabalhar no projeto, Mary primeiro precisa bifurcar o repositório do Bitbucket de John. Ela pode fazer isso se conectando ao Bitbucket, navegando até o repositório de John e clicando no botão Bifurcar.

Pull Request: Fork in Bitbucket

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

Pull Request: Clone the Bitbucket repo

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.git

Lembre-se de que git clone cria automaticamente uma origem remota que aponta de volta para o repositório bifurcado de Mary.

Mary desenvolve um novo recurso

Pull Requests: develop a new feature

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 quantas confirmações ela precisar para criar o recurso. E, se o histórico do recurso for mais confuso do que ela gostaria, ela pode usar um rebase interativo para remover ou suprimir as confirmações desnecessárias. Para projetos maiores, limpar o histórico de um recurso faz com que fique muito mais fácil para o mantenedor do projeto ver o que está acontecendo na solicitação pull.

Mary envia o recurso para seu repositório do Bitbucket

Pull Requests: Push feature to Bitbucket repository

Depois de concluir seu recurso, Mary envia a ramificação de recursos para seu próprio repositório do Bitbucket (não o repositório oficial) com um simples git push:

git push origin some-branch

Isso 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

Pull Request: Create Pull Request

Depois que o Bitbucket tem a ramificação de recursos dela, Mary pode criar a solicitação pull através de sua conta do Bitbucket navegando para seu repositório bifurcado e clicando no botão Solicitação pull no canto superior direito. O formulário resultante define 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 mesclar seu recurso na base de código principal, portanto, a ramificação de origem é sua ramificação de recurso, o repositório de destino é o repositório público de John e a ramificação de destino é mestre. Ela também vai precisar fornecer um título e uma descrição para a solicitação pull. Se houver outras pessoas que precisem aprovar o código além de John, ela pode inseri-las no campo Revisores.

Pull Request: Bitbucket

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

Pull Request: Bitbucket pull requests

John pode acessar todas as solicitações pull arquivadas pelas pessoas clicando na guia Solicitação pull em seu próprio repositório do Bitbucket. Clicar na solicitação pull de Mary vai exibir uma descrição da solicitação pull, o histórico de confirmação do recurso e um diff de todas as alterações que ele contém.

Se ele achar que o recurso está pronto para ser mesclado no projeto, ele só precisa pressionar o botão Mesclar para aprovar a solicitação pull e mesclar o recurso de Mary em sua ramificação mestre.

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.

Pull Request: Comment

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

Finalmente, John aceita as alterações, mescla a ramificação do recurso no mestre e fecha a solicitação pull. O recurso é, então, integrado ao projeto e qualquer outro desenvolvedor que esteja trabalhando nele pode puxá-lo para seus próprios repositórios locais usando o comando git pull padrão.

Onde ir a partir daqui

Agora, você deve ter todas as ferramentas necessárias para iniciar a integração das solicitações pull no fluxo de trabalho existente. Lembre-se, as solicitações pull não são uma substituição para nenhum dos fluxos de trabalho de colaboração baseados em Git, mas são uma adição conveniente para eles que torna a colaboração mais acessível a todos os membros da equipe.

Pronto para tentar as solicitações pull?

Tente este tutorial interativo.

Comece agora mesmo