Pular para conteúdo

Guia de contribuição

Algumas instruções legais, caso você queira contribuir com esse projeto ❤

O básico

Faça um fork do repositório do git na sua conta:

captura de tela exibindo o botão de fork da tela do repositório no github

Clone o seu fork do repositório:

$ Execução no terminal!
git clone https://github.com/seu_handle/fastapi-do-zero

Crie uma branch:

$ Execução no terminal!
git branch -m fix/aula-01-gramatica

Embora essa branch use conventional branch, isso não é um requisito, somente um exemplo.

Inicie seu ambiente:

Esse projeto é gerenciado pelo poetry

Caso você não o tenha instalado, pode instalar via pipx:

$ Execução no terminal!
pipx install poetry
$ Execução no terminal!
poetry install

Faça suas alterações: ...

Veja o material renderizado, caso sua alteração seja no texto:

$ Execução no terminal!
poetry run task serve #(1)!
  1. Inicia o servidor do mkdocs

Execute os testes, caso sua alteração envolva código:

$ Execução no terminal!
poetry run task test #(1)!
  1. executa os testes de todas as aulas do curso

⚠ Após a aula 10, os testes dependem do testcontainer para serem executados. Logo, seu docker precisa estar ativo para poder executar! ⚠

Adicione um changelog:

$ Execução no terminal!
towncrier create #(1)!
Issue number (`+` if none): + #(2)!
Fragment type (adicionado, correcoes, alterado, slides, ...): #(3)!
  1. Esse é o comando. Após isso o cli exibirá uma opção.
  2. Aqui você deve adicionar o número da issue, caso houver
  3. Aqui você deve escolher um dos tipos, o que mais se aproxima da contribuição que fizer. Após isso o editor se abrirá em modo de texto.

Para mais informações sobre isso, vá para changelogs

Faça um commit e push:

$ Execução no terminal!
git add .
git commit -m "fix: corrige a gramática na aula 01"
git push

Embora esse commit use conventional commits, isso não é um requisito, somente um exemplo.

Abra um pull request:

captura de tela exibindo o botão de Pull Request da tela do repositório no github

Lembre-se de que se seu Pull Request for associado a resolução de alguma issue, é importante que no corpo da mensagem do PR esteja:

closes #numero

Dessa forma, quem acompanha as issues sabe que o problema está sendo ou foi resolvido. E, quando a solicitação de PR for aceita, a issue é fechada automaticamente.

Slides

Caso sua alteração envolva o conteúdo de um slide (slides/brutos/*.md), é importante gerar a versão HTML do mesmo.

poetry run task slides

Os slides têm uma marcação especial de changelog, logo não se esqueça de adicionar um changelog para isso também, além do changelog da modificação.

Esse passo é importante, pois algumas modificações ficam somente no texto e, para conferir se foram atualizadas nos slides, a forma mais simples de ver é nos changelogs.

Changelogs

A ferramenta usada para os changelogs é o towncrier.

Uso básico:

$ Execução no terminal!
towncrier create #(1)!
Issue number (`+` if none): + #(2)!
Fragment type (adicionado, correcoes, alterado, slides, ...): #(3)!
  1. Esse é o comando. Após isso o o cli exibirá uma opção.
  2. Aqui você deve adicionar o número da issue, caso houver
  3. Aqui você deve escolher um dos tipos, o que mais se aproxima da contribuição que fizer. Após isso o editor se abrirá em modo de texto.

As entradas vão automaticamente para o diretório changelogs, caso isso apareça no seu diff.

Algumas coisas são importantes para geração do changelog:

  • É importante que sua mensagem de mudança não tenha mais de uma linha.
  • Após o texto da alteração, adicione o seu @ do git: 
    Correções gramaticais na aula 01, por [@dunossauro](https://github.com/dunossauro){:target="_blank"}
  • Sempre adicione o número da issue, caso ela exista, no campo Issue number, isso fará com que seu changelog seja associado à issue que foi discutida.

Após o Pull Request ser aceito, essas mensagens são exibidas na página de alterações.