Fazendo uma solicitação pull

Making a Pull Request

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.

Git Workflows: Pull Request in Bitbucket

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

But, the pull request is more than just a notification—it’s a dedicated forum for discussing the proposed feature. If there are any problems with the changes, teammates can post feedback in the pull request and even tweak the feature by pushing follow-up commits. All of this activity is tracked directly inside of the pull request.

Git Workflows: Activity inside a pull request

Compared to other collaboration models, this formal solution for sharing commits makes for a much more streamlined workflow. SVN and Git can both automatically send notification emails with a simple script; however, when it comes to discussing changes, developers typically have to rely on email threads. This can become haphazard, especially when follow-up commits are involved. Pull requests put all of this functionality into a friendly web interface right next to your Bitbucket repositories.

Anatomy of a Pull Request

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.

Git Workflows: Pull Requests

Many of these values will be set to a sensible default by Bitbucket. However, depending on your collaboration workflow, your team may need to specify different values. The above diagram shows a pull request that asks to merge a feature branch into the official master branch, but there are many other ways to use pull requests.

How it works

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:

  1. A developer creates the feature in a dedicated branch in their local repo.

  2. The developer pushes the branch to a public Bitbucket repository.

  3. The developer files a pull request via Bitbucket.

  4. The rest of the team reviews the code, discusses it, and alters it.

  5. The project maintainer merges the feature into the official repository and closes the pull request.

The rest of this section describes how pull requests can be leveraged against different collaboration workflows.

Feature Branch Workflow With Pull Requests

O fluxo de ramificação de funcionalidade usa um repositório compartilhado de Bitbucket para gerenciamento de colaboração e os desenvolvedores criam funcionalidades em ramificações isoladas. Contudo, em vez de fundi-los imediatamente no mestre, os desenvolvedores devem abrir uma solicitação pull para iniciar uma discussão ao redor da funcionalidade antes que ele seja integrado à base de código principal.

Pull Request: Feature Branch workflow

Existe somente um repositório público no fluxo de trabalho da ramificação de funcionalidade, então, o repositório de destino da solicitação pull e o repositório de origem sempre serão os mesmos. Geralmente, o desenvolvedor especificará sua ramificação de funcionalidade como a ramificação de origem e a ramificação mestre como a de destino.

Depois de receber a solicitação pull, o mantenedor do projeto precisa decidir o que fazer. Se a funcionalidade estiver pronta, ele pode simplesmente fundi-la à mestre 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 aparecerão ao lado dos comentários relevantes.

It’s also possible to file a pull request for a feature that is incomplete. For example, if a developer is having trouble implementing a particular requirement, they can file a pull request containing their work-in-progress. Other developers can then provide suggestions inside of the pull request, or even fix the problem themselves with additional commits.

Gitflow Workflow With Pull Requests

The Gitflow Workflow is similar to the Feature Branch Workflow, but defines a strict branching model designed around the project release. Adding pull requests to the Gitflow Workflow gives developers a convenient place to talk about a release branch or a maintenance branch while they’re working on it.

Pull Requests: Gitflow Workflow Pull Requests: Gitflow Workflow 2

The mechanics of pull requests in the Gitflow Workflow are the exact same as the previous section: a developer simply files a pull request when a feature, release, or hotfix branch needs to be reviewed, and the rest of the team will be notified via Bitbucket.

As funcionalidades geralmente são mescladas na ramificação dodesenvolvedor, enquanto as ramificações de lançamento e hotfix são mescladas tanto no desenvolvedor, quanto no mestre. As solicitações pull podem ser usadas para gerenciar formalmente todas essas fusões.

Forking Workflow With Pull Requests

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.

The notification aspect of pull requests is particularly useful in this workflow because the project maintainer has no way of knowing when another developer has added commits to their Bitbucket repository.

Pull Requests: Forking workflow

Como cada desenvolvedor possui seu próprio repositório público, o repositório de origem da solicitação pull 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 fundir a funcionalidade na base de código principal, então o repositório de destino será o projeto oficial e a ramificação de destino será o 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 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.

Pull Requests: Forking workflow

The two developers could discuss and develop the feature inside of the pull request. When they’re done, one of them would file another pull request asking to merge the feature into the official master branch. This kind of flexibility makes pull requests very powerful collaboration tool in the Forking workflow.

Example

The example below demonstrates how pull requests can be used in the Forking Workflow. It is equally applicable to developers working in small teams and to a third-party developer contributing to an open source project.

In the example, Mary is a developer, and John is the project maintainer. Both of them have their own public Bitbucket repositories, and John’s contains the official project.

Mary forks the official project

Pull Requests: Fork the project

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.

Pull Request: Fork in Bitbucket

After filling out the name and description for the forked repository, she will have a server-side copy of the project.

Mary clones her Bitbucket repository

Pull Request: Clone the Bitbucket repo

Next, Mary needs to clone the Bitbucket repository that she just forked. This will give her a working copy of the project on her local machine. She can do this by running the following command:

git clone https://user@bitbucket.org/user/repo.git

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

Mary develops a new feature

Pull Requests: develop a new feature

Before she starts writing any code, Mary needs to create a new branch for the feature. This branch is what she will use as the source branch of the pull request.

git checkout -b some-feature
# Edite alguns códigos
git commit -a -m "Adicione o primeiro rascunho de alguma funcionalidade"

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 pushes the feature to her Bitbucket repository

Pull Requests: Push feature to Bitbucket repository

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-branch

This makes her changes available to the project maintainer (or any collaborators who might need access to them).

Mary creates the pull request

Pull Request: Create Pull Request

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 deseja mesclar sua funcionalidade na base de código principal, para que a ramificação de origem seja sua ramificação de funcionalidade, que o repositório de destino seja o repositório público de John, e que a ramificação de destino seja a mestre. Ela também precisará fornecer 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, ela pode inseri-las no campo Reviewers [Revisores].

Pull Request: Bitbucket

After she creates the pull request, a notification will be sent to John via his Bitbucket feed and (optionally) via email.

John reviews the pull request

Pull Request: Bitbucket pull requests

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 a funcionalidade está pronta para ser fundida no projeto, tudo o que ele precisa fazer é clicar no botão Merge [Mesclar] para aprovar a solicitação pull e fundir a funcionalidade de Mary em sua ramificação mestre.

But, for this example, let’s say John found a small bug in Mary’s code, and needs her to fix it before merging it in. He can either post a comment to the pull request as a whole, or he can select a specific commit in the feature’s history to comment on.

Pull Request: Comment

Mary adds a follow-up commit

If Mary has any questions about the feedback, she can respond inside of the pull request, treating it as a discussion forum for her feature.

To correct the error, Mary adds another commit to her feature branch and pushes it to her Bitbucket repository, just like she did the first time around. This commit is automatically added to the original pull request, and John can review the changes again, right next to his original comment.

John accepts the pull request

Finalmente, John aceita as mudanças, mescla a ramificação de funcionalidade ao mestre e fecha a solicitação pull. A funcionalidade agora está integrada ao projeto e quaisquer outros desenvolvedores trabalhando nele podem puxá-lo para seus próprios repositórios locais, usando o comando padrão git pull.

Where to go from here

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.

Ready to try pull requests?

Try this interactive tutorial.

Comece agora mesmo