[infra] Escrever tutorial de como contribuir para o pacote Python

[vmussa]

Tutorial completo

Referências: https://pandas-gbq.readthedocs.io/en/latest/contributing.html

Protocolo para merge de branchs

Descrição do problema

Todos os últimos PRs de infra, como por exemplo os #898 / #675 / #462 foram contaminados por merges que trouxeram outras branches pra dentro do PR, impossibilitando a visualização das mudanças específicas de cada PR. Ainda pior, no #898 alguns commits de merge que vieram do #675 criaram uma situação grave em que arquivos antigos sobrescreveriam arquivos novos da master, porque apareciam como mudanças, em vez de versões antigas. Me parece que isso tenha acontecido por conta de alguns commits que revertiam alguns outros commits de merge, o que fazia o git entender as versões antigas, resgatadas via revert, como acréscimos dos commits de revert que, em seguida, sobrescreveriam a master em caso de um futuro merge.

Possível solução

Um protocolo que defina as seguintes coisas:

Como criar uma branch nova?

Exemplo de workflow:

# acessa a master e a atualiza
git checkout master && git pull

# cria nova branch local a partir da master já atualizada
git checkout -b nova_branch

# depois de algum commits, sobe nova branch no github
git push -u origin nova_branch

Como atualizar a branch nova, para absorver as mudanças da branch master?

O que não fazer

• git pull master ou git pull origin master. Isso traz as mudanças de outras branches e commits de outros contextos (docs, dados etc.) para dentro do PR, poluindo seções como Files changed.
• Evitar force-pushes, reverts e outras técnicas de força bruta do git.

O que fazer

• git rebase master ou git rebase origin master. Tal como explicado na documentação oficial do git, o rebase permite um produto final igual ao merge, mas gera um histórico de mudanças mais limpo.

Como evitar a constante defasagem da branch nova com relação à master?

Talvez criar um limite temporal para cada novo PR? Dividir uma mudança grande em pequenos PRs? @vncsna tinha sugerido algo nesse sentido.

[JoaoCarabetta]

Fazer template de PR com esse tutorial.

Adicionar campos necessários para abrir PR de novas features.