Guidelines de Desenvolvimento

Regras e práticas para guiar o desenvolvimento, padronizar o fluxo de trabalho e facilitar a colaboração.

Objetivo

Este documento descreve regras e práticas definidas para guiar o desenvolvimento de projetos. O objetivo é registrar decisões, padronizar o fluxo de trabalho e facilitar a colaboração e a qualidade técnica.

1. Língua

Padrão: Seja qual for a língua escolhida, regras gramaticais deverão ser seguidas à risca, e será solicitada correção em caso de erros. A equipe deverá decidir se usará português ou inglês para documentação, mensagens de commit, issues e PRs.

2. Fluxo de Trabalho GitHub

GitHub Projects

Utilizar o GitHub Projects para planeamento e acompanhamento do projeto.

Labels Customizadas

Urgente Usar quando a tarefa precisa de ser entregue muito brevemente.

Priorizada Deve ser entregue até à data final estipulada.

Bônus Não é obrigatório entregar.

Issues

Padrão de Título

O título da issue deve incluir uma ou duas tags. A primeira tag deve ser uma das principais, e a segunda deve ser referente à funcionalidade ou ficheiro.

documentação refatoração análise implementação teste ajuste

                                    Exemplo: [Implementação][Categoria] Implementação de endpoints de categoria.
                                

Corpo da Issue

Toda issue deve incluir a estrutura abaixo para garantir clareza. Não é obrigatório incluir todas.

Motivação: Porquê isso é necessário?
Objetivo: O que deve ser entregue?
Cenário: Passos ou contexto de uso.
Considerações: Restrições, escopo, decisões.
Testes: Ideias para testes unitários, critérios de aceitação e validação.

É possível e boa prática abrir também subissues.

Toda issue deve dar assign em quem for o responsável por ela.

[Documentação] Buscar por referências e templates para arquivos de documentação


  Motivação
  - Possuir todo o projeto bem documentado para o desenvolvimento, apresentação e posterioridade;


  Objetivo
  - Buscar por referências de:
    - Como documentar APIs
    - Como estruturar issues e PR (done, documentar)
    - README files
    - Guidelines de desenvolvimento


  Considerações
  - Nem tudo que será documentado deve ser mostrado na apresentação
  - Filtrar tópicos relevantes para apresentar ou dados que podem ser extraídos

Branches

Abrir diretamente na issue, através da webapp do GitHub. O nome é criado automaticamente.
Evitar abrir branch sem issue vinculada.

Commits

Regra: Commits curtos, focados num único assunto.

Formato recomendado com tag entre colchetes, seguindo o padrão Conventional Commits. O título do commit deve incluir uma ou duas tags (ex: impl, ajuste, documentacao, teste, refatoracao).

FAÇA


                                    [impl][categoria] endpoints e organizacao de pastas

NÃO FAÇA


                                    mudanca readme

Pull Requests

Exigência: É necessário Code Review antes do merge. Tanto nos comentários de review quanto nas respostas, a gramática e a clareza devem ser aplicadas.

Estrutura do Corpo do PR

Release Notes (RN): resumo objetivo do que passou a existir.
Testing Notes (TN): instruções claras de como validar.

Título: [nome da branch]


  RN:
  - Agora o sistema é capaz de ...


  TN:
  1) Seguir o cenário da issue
  2) Verificar que a feature ...

3. Padrões de Código

Indentação: 4 espaços

Variáveis Definir se será usado camelCase, PascalCase ou snake_case
Métodos Definir se será usado camelCase, PascalCase ou snake_case
Constantes Geralmente tudo em MAIÚSCULO.
Nomenclatura Preferir sempre nomes descritivos.