Trabalhando com Git e GitHub¶

Publicando trabalho¶

You can publish your work on GitHub by running:

git push origin ticket_xxxxx

Quando acessar sua página no GitHub, irá perceber que um novo “branch” foi criado.

Se você está trabalhando em um ticket do Trac, você deve mencionar no ticket que o seu trabalho está disponível através da branch ticket_xxxxx do seu repositório no GitHub. Inclua um link para a sua branch.

Tenha em mente que a branch acima é chamada de “topic branch” no linguajar do Git. Você é livre para reescrever o histórico dessa branch, através do uso do git rebase por exemplo. Outras pessoas não deveriam basear o seu trabalho em uma branch como essa, porque os clones dela serão corrompidos quando você editar os seus commits.

There are also “public branches”. These are branches other people are supposed to fork, so the history of these branches should never change. Good examples of public branches are the main and stable/A.B.x branches in the django/django repository.

Quando você achar que o seu trabalho está pronto para ser enviado para o Django, você deve criar um pull request no GitHub. Um bom pull request significa:

• Commits com uma mudança lógica, seguindo o estilo de código,
• Mensagens bem formatadas para cada commit: uma linha de sumário e então parágrafos embutidos em até 72 caracteres depois dela – veja as regras de commit para mais detalhes.
• Documentação e testes, quando necessário – na verdade testes são sempre necessários, exceto para mudanças na documentação.

A suíte de testes deve passar e a documentação deve ser gerada sem quaisquer warnings.

Uma vez que tenha criado seu pull request, você deve adicionar um comentário no ticket do Trac relacionado explicando o que você fez. Em particular, você deve mencionar o ambiente no qual você rodou os testes, por exemplo: “all tests pass under SQLite and MySQL”.

Pull requests at GitHub have only two states: open and closed. The merger who will deal with your pull request has only two options: merge it or close it. For this reason, it isn’t useful to make a pull request until the code is ready for merging – or sufficiently close that a merger will finish it themselves.

Fazendo rebase de branches¶

No exemplo acima, você criou dois commits, o “Fixed ticket_xxxxx” e o “Added two more tests”.

Nós não queremos ter o histórico inteiro do seu processo de trabalho no seu repositório. O seu commit “Added two more tests” seria poluído e pouco amigável. Ao invés disso, nós preferimos ter apenas um commit contendo todo o seu trabalho.

Para retrabalhar o histórico da sua branch você pode esmagar os commits tornando todos eles uma coisa só através do uso interativo do rebase:

git rebase -i HEAD~2

O HEAD~2 acima é um atalho para os dois últimos commits. O comando acima irá abrir um editor mostrando os dois commits, prefixados com a palavra “pick”.

Mude “pick” na segunda linha para “squash”. Isso manterá o primeiro commit, e esmagará o segundo commit dentro do primeiro. Salve e feche o editor. Uma segunda janela do editor deverá abrir, de modo que você possa reescrever a mensagem de commit agora que ele está incluindo os seus dois passos.

Você também pode usar a opção “edit” no rebase. Desta forma você pode mudar um único commit, por exemplo para corrigir um erro de ortografia em uma docstring:

git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.

Se seu “branch” já está publicado no GitHyb, por exemplo se você está fazendo alterações pequenas para considerar uma revisão, você precisa forçar o “push” com as alterações:

git push -f origin ticket_xxxxx

Note that this will rewrite history of ticket_xxxxx - if you check the commit hashes before and after the operation at GitHub you will notice that the commit hashes do not match anymore. This is acceptable, as the branch is a topic branch, and nobody should be basing their work on it.

Depois que o upstream foi modificado¶

Quando o “upstream” (“django/django”) for alterado, você deve fazer um “rebase” no seu trabalho. Para isso, use o:

git fetch upstream
git rebase

The work is automatically rebased using the branch you forked on, in the example case using upstream/main.

O comando rebase remove todos os seus commits locais temporariamente, aplica os commits do upstream, e então aplica os seus commits locais novamente.

Se houver conflitos nos “merges”, precisamos resolvê-los e então usar o get rebase --continue. Em qualquer momento você pode usar o get rebase --abort para retornar ao estado original.

Note que você quer fazer rebase no upstream, e não merge do upstream.

A razão para isso é que ao fazer o rebase, os seus commits sempre ficarão no topo do trabalho realizado no upstream e não misturado com as mudanças do upstream. Desta forma a sua topic branch irá conter somente commits relacionados a ela, o que faz com que o processo de esmagar os seus commits fique mais simples.

Depois de revisar¶

É muito incomum receber qualquer porção de código não trivial incluída no core do Django sem quaisquer alterações sendo solicitadas pelos revisores. Neste caso, costuma ser uma boa ideia adicionar as mudanças na forma de um commit incremental para o seu trabalho. Isso permite que os revisores possam checar facilmente quais mudanças você fez.

Neste caso, faça as mudanças solicitadas pelo revisor. Faça commit tão frequentemente quanto necessário. Antes de publicar as mudanças, faça o rebase do seu trabalho. Se você adicionou mais dois commits, você pode rodar o seguinte comando:

git rebase -i HEAD~2

Esmague o segundo commit dentro do primeiro. Escreva uma mensagem de commit junto das linhas de:

Made changes asked in review by <reviewer>

- Fixed whitespace errors in foobar
- Reworded the docstring of bar()

Finalmente, faça o “push” do seu trabalho de volta para o seu respotitório do GitHub. Uma vez que não tenha tocado nos “commits” públicos durante o “rebase”, você não vai precisar forçar um “push” (force-push):

git push origin ticket_xxxxx

O seu pull request deve agora conter um novo commit também.

Note that the merger is likely to squash the review commit into the previous commit when committing the code.