This section explains how the community can contribute code to Django via pull\nrequests. If you’re interested in how mergers handle\nthem, see Enviando código.
\nAbaixo, iremos mostrar como criar um “pull request” no GitHub, contendo as mudanças para o ticket #xxxxx do Trac. Criando um “pull request” totalmente pronto, você tornará mais fácil o trabalho dos revisores, o que quer dizer que seu trabalho está mais próximo de ser “mergeado” no Django.
\nVocê também poderia fazer upload de um patch tradicional no Trac, mas isso é menos prático para os revisores.
\nDjango uses Git for its source control. You can download Git, but it’s often easier to install with\nyour operating system’s package manager.
\nO repositório do Django é hospedado no GitHub, e é recomendado que você também trabalhe usando o GitHub.
\nAfter installing Git, the first thing you should do is set up your name and\nemail:
\n$ git config --global user.name "Your Real Name"\n$ git config --global user.email "you@email.com"\nNote que user.name deve ser o seu nome real, e não o seu nick no GitHub. O GitHub deve saber o email que você usa pelo campo user.email, já que ele será usado para associar os seus commits com a sua conta no GitHub.
When you have created your GitHub account, with the nick “GitHub_nick”, and\nforked Django’s repository,\ncreate a local copy of your fork:
\ngit clone https://github.com/GitHub_nick/django.git\nThis will create a new directory “django”, containing a clone of your GitHub\nrepository. The rest of the git commands on this page need to be run within the\ncloned directory, so switch to it now:
\ncd django\nO seu repositório GitHub será chamado de “origin” no Git.
\nYou should also set up django/django as an “upstream” remote (that is, tell\ngit that the reference Django repository was the source of your fork of it):
git remote add upstream https://github.com/django/django.git\ngit fetch upstream\nYou can add other remotes similarly, for example:
\ngit remote add akaariai https://github.com/akaariai/django.git\nWhen working on a ticket, create a new branch for the work, and base that work\non upstream/main:
git checkout -b ticket_xxxxx upstream/main\nA flag -b cria uma nova branch para você localmente. Não hesite em criar novas branches mesmo para as coisas mais simples - esse é o motivo delas existirem.
\nIf instead you were working for a fix on the 1.4 branch, you would do:
\ngit checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x\nAssume the work is carried on the ticket_xxxxx branch. Make some changes and\ncommit them:
\ngit commit\nWhen writing the commit message, follow the commit message\nguidelines to ease the work of the merger. If you’re\nuncomfortable with English, try at least to describe precisely what the commit\ndoes.
\nIf you need to do additional work on your branch, commit as often as\nnecessary:
\ngit commit -m 'Added two more tests for edge cases'\nYou can publish your work on GitHub by running:
\ngit push origin ticket_xxxxx\nQuando acessar sua página no GitHub, irá perceber que um novo “branch” foi criado.
\nSe 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.
\nTenha 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\nto fork, so the history of these branches should never change. Good examples\nof public branches are the main and stable/A.B.x branches in the\ndjango/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:
\nCommits 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.
\nUma 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”.
\nPull requests at GitHub have only two states: open and closed. The merger who\nwill deal with your pull request has only two options: merge it or close it.\nFor this reason, it isn’t useful to make a pull request until the code is ready\nfor merging – or sufficiently close that a merger will finish it themselves.
\nNo exemplo acima, você criou dois commits, o “Fixed ticket_xxxxx” e o “Added two more tests”.
\nNó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.
\nTo rework the history of your branch you can squash the commits into one by\nusing interactive rebase:
\ngit rebase -i HEAD~2\nO 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”.
\nMude “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.
\nYou can also use the “edit” option in rebase. This way you can change a single\ncommit, for example to fix a typo in a docstring:
\ngit rebase -i HEAD~3\n# Choose edit, pick, pick for the commits\n# Now you are able to rework the commit (use git add normally to add changes)\n# When finished, commit work with "--amend" and continue\ngit commit --amend\n# Reword the commit message if needed\ngit rebase --continue\n# The second and third commits should be applied.\nIf your topic branch is already published at GitHub, for example if you’re\nmaking minor changes to take into account a review, you will need to force-push\nthe changes:
\ngit push -f origin ticket_xxxxx\nNote that this will rewrite history of ticket_xxxxx - if you check the commit\nhashes before and after the operation at GitHub you will notice that the commit\nhashes do not match anymore. This is acceptable, as the branch is a topic\nbranch, and nobody should be basing their work on it.
\nWhen upstream (django/django) has changed, you should rebase your work. To\ndo this, use:
git fetch upstream\ngit rebase upstream/main\nThe work is automatically rebased using the branch you forked on, in the\nexample 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.
\nSe 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.
\nA 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.
\nÉ 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.
\nIn this case, do the changes required by the reviewer. Commit as often as\nnecessary. Before publishing the changes, rebase your work. If you added two\ncommits, you would run:
\ngit rebase -i HEAD~2\nSquash the second commit into the first. Write a commit message along the lines\nof:
\nMade changes asked in review by <reviewer>\n\n- Fixed whitespace errors in foobar\n- Reworded the docstring of bar()\nFinally, push your work back to your GitHub repository. Since you didn’t touch\nthe public commits during the rebase, you should not need to force-push:
\ngit push origin ticket_xxxxx\nO seu pull request deve agora conter um novo commit também.
\nNote that the merger is likely to squash the review commit into the previous\ncommit when committing the code.
\nOne of the ways that developers can contribute to Django is by reviewing\npatches. Those patches will typically exist as pull requests on GitHub and\ncan be easily integrated into your local repository:
\ngit checkout -b pull_xxxxx upstream/main\ncurl -L https://github.com/django/django/pull/xxxxx.patch | git am\nIsso irá criar uma nova branch e então aplicar as mudanças do pull request nela. Neste momento você pode rodar os testes ou fazer qualquer coisa que você precise para investigar a qualidade do patch.
\nFor more detail on working with pull requests see the\nguidelines for mergers.
\nTrabalhe no GitHub se você puder.
Anuncie o seu trabalho no ticket do Trac adicionando um link para a sua branch no GitHub.
Quando você tiver algo pronto, faça um pull request.
Faça os pull requests tão bons quanto puder.
Quando estiver fazendo correçṍes no seu trabalho, use git rebase -i para esmagar os commits.
Quando o upstream tiver sido alterado, faça git fetch upstream; git rebase.