02 ‐ Padrões de Projeto da Equipe
Nesta seção serão abordados os parâmetros e regras de desenvolvimento de projeto da equipe. A grosso modo, será explicado como a equipe se organizou para desenvolver o produto. Essa seção contará com os seguintes temas:
- Modelo e regras na criação de tasks
- Fluxo de desenvolvimento
- Regras de teste de código
- Modelo e regras de branch
- Modelo e regras de commits
- Padrão de documentação de endpoints para o Swagger
- Modelo e regras de pull-request
- Regras de review de pull-request
A fim de tornar mais dinâmico e eficiente o desenvolvimento, criamos este "padrão de tasks", seu objetivo é servir como um modelo e explanar o porque desse modelo. Primeiramente é válido deixar explicito que a equipe optou por gerenciar as tasks na plataforma do Github, na aba "Projects", logo, tanto regra quanto modelo q serão apresentados, são baseados nesse contexto.
O modelo é o seguinte:
nome do card - vertente
dificuldade - prioridade
### **_Oque fazer_**:
inserir descrição do que se deve fazer
### **_Restrições_**:
inserir restrições (caso haja)
### **_Falha_**:
inserir falhas possíveis/comuns que devem ser evitadas e como resolve-las (o que o sistema fará caso elas aconteçam).
### **_Conteúdo_**:
conteúdo a ser desenvolvido com este card, pode incluir o conteúdo que precisa ser visto ou acessado.
--------------------------------------------------------------------------------------------------------------------------------------------
### **_Aceitação_**:
- [ ] Inserir um parametro de aceitação para que a task seja dada como concluída e o pull-request seja feito
caso hajam casos de falhas eles precisam passar pela aceitação
--------------------------------------------------------------------------------------------------------------------------------------------
### **_Apoio_**:
qualquer material suplementar, que vá ajudar etc.
data inicio - data conclusão
Ver Exemplo
Este é um exemplo de como deve ficar o card ao ser aberto
- nome do card: É o nome da tarefa, precisa ser o mais simples possível;
- vertente: Front ou Back;
- dificuldade: o quão difícil é para a equipe de modo geral, realizar aquela tarefa;
- prioridade: o quão urgente é aquela tarefa?
- descrição: é a abordagem das instruções da tarefa, como fazer, atenções, tudo que envolve o processo dessa tarefa deve ser explicado;
- aceitação: quando a tarefa pode ser dada como concluída e abrir o pull-request?
- data inicio e data coclusão: o encarregado da tarefa deve inserir estes valores, quando começar e quando terminar a tarefa;
Você pode criar a task de modo manual, abrindo um draft no board e depois convertendo em issue e preenchendo os campos nescessários... ou pode fazer da seguinte maneira:
Ver exemplo de como abrir uma task
Comece indo até a aba: "Issues"
Depois selecione para criar uma nova Issue.
Selecione a opção de "Get started"
Ele irá criar a partir de um template, uma nova issue:
É muito importante que você linque a issue no project correto:
preencha os campos e clique em "submit new issue". Com tudo configurado, você irá linkar essa Issue a uma branch no repositorio correto:
No caso escolha entre o front e o back, neste exemplo vou escolher o front... Com o repositório, selecionado, vamos na opção create a branch:
Por fim confiure a branch corretamente, por exemplo, seu nome estará fora do padrão, arrume-o, certifiquesse que a opção: "checkout locally" está marcada e que o repositório está correto, por fim, clique em "create branch"
Por fim, arrume a posição no board desse card, pois ele estará em um uma tabela de "No status", mova ele para sua aba correta.
Para garantir uma organização eficiente e coerente entre os membros da equipe, seguimos um fluxo de desenvolvimento específico. Cada etapa é seguida de forma que o trabalho se mantenha linear e bem estruturado. Seguimos o seguinte fluxo: criação da branch, Testes de código, modelo e regras de commits, padrão de documentação de endpoints para o Swagger (quando necessário) e modelo e regras de pull-request
O teste de código é uma etapa essencial para garantir a qualidade do projeto. Definimos regras que devem ser seguidas para criação e execução de testes. Cada desenvolvedor é responsável por escrever o teste após o desenvolvimento de cada funcionalidade e também por testar seu código manualmente e assegurar que ele funcione como o esperado e não afete outras áreas do sistema.
Para uma melhor rastreabilidade e análise das tasks realizadas, foi definido um padrão ao criar novas branches, as mesmas levam o tipo, o título, e o id da task que está no scrum board.
O Git Flow é um modelo, uma estratégia ou, ainda, um fluxo de trabalho muito utilizado por equipes de desenvolvimento de software. Ele se destaca por auxiliar na organização do versionamento de códigos. O Git Flow é recomendado para projetos que utilizam versionamento semântico (semantic versioning) ou que precisam oferecer suporte a várias versões de seu software.
Segundo o próprio autor, Vincent Driessen, se o projeto exige entrega contínua, como normalmente ocorre em projetos, este modelo não é recomendado para esse tipo de cenário. Porque geralmente com o Git Flow são geradas branches de longa duração e branches de longa duração atrapalham a entrega contínua.
A equipe optou pela utilização do Git Flow pois existe uma grande quantidade de pessoas “commitando” dentro de um repositório, e o projeto possuí um ciclo de entrega agendada.
Siga os passos para utilizar o git-flow:
O padrão segue o seguinte modelo:
id_da_task-tag_do_tipo_da_branch/descricao
Segue abaixo as tags e seus respectivos tipos de branch:
| TAG | TIPO DE BRANCH |
|---|---|
| func | funcionalidade |
| corr | correção |
| refa | refatoração |
| perf | performance |
| mant | manutenção |
| oper | CI, integração, actions e deploy |
Note
É possível que o padrão de branchs mude, caso haja necessidade. Se isso acontecer, é de suma importância que o modelo e a tabela sejam atualizados.
Exemplo
No Scrum Board existe a task 'swagger' de id 1. Portanto, a nomeação da branch deve seguir próxima do seguinte modelo:
1-func/swagger
Warning
Evite caracteres especiais e acentuações nas branches.
Para melhor organização do time, foi criado um padrão que deve ser seguido na criação de commits. Esse padrão tem como objetivo facilitar o entendimento das alterações feitas nos trechos de código, promovendo agilidade na rastreabilidade de possíveis erros durante o desenvolvimento do projeto.
O padrão segue o seguinte modelo:
tag_do_tipo_do_commit: descricao_da_alteracao_do_commit
Segue abaixo as tags e seus respectivos tipos de commit:
| TAG | TIPO DE COMMIT |
|---|---|
| func | funcionalidade |
| corr | correção |
| refa | refatoração |
| perf | performance |
| mant | manutenção |
| oper | CI, integração, actions e deploy |
Note
É possível que o padrão de commits mude, caso haja necessidade. Se isso acontecer, é de suma importância que o modelo e a tabela sejam atualizados.
Exemplo
Realizei uma alteração no código-fonte que adiciona o endpoint de login à aplicação. Portanto, o commit deve seguir o seguinte modelo:
func: adicionar o endpoint de login
Warning
Preze pelo espaço entre os dois pontos e a descrição da alteração do commit. Além disso, evite caracteres especiais e acentuações nos commits.
Todo o endpoint do API deve ser documentado através do @extend_schema usado pela biblioteca drf_spectacular para a criação do Schema utilizado no Swagger.
Sempre acima da função de cada método do respectivo endpoint deve ser codificado um @extend_schema contendo parameters (se necessário), request (se necessário) e response com os status dos possíveis retornos.
Exemplo:
from .models import User
from .serializers import UserSerializer
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from drf_spectacular.utils import extend_schema
class UserViewSet(APIView)
@extend_schema(
responses={
200: UserSerializer(many=True),
400: OpenApiResponse(
description="Bad Request",
examples={
"application/json": {
"message": "Erro ao listar usuários"
}
}
)
}
)
def get(self, request, format=None):
try:
users = User.objects.all()
serializer = UserSerializer(users, many=True)
return Response(serializer, status=status.HTTP_200_OK)
except:
return Response({'message': 'Erro ao listar usuários'}, status=status.HTTP_400_BAD_REQUEST)O pull-request deve ser aberto assim que todos os requisitos pedidos no card estiverem validados, ou seja, efetivamente quando a tarefa estiver feita. Ao abrir o pull-request certifique-se de que a "base"; seja a main e aquela que será comparada seja a branch em questão. O padrão de nome para o pull-request não está bem definido, pois é abstrato, mas recomendamos utilizar o próprio nome da branch. Não é obrigatório inserir uma descrição para o pull-request, mas é interessante colocar a seguinte descrição:
Fixes Grupo-Syntax-Squad/Tupan#id-task
isso irá concluir automaticamente a task assim que o pull request for aprovado e mergeado.
O processo de revisão é importante para manter a qualidade e consistência do código. Para cada pull-request, um membro da equipe deve revisá-lo, garantindo que o código esteja em conformidade com as regras e padrões estabelecidos e validando o impacto das alterações. É recomendável que a revisão seja feita por um desenvolvedor que não participou da implementação inicial para evitar viés e trazer uma perspectiva externa.
Assim que o pull-request for aprovado, não se esqueça de atualizar a release do repositório, seja ele do front ou do backend.
