#+TITLE: Contributing to Functional Algorithms Design
#+AUTHOR: Alexandre Rademaker
#+LANGUAGE: pt_BR

Este guia te ajudará a contribuir com o projeto `FAD`, que consiste na
tradução e formalização em Lean dos algoritmos apresentados no livro
*Algorithm Design with Haskell*.

* Como contribuir passo a passo

** Crie uma Issue

Antes de começar a codificar, crie uma *Issue* descrevendo sua
proposta:

- Tipos de contribuição:
  
  - Implementação de estrutura de dados ou algoritmo
  - Prova de propriedades
  - Correção de bugs (uso de `sorry`, falhas etc.)
  - Refatorações ou melhorias

- Como criar:
  
  1. Vá em *Issues* no GitHub
  2. Clique em *New Issue*
  3. Dê um título claro e descritivo
  4. No corpo, detalhe:
     - Qual seção/capítulo do livro será abordada
     - O que será implementado, formalizado ou corrigido
     - No caso de bug, como reproduzir

Espere pelo feedback antes de iniciar o desenvolvimento.

** Clone o repositório

No terminal:

#+begin_src bash
git clone https://github.com/emap-taa-20251/fad.git
cd fad
#+end_src

Você não precisa clonar o repositório mais de uma vez para cada
contribuição, depois de clonado você poderá repetir os passos abaixo
para cada contribuição.

** Crie uma nova branch

Atualize sua cópia da branch principal e crie uma nova branch para sua
contribuição:

#+begin_src bash
git checkout main
git pull origin main
git checkout -b issue-XX  # substitua XX pelo número da sua issue
#+end_src

** Faça suas alterações e commits

Adicione arquivos modificados e faça commits com mensagens claras:

#+begin_src bash
git add path/to/seu_arquivo.lean
git commit -m "issue-XX: descrição clara da alteração"
#+end_src

*Dica:* Commits pequenos são mais fáceis de revisar.

** Envie sua branch (push)

#+begin_src bash
git push origin issue-XX
#+end_src

** Crie um Pull Request (PR)

No GitHub:

1. Clique em *Compare & pull request* ou crie um novo PR manualmente
2. Configure:
   - Base: =main=
   - Compare: =issue-XX=
3. No corpo do PR:
   - Descreva as alterações
   - Use ~Closes #XX~ para referenciar a issue
   - Explique detalhes relevantes

** Aguarde revisão

- Seu PR será revisado com comentários e sugestões.
- Faça novos commits e =git push= na mesma branch para atualizá-lo.
- Após aprovação, ele será mesclado à =main=.

* Boas práticas gerais

- Comece sempre por uma *Issue*
- Use títulos e descrições claras
- Mantenha os commits pequenos e temáticos
- Mantenha sua branch atualizada com a =main=:

#+begin_src bash
git checkout main
git pull origin main
git checkout NOME_DA_BRANCH
git merge main # recupera para a branch atual atualizações da main
#+end_src

* Boas práticas para mensagens de commit

Use mensagens de commit claras, concisas e no imperativo. Siga a convenção abaixo:

** Formato recomendado

#+begin_example
<tipo>(escopo opcional): descrição breve no imperativo

Corpo opcional explicando o que e por quê da mudança.

Rodapé opcional: referências a issues, breaking changes etc.
#+end_example

** Exemplos

#+begin_example
feat(lista): adiciona implementação de listas encadeadas

Implementação baseada na seção 2.3 do livro.
Inclui função de inserção ordenada.

Closes #42
#+end_example

** Tipos comuns (prefixos)

- ~feat~ :: nova funcionalidade
- ~fix~ :: correção de bug
- ~docs~ :: alterações na documentação
- ~style~ :: mudanças de formatação (semântica inalterada)
- ~refactor~ :: refatorações sem mudar o comportamento
- ~test~ :: testes adicionados ou modificados
- ~chore~ :: tarefas administrativas (CI, configs)

** Regras principais

- Use o imperativo: *"adiciona suporte"*, e não *"adicionando"*
- Mantenha a primeira linha com até 50 caracteres
- Separe o corpo com uma linha em branco
- Foque no *porquê*, além do *o quê*

Caso tenha dúvidas, procure o monitor ou professor. Boa contribuição!