Fretebras web dev flow 2.0

Já faz algum tempo que em nossas squads estamos adotando para os novos projetos de software o “GitHub flow”, que é um fluxo de trabalho leve e baseado em branch que suporta equipes e projetos em que as implantações são feitas com regularidade.

Este guia explica como e porquê esse fluxo de apenas seis passos se adere ao nosso modelo de trabalho atual, que não exige necessidade de um plano de releases a fim de manter múltiplas versões de um serviço em ambiente de produção, junto ao crescimento contínuo do nosso time de engenheiros geograficamente distribuídos.

Crie uma branch

Passo 1, Crie uma branch

Quando você estiver trabalhando em um projeto, terá várias idéias diferentes em andamento a qualquer momento, algumas das quais estão prontas para serem usadas e outras que não. As branchs existem para ajudá-lo a gerenciar esse fluxo de trabalho.

Ao criar um branch em seu projeto, você cria um ambiente em que pode experimentar novas idéias. As alterações feitas em um branch não afetam a ramificação master; Portanto, você pode experimentar e commitar alterações, seguro de que sua branch não será mesclada até que esteja pronta para ser revisada por alguém com quem você está colaborando.

git checkout -b refector_r1h1-refatora-autenticacao

ProTip

Branching é um conceito central no Git, e todo esse fluxo é baseado nele. Há apenas uma regra: qualquer coisa na ramificação master é sempre implantável, portanto não deve conter código quebrado, testes falhando e muito menos credenciais de acesso.

Por isso, é extremamente importante que seu novo branch seja criado fora do master ao trabalhar em um recurso ou uma correção. O nome do seu branch deve ser descritivo, separando palavras por “-”, (por exemplo: refactor_r1h1-refatora-autenticacao, feat_r1h2-cria-avatares-resolucao-retina), para que outros possam ver e compreender o que está sendo trabalhado.

Dicas para nomear seu branch seguindo o conceito tipo_ESCOPO:

• feat — será implementada uma nova funcionalidade
• fix — será implementada uma correção para resolver um problema existente
• refactor — será realizado algum refactor em parte do código que já funciona
• chore — será implementa alguma melhoria de código e/ou infraestrutura
• test — será desenvolvido algum novo cenário de teste para a aplicação
• doc — será feita alguma mudança na documentação

Adicionar commits

Passo 2, Adicionar commits

Depois que seu branch for criado, é hora de começar a fazer suas alterações. Sempre que você adiciona, edita ou exclui um arquivo, você deve fazer um commit e adiciona-lo ao seu branch. Esse processo de adição de commits acompanha o seu progresso enquanto você trabalha em uma feature-branch.

Os commits também criam um histórico transparente do seu trabalho para que outras pessoas possam seguir e entender o quê, e, porquê você as fez. Cada commit tem uma mensagem de confirmação associada, que é uma descrição que explica porque uma alteração específica foi feita. Além disso, cada commit é considerado uma unidade de mudança separada. Isso permite reverter as alterações se um erro for encontrado ou se você decidir seguir um caminho diferente.

Dicas gerais:

• Faça commits com seu email da Fretebras.
• Mantenha o .gitignore consistente com as mudanças no seu ambiente.
• Não permita credenciais de acesso vazarem no código fonte.
• Não versione arquivos gerenciados como dependência.
• Não versione arquivos de configuração.
• Não versione arquivos gerados automaticamente.

ProTip

As mensagens de commit são importantes, principalmente porque o Git rastreia suas alterações e as exibe como confirmadas quando são enviadas ao servidor. Ao escrever mensagens claras de commit, você pode facilitar o acompanhamento e feedback de outras pessoas.

Você sempre pode discriminar melhor a solução implementada nas mensagens de commit. 🤩

Abrir um Merge Request

Passo 3, abrir um MR

Um Merge Request (MR) permite iniciar discussões e colaborações sobre seus commits. Como esses MR estão totalmente integrados ao repositório Git subjacente, qualquer membro do time pode ver exatamente quais alterações seriam mescladas se aceitarem sua solicitação.

Você pode abrir um MR a qualquer momento durante o processo de desenvolvimento:

• Quando você tem pouco ou nenhum código, mas deseja compartilhar algumas capturas de tela ou idéias gerais.
• Quando está bloqueado criativamente e precisa de ajuda ou aconselhamento.
• Quando está pronto para que alguém revise seu trabalho.

Usando o sistema "@menção" no seu MR, você pode solicitar feedback de pessoas ou equipes específicas, estejam elas no final do corredor ou em até outro fuso horário.

Dicas para abrir um MR:

• Atualize seu branch master local (git checkout master, git pull --rebase). *1
• No seu feature-branch, efetue o rebase com o head do master (git checkout refactor_r1h1-refatora-autenticacao, git rebase master).
• Só então abra o MR.

O rebase em sua forma padrão de uso permite que suas alteração sejam realocadas adiante no histórico, recebendo todas as alterações isoladas no seu branch e alinhando-as como se acontecessem após as revisões atualizadas do master, sem as complicações de um reverse merge, alem de deixar o histórico mais limpo e linear.

ProTip

MR são úteis para contribuir com projetos e para gerenciar alterações em repositórios, pois fornecerá uma maneira de notificar os mantenedores sobre as alterações que você deseja que eles considerem antes de serem mescladas no branch principal.

Não está feliz com o histórico gerado por sua revisão?

• Considere realizar um squash para comprimir os vários commits em um só e manter o histórico mais limpo e reversível.

Entretanto cuidado, pois modificações no histórico geram novos identificadores e podem exigir reenvio forçado (git push --force) *3 dos seus commits, por isso deve ser usado apenas em branchs no qual você é o proprietário.

Discutir e revisar seu código

Passo 4, discutir e revisar seu código

Depois que uma MR é aberta, a pessoa ou equipe que está revisando suas alterações pode ter perguntas ou comentários. Talvez o estilo de codificação não corresponda às diretrizes do projeto, esteja faltando algo nos testes unitário ou talvez tudo esteja ótimo e tudo esteja em ordem.

As MR são projetadas para incentivar e capturar esse tipo de conversa.

Se alguém comentar que você esqueceu de fazer algo ou se houver um erro no código, você poderá corrigi-lo em seu branch e simplesmente efetuar a alteração. O repositório mostrará seus novos commits e qualquer feedback adicional que você receber na tela de visualização de MR.

Chame os diversos times para colaborar e não centralize somente aos Devs!

ProTip

Os comentários do MR são escritos em Markdown, para que você possa incorporar imagens, emojis (🤩), usar blocos de texto pré-formatados e outras formatações leves.

Deploy

Passo 5, deploy

Você pode realizar a implantação (deploy) a partir de um branch para teste final de produção antes de mesclar no master.

Depois que seu MR for analisado e o branch passar nos testes automatizados, você poderá implantar suas alterações no ambiente de staging. Se seu branch causar problemas, você poderá recuperá-lo implantando o master existente na produção.

Merge

Passo 6, merge

Agora que suas alterações foram verificadas na produção/staging, é hora de mesclar seu código no branch principal.

Depois de mesclados, as MR preservam um registro das alterações históricas no seu código. Por serem pesquisáveis, permitem que alguém volte na linha do tempo para entender porque e como uma decisão foi tomada.

Ao mesclar manualmente seu branch no master, use a opção --no-ff *2 para gerar um merge commit. Dessa maneira, você facilita o rastreamento, visualização e também a reversão dos recursos incrementados.

• git checkout master
• git merge --no-ff refactor_r1h1-refatora-autenticacao

ProTip

Ao incorporar determinadas palavras-chave no texto da sua solicitação de recebimento, você pode associar problemas ao código. Quando sua MR é mesclada, os problemas relacionados também podem ser fechados. Por exemplo, ao digitar a frase "Closes #123" você encerraria o issue/task de número #123 no repositório.

Dicas extras de configuração

*1) Sempre que precisar mesclar atualização upstream em seu feature-branch, faça-o com --rebase, a menos que haja mais pessoas trabalhando no mesmo branch (nesse caso, discuta quando será o melhor momento), ou se já houver um MR em aberto.

*2) Para garantir que você não se esqueça de adicionar --rebase ao fazer o pull e --no-ff durante o merge, é recomendado pré-definir essas configurações globalmente:

• git config --global pull.rebase true
• git config --global merge.ff fase

*3) Ao trabalhar em um branch compartilhado evite o force-pushing, entretanto caso seja realmente necessário, utiliza a opção --force-with-lease, evitando assim substituir o trabalho de outra pessoa.

*4) Nunca realize o --rebase em commits que já existiram em qualquer lugar, exceto no seu repositório local. Nesse caso opte pelo uso do merge.