Documentação do negócio

Documentação técnica

\mathbb{PROCESSO \space DE \space DESENVOLVIMENTO}

Esta seção é dedicada a apresentar o processo de desenvolvimento do time, junto dela serão apresentados documentos referentes a maneira como o time se organizou e trabalha.

🔖 Sumário

• Git Workflow
  • Definition of Ready
  • Definition of Done
• Padrões Utilizados
  • Branches
  • Commits
  • Merge Requests
• Code Freezing

🚂 Git Workflow

Para que os trabalhos no repositório sigam um fluxo organizado de trabalho, vamos adotar o Git Flow um fluxo de trabalho que consiste em duas principais branches:

• Main: A branch principal, tendo todo o código final, validado e testado;
• Development: A branch de desenvolvimento, onde irá organizar os trabalhos realizados.

🚦 Definition of Ready

Para que uma tarefa seja considerada pronta para desenvolvimento, ela deve seguir as seguintes condições:

• Não possuir nenhuma outra tarefa que dependa dela;
• Comunicar e organizar com os colegas que estão vinculados à tarefa;
• Possuir o ambiente de desenvolvimento configurado de acordo com as regras. Mais detalhes em Instalação.

🏁 Definition of Done

Para que uma tarefa seja considerada concluída ela deve seguir as seguintes condições:

• O código deve estar funcional;
• Toda possível documentação deve ser criada (payloads, endpoints, ...);
• Todas revisões devem ter sido informadas e corrigidas;
• O merge request da tarefa deve ter sido revisado e aprovado por um AGES III;

🛠️ Padrões Utilizados

🌐 Idioma padrão

Como acordo, todas as branches, commits e merge requests devem ser descritos em inglês.

🔱 Branches

Para criar uma branch e começar a trabalhar nela, 3 comandos git serão essenciais, vejamos abaixo quais são eles:

git checkout develop # Vai para a branch ‘develop’.
git pull # Puxa as modificações remotas.
git checkout -b <NOME_DA_SUA_BRANCH_AQUI> # Cria uma nova branch.

Nos comandos acima, você estará trocando para a branch ‘develop’, puxando todas as modificações remotas, e criando uma nova branch a partir da branch ‘develop’, e também, a branch em uso passa a ser a criada. Você então passará a trabalhar na nova branch criada.

Os nomes das branches devem seguir o formato <tipo>/<código>, onde os <tipo> são os mesmos tipos usados nas tarefas cadastradas no Trello, e o <código> é o card number, que pode ser encontrado logo abaixo do título do card, seguido de um "#".

Exemplos:

• task/15
• build/12
• spike/11

Exceções

Caso a demanda que está sendo desenvolvida não esteja descrita em uma task em nosso board do Trello, devemos seguir o seguinte padrão:

<tipo>/<descrição_breve>

Ser o mais sucinto possível no nome da branch, caso necessite seja mais descritivo na abertura do MR

📦️ Commits

Para tornar mais consistentes as mensagens de commit, usamos o padrão Conventional Commits. Para seguir esse padrão, as mensagens, em geral, devem escritas seguindo no formato tipo(escopo): descrição, em que:

• o tipo, obrigatório, é um dos tipos possíveis de commit;
• o (escopo), opcional, sempre escrito entre parênteses, contextualiza o commit dentro do projeto, e pode ser tanto uma funcionalidade do produto, quanto uma questão técnica do projeto;
• a descrição, obrigatória, é uma mensagem escrita conforme a vontade do desenvolvedor, e descreve resumidamente o trabalho feito.

Exemplos do uso:

• feat: Implementation of sending the votes of each participant.
• fix(api): Correcting the submission of information to the database.
• docs: Describe commit patterns.
• build: dependencies updates.

A descrição é escrita de acordo com a vontade do desenvolvedor. O escopo não é pré-definido, mas o grupo deve procurar usar o mesmo nome quando falando do mesmo contexto/componente/etc; o escopo deve sempre ser um substantivo.

Os tipos são limitados; o Conventional Commits especifica dois -- "fix", que identifica uma correção em algo já existente, e "feat", que indica a adição de uma funcionalidade nova --, mas o time pode especificar outros, desde que use-os de forma consistente.

Tipos usados no time:

• "fix", para descrever soluções de problemas;
• "feat", para descrever funcionalidades adicionadas;
• "docs", para identificar trabalho na documentação do projeto;
• "build", para identificar trabalho na configuração do projeto.

Mais informações estão disponíveis no link: Conventional Commits.

Além desse padrão, estamos usando a ferramenta Husky para padronizar os commit. O husky roda dois comandos ao tentar fazer um commit, ele primeiro, verifica a mensagem do commit para ver se está de acordo com o padrão do projeto, e segundo, ele executa o comando lint-staged descrito no package.json

Para commits onde teve participação de mais de um autor. Siga o exemplo abaixo:

Co-Authored-By: Nome Sobrenome <[email protected]>

🤝 Merge Requests

Merge request(MR) deve ser criado apenas ao finalizar a task com todos seus objetivos atingidos. Ao criar o MR, o responsável entende que seu código está pronto para ser entregue em produção.

Cada projeto terá seu template de MR que deverá ser usado para descrever as mudanças realizadas. Campos não obrigatórios estarão descritos em comentários, os demais devem ser preenchidos pelo autor do MR.

Ao analisar um MR, caso o revisor note alguma correção a ser feita no código, o autor será avisado pelo canal de MRs do discord, iremos marcar o usuário no discord para enviar uma notificação. Uma vez que forem corrigidos os pontos levantados, o autor deve reagir à marcação feita no canal do discord com um emoji ✅ para sinalizar que o MR está pronto para reavaliação.

⛄ Code Freezing

É estabelecido um tempo onde se encerram os trabalhos de desenvolvimento antes de uma entrega, para garantir a qualidade da entrega, evitando possíveis bugs e problemas que possam surgir.

Foi determinado às 4h da manhã da quinta-feira, antes da entrega.