Como contribuir
Histórico de versões
| Data | Versão | Descrição | Autor |
|---|---|---|---|
| 05/04/2024 | 1.0 | Criação do documento | Amanda Nobre |
Issues
Ao criar issues atente-se as seguintes questões:
- Já existe issue referente ao assunto que você pretende abordar na sua? Se sim, trabalhe a partir da issue já criada
- Adicione um título que sintetize bem o problema abordado na issue
- Adicione uma descrição adequada, de modo que qualquer membro do repositório consiga compreender qual é o problema
- Adicione ao menos um Assignee
- Adicione as Labels adequadas
- Adicione a milestone referente a sprint em que o problema será trabalhado
- Adicione um Estimate segundo as definições descritas nesse documento
Definição de Estimate
Deve-se definir uma estimativa de dificuldade (pontuação) à issue em questão, levando em consideração os seguintes critérios:
| Pontuação | Critérios |
|---|---|
| 1 | Tarefa bem simples, é possível ser feita em até 1h |
| 2 | Tarefa simples que leva algumas horas |
| 3 | Tarefa que pode levar algumas horas e necessita de alguma pesquisa |
| 5 | Tarefa não tão simples, precisa de pesquisa e deve levar alguns dias |
| 8 | Tarefa complexa, pode durar a semana toda |
| 13 | Tarefa muito complexa, provavelmente levará mais que uma sprint, melhor rever e dividir em mais de uma issue |
A pontuação da issue deverá ser levada a votação utilizando a ferramenta de planning poker do zenhub.
- Para issues que envolvem apenas um time, todo o time deverá ser adicionado ao planning poker.
- Para issues que envolvam mais de um time, apenas os colaboradores deverão ser adicionados ao planning poker.
Branches
Padronizar evita confusões e torna mais fácil a leitura e a procura por artefatos do projeto, e isso também se aplica à nomenclatura de branches. Por padrão, a nomenclatura de branches deve obedecer o seguinte formato:
<type>/<branch-name>
Type
O parâmetro type sinaliza qual o principal tipo de modificação realizada. Por padrão, utilizamos as seguintes palavras chaves:
| Type | Significado |
|---|---|
| feat | Novas funcionalidades para o usuário |
| fix | Correções de bugs para o usuário |
| docs | Modificações na documentação |
| style | Formatação, sem alterações no código de produção |
| refactor | Refatoração de código de produção |
| test | Adição e refatoração de testes (sem alterar código de produção) |
| chore | Atualizações genéricas sem alterações de código de produção |
Branch name
O parâmetro branch-name descreve de forma textual a atividade realizada dentro da branch. Por padrão, o nome da branch é escrito em inglês substituindo os espaços por hífen "-". Por exemplo: Create new tests for user se torna create-new-tests-for-user.
Atente-se para a criação de um nome coerente para sua branch, a fim de evitar confusões e incoerências.
Exemplos
Uma branch para adição de novos testes para a um user:
test/create-new-tests-for-user
Uma branch para correção de um bug na criação de user:
fix/remove-bug-from-user-creation
Criação de Branches
A partir do repositório desejado:
- Atualize seu repositório local buscando por novidades no repositório remoto.
git fetch
- Mude para a branch principal, seja develop ou main.
git checkout _branch-principal_
- Sincronize o estado da branch local com o estado da branch remota.
git reset --hard _branch-principal_
- A partir da branch atual, crie a nova branch obedecendo a convenção de nomes.
git checkout -b <type>/<branch>
Commits
A política de commits desse projeto é baseada no Conventional Commits v1.0.0.
Conventional Commits define um conjunto de regras simples para que as mensagens commit sejam consistentes no histórico de um repositório. Utilizar uma convenção como essa facilita a leitura do histórico, a identificação das mudanças realizadas por um commit e facilita a adoção de ferramentas de automação para gerar changelogs ou release notes.
Por padrão, as mensagens de commits devem seguir o seguinte formato:
<type>: <subject>
Type
Assim como para as branches, type descreve o tipo da modificação contemplada pelo commit. Por padrão, utilizamos as seguintes palavras chaves:
| Type | Significado |
|---|---|
| feat | Novas funcionalidades para o usuário |
| fix | Correções de bugs para o usuário |
| docs | Modificações na documentação |
| style | Formatação, sem alterações no código de produção |
| refactor | Refatoração de código de produção |
| test | Adição e refatoração de testes (sem alterar código de produção) |
| chore | Atualizações genéricas sem alterações de código de produção |
Subject
O parâmetro subject representa a mensagem que descreve o commit escrita em inglês. Uma boa prática que diz respeito a commits é a de sempre escrever subjects descritivos, isto é, sempre se preocupando em deixar bem claro os conceitos what e why.
Para clarificar as recomendações aqui mencionadas, confira estes exemplos:
Modifies user model
Ao avaliar esta mensagem de commit, o conceito what é superficial, pois não descreve especificamente o que foi alterado na model user. Já o conceito why sequer existe.
Modifies user's model name field to make it shorter
Ao avaliar esta mensagem de commit, quem quer que a leia entenderá o motivo, e do que se trata a alteração feita. Tal coisa permite poupar esfoço e tempo para entender do que o commit se trata.
Pull Request
Ao fazer um pull request atente-se para:
- Seguir o template configurado.
- Linkar o PR a sua Issue correspondente.
- Marcar um dos responsáveis para revisão.