Skip to content

Boas Práticas

Isabel Pires Meister edited this page Apr 25, 2025 · 5 revisions

Boas Práticas

Seguindo o modelo de três branches principais usadas aqui na BD - Main (Produção), Staging e Development (Dev) - o modelo de utilização de branches será baseado no Git Flow, mantendo essas três como fixas do repositório do backend. Considera-se uma boa prática pois usa-se a branch de Dev para testar novas funcionalidades e correções que forem necessárias. A branch de Staging permanece como a réplica de produção, onde também servirá para debbug de forma mais assertiva de possíveis erros que ocorrerem em produção. E temos a branch Main que é Produção, onde para alguma alteração subir para Prod, deve-se passar pelo fluxo: Dev -> Staging -> Prod.

Segue o fluxo:

  1. Dentro do seu repositório local entre na branch main: git checkout main
  2. Atualize a branch main local com a origem: git pull origin main
  3. Após estar atualizado, crie uma nova branch: git checkout -b [tipo da branch]/nome-da-branch

O tipo da branch pode ser: Feat, Fix, Refac, Chore, Doc ou Test
O nome da sua branch deve seguir lower_case e com - para separação de palavras.

  1. Faça as alterações de código necessárias, adicione as alterações na sua branch com git add e depois utilize padrões de commit na mensagem do git commit -m "mensagem-de-commit"
  2. Realize o Push para sua branch no github: git push -u origin [tipo da branch]/nome-da-branch

Seguindo com sua branch no GitHub:

  1. Abra o PR da sua branch apontando para o ambiente de Dev e então realize as validações e testes necessários.
  2. Abra um novo PR da sua branch apontando para Staging e então realize as validações e testes novamente (Agora estará sendo testado já simulando o ambiente de Produção, visto que Staging é uma réplica da Main)
  3. Abra um novo PR da sua branch apontando para Main. Aqui será necessário Code Review e também passar na pipeline de validações do PR (Python Lint, Pull Request Lint e etc.) e então poderá ser mergado para Main (Prod).

NÃO UTILIZE O UPDATE BRANCH dentro do seu PR nos ambientes de staging e dev!! Isso irá puxar todas as alterações do ambiente para seu PR e sujar sua branch, o que não é o correto. Caso você esteja comparando sua branch com a main pode utilizar o UPDATE BRANCH, assim teremos a certeza de que se houver conflito de código, será resolvido antes do merge com a main. Lembrando sempre de testar novamente caso o conflito de código ocorra (testar em staging novamente)!

Pull Request (PR)

Um PR bem feito serve também como documentação, facilitando assim o acompanhamento das mudanças no código e no repositório. Como também usamos o Lint para PRs aqui estão as boas práticas.

Título do PR:

Nas configurações do Lint o título do PR também conta, e também é a forma mais fácil de visualizar na lista dos pull requests sobre o que será tratado naquela mudança.

  • Utilizar no início do título em lowercase o tipo da alteração, como: feat, fix, refac, chore, doc ou test
  • Logo após o tipo da alteração, utilizar palavras chaves do que a mudança se refere, por exemplo: se arrumei o arquivo populate.py o título será fix: script populate

Descrição do PR:

Assim como um título organizado fica mais intuitivo o que a alteração irá se tratar, temos tópicos que devem ser usados por organização e também entendimento de: O que este PR se trata, de forma mais extensa e não muito técnica, quais foram as principais modificações. Como ou um resumo de como foi feito, de maneira mais técnica a explicação. E o Porque, qual motivação dessa mudança ou criação de código. Também é interessante que utilize de links relacionados, como a issue ou a task em questão. Sugestão de template completo:

What (O quê)

o que se trata

How (Como)

descrição mais técnica

Why (Porque)

motivação

Related Links (Links relacionados)

[ Issue/Task ] ( url_do_link )

Preenchimento do Menu Lateral:

  • É importante para que se esteja o máximo preenchido possível, mas deve-se ser obrigatório o preenchimento do Assignees com o/a(s) autor/a(s) do código realizado, independente se o PR é para produção ou não, desta forma se caso alguma dúvida que surgir ela poderá ser sanada com mais agilidade.
  • A secção de Labels é importante estar preenchida principalmente em PRs que irão para produção, tendo então uma forma de metrificação e também na facilidade de filtrar pela label que tenha interesse.
  • Como utilizamos o Projects do própria Github, não há necessidade de ser preenchido, pois pode gerar confusão no board.
  • Se houver Milestones é interessante que esteja selecionada.
  • Em Development é necessário que esteja preenchido para PRs que irão para Produção, assim dando encerramento á issue/task relacionada.

No nosso contexto se refere ao uso das ferramentas de pre-commit e github actions para garantir que o código mergeado tenha sempre o mesmo padrão, seja funcional ou estético. Para esse fim se recomenda instalar o projeto via poetry incluindo as dependências de desenvolvimento, e em seguida instalar os pre-commit hooks via código abaixo:

poetry install --with=dev && pre-commit install

Uma vez instalados esses hooks irão executar sempre que um commit for realizado. Atualmente alguns repositórios contam com fluxos que executam testes e checam a formatação de arquivos python, sql e yaml. É recomendado que um pull request seja mergeado apenas após todas as validações tenham finalizado com sucesso.

Clone this wiki locally