Introdução
O fluxo de GitHub é um fluxo de trabalho leve e baseado no branch. O fluxo do GitHub é útil para todos, não apenas para os desenvolvedores. Por exemplo, aqui no GitHub, usamos o fluxo do GitHub para nossa política de site, para a documentação e para o roteiro.
Pré-requisitos
Para seguir o fluxo de GitHub, você precisa de uma conta de GitHub e um repositório. Para obter informações sobre como criar uma conta, confira Criar uma conta no GitHub. Para obter informações sobre como criar um repositório, confira Início rápido para repositórios. Para obter informações sobre como procurar um repositório existente para contribuir, confira Encontrando maneiras de contribuir com o código aberto no GitHub.
Seguindo o fluxo de GitHub
Tip
Conclua todas as etapas do fluxo do GitHub por meio da interface da Web do GitHub, da linha de comando e GitHub CLI ou GitHub Desktop. Para obter mais informações sobre as ferramentas que você pode usar para se conectar ao GitHub, confira Conectando-se ao GitHub.
Criar um branch
Crie um branch no seu repositório. Um nome de branch curto e descritivo permite que seus colaboradores vejam o trabalho em andamento rapidamente. Por exemplo, increase-test-timeout ou add-code-of-conduct. Para saber mais, confira Criar e excluir branches no repositório.
Ao criar um branch, você cria um espaço para trabalhar sem afetar o branch padrão. Além disso, você fornece aos colaboradores a oportunidade de revisar seu trabalho.
Fazer alterações
No seu branch, faça quaisquer alterações desejadas no repositório. Para saber mais, confira Criar arquivos, Editando arquivos, Renomear um arquivo, Movendo um arquivo para um novo local ou Excluir arquivos em um repositório.
Seu branch é um lugar seguro para fazer alterações. Se você cometer um erro, você poderá reverter suas alterações ou fazer push das alterações adicionais para corrigir o erro. As suas alterações não serão feitas no branch padrão até que você faça merge de seu branch.
Faça o commit e faça push das alterações no seu branch. Dê a cada commit uma mensagem descritiva para ajudar você e futuros contribuidores a entender quais alterações o commit contém. Por exemplo, fix typo ou increase rate limit.
Idealmente, cada commit contém uma alteração isolada e completa. Isso facilita reverter as suas alterações se decidirmos adotar uma abordagem diferente. Por exemplo, se você deseja renomear uma variável e adicionar alguns testes, coloque a variável renomeada em um commit e os testes em outro commit. Posteriormente, se você quiser manter os testes, mas reverter o novo nome da variável, você poderá reverter o commit específico que continha a variável renomeada. Se você colocar o novo nome da variável e testar no mesmo commit ou espalhar o novo nome da variável por múltiplos commits, você gastaria mais esforço revertendo suas alterações.
Ao fazer commit e push das suas alterações, você fará backup do seu trabalho no armazenamento remoto. Isso significa que você pode acessar seu trabalho a partir de qualquer dispositivo. Isso também significa que os seus colaboradores poderão ver o seu trabalho, responder a perguntas e fazer sugestões ou contribuições.
Continue a criar, fazer commit e fazer push das alterações no seu branch até que você esteja pronto para pedir feedback.
Tip
Crie um branch separado para cada conjunto de alterações não relacionadas. Isso facilita para os revisores darem feedback. Isso também facilita para você e para futuros colaboradores entenderem as alterações e reverter ou criar com elas. Além disso, se houver um atraso em um conjunto de alterações, as suas outras alterações também não serão atrasadas.
Criar uma solicitação de pull
Crie um pull request para pedir aos colaboradores feedback sobre suas alterações. A revisão de pull request é tão valiosa que alguns repositórios exigem uma revisão de aprovação antes que os pull requests possam ser mesclados. Se você quiser feedback ou conselhos antes de concluir suas alterações, você poderá marcar seu pull request como um rascunho. Para saber mais, confira Como criar uma solicitação de pull.
Ao criar uma pull request, inclua um resumo das alterações e qual o problema que elas resolvem. Você pode incluir imagens, links e tabelas para ajudar a transmitir estas informações. Se o seu pull request resolve um problema, vincule o problema para que os interessados no problema estejam cientes do pull request e vice-versa. Se você vincular com uma palavra-chave, o problema será fechado automaticamente quando o pull request for mesclado. Para saber mais, confira Sintaxe básica de gravação e formatação no GitHub e Vinculando uma pull request a um problema.
Além de preencher o texto do pull request, você pode adicionar comentários em linhas específicas do pull request para apontar algo explicitamente para os revisores.
Seu repositório pode ser configurado para solicitar uma revisão automaticamente de equipes específicas ou usuários quando um pull request for criado. Você também pode @mention manualmente ou solicitar uma revisão de pessoas ou de equipes específicas.
Se seu repositório tiver verificações configuradas para serem executadas em pull requests, você verá todas as verificações que falharam no seu pull request. Isso ajuda você a capturar erros antes de fazer merge do seu branch. Para saber mais, confira Sobre verificações de status.
Comentários de revisão do endereço
Os revisores devem deixar perguntas, comentários e sugestões. Os revisores podem comentar toda a solicitação de pull ou adicionar comentários a linhas ou arquivos específicos. Você e os revisores podem inserir imagens ou sugestões de código para esclarecer comentários. Para saber mais, confira Como revisar alterações nas solicitações de pull.
Você pode continuar a fazer commit e push das alterações em resposta às revisões. Sua pull request atualizará automaticamente.
Fazer merge do seu pull request
Depois que seu pull request for aprovado, faça merge do seu pull request. Isso fará o merge automático do seu branch para que suas alterações apareçam no branch padrão. GitHub mantém o histórico de comentários e commits no pull request para ajudar futuros contribuidores a entender suas alterações. Para saber mais, confira Mesclar uma solicitação de pull.
GitHub dirá se o seu pull request possui conflitos que precisam ser resolvidos antes do merge. Para saber mais, confira Resolvendo conflitos de mesclagem.
Configurações de proteção de branch podem bloquear o merge se seu pull request não cumprir certos requisitos. Por exemplo, você precisa de um certo número de revisões ou uma revisão de aprovação de uma equipe específica. Para saber mais, confira Sobre branches protegidos.
Excluir seu branch
Depois de realizar o merge do seu pull request, exclua o branch. Isso indica que o trabalho no branch foi concluído e impede que você ou outras pessoas de usar os branches antigos acidentalmente. Para saber mais, confira Excluir e restaurar branches em uma pull request.
Não se preocupe em perder informações. O histórico do seu pull request e commit não será excluído. Você sempre tem a opção de restaurar o branch excluído ou reverter seu pull request, se necessário.