Interessado em retribuir um pouco para a comunidade? Talvez você tenha encontrado uma falha no Django que você gostaria de ver corrigida, ou talvez exista uma pequena funcionalidade que poderia ser adicionada.
\nA melhor maneira de ver os seus problemas serem resolvidos é contribuindo com o Django. Pode parecer intimidador no começo, mas é um caminho que dá para ser percorrido com a documentação, ferramentas e uma comunidade para suporte. Nós lhe guiaremos por todo o processo para que você possa aprender através de exemplos.
\nPara este tutorial, esperamos que você tenha pelo menos uma compreensão básica de como o Django funciona. Isso significa que você deve se sentir confortável em seguir os tutoriais existentes em writing your first Django app. Além disso, é importante ter um bom entendimento de Python em si. Caso contrário, o livro online Dive Into Python é uma fantástica (e gratuita) opção para programadores iniciantes em Python.
\nAqueles que não estão familiarizados com sistemas de controle de versão e Trac irão encontrar neste tutorial, e seus links inclusos, informações suficientes para iniciar. Entretanto, se você esta planejando contribuir com o Django regularmente, provavelmente você vai querer ler mais a respeito das destas diferentes ferramentas.
\nPara a maior parte, porém, este tutorial tenta explicar o máximo possível, tal que possa ser usado por um público mais amplo.
\n\nWe’ll be walking you through contributing to Django for the first time.\nBy the end of this tutorial, you should have a basic understanding of both the\ntools and the processes involved. Specifically, we’ll be covering the following:
\nInstalando Git.
Baixando uma cópia da versão de desenvolvimento do Django.
Executando suite de testes do Django.
Escrevendo um teste para suas alterações.
Escrevendo o código para suas alterações.
Testando suas alterações.
Submetendo um pull request.
Onde encontrar mais informações.
Uma vez que você terminar este tutorial, você pode olhar o restante da Documentação do Django sobre contribuição Ela contém muitas informações úteis e deve ser lida por quem deseja se tornar um contribuidor do Django. Caso tenha perguntas, a documentação provavelmente contem as respostas.
\n\n\nComo um contribuidor, você pode nos ajudar a manter a comunidade Django aberta e solidária. Por favor, leia e siga nosso ‘Código de conduta’ <https://www.djangoproject.com/conduct/>`_.
\nPara este tutorial, você precisará ter o Git instalado para baixar a versão de desenvolvimento atual do Django e gerar uma ramificação para as alterações feitas.
\nPara verificar se o Git está instalado ou não no seu sistema, digite git na linha de comando. Se o resultado for uma mensagem dizendo que o comando não pode ser encontrado, você terá que fazer o download e instalar o Git. Dê uma olhada em `Git's download page`__.
Caso não esteja familiar com o Git, você sempre pode achar mais sobre seus comandos (uma vez que estiver instalado) digitando “git help” na linha de comando.
\nO primeiro passo para contribuir com o Django é obter uma cópia do código-fonte. Primeiro, faça um fork do Django no GitHub. Então, a partir da linha de comando, use o comando cd para navegar até o diretório onde você deseja que sua cópia local do Django fique armazenada.
Baixe o código fonte do repositório do Django usando o seguinte comando:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nAgora que você tem uma cópia local do Django, você pode instalá-lo da mesma forma que você instalaria qualquer pacote usando pip. A maneira mais conveniente de fazer isso é usando um ambiente virtual que é um recurso embutido no Python que permite que você mantenha um diretório separado para os pacotes instalados de cada um dos seus projetos para que uns não interfiram com os outros.
É uma boa ideia manter todos os seus virtualenvs em um lugar, por exemplo em .virtualenvs/ no seu diretório pessoal.
Crie um novo ambiente virtual executando:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nO caminho é o local onde o novo ambiente será salvo em seu computador.
\nO último passo para configurar o seu ambiente virtual é ativá-lo:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nSe o comando source não estiver disponível, você pode tentar usar um ponto em vez disso:
$ . ~/.virtualenvs/djangodev/bin/activate\nVocê precisa ativar o ambiente virtual sempre que abrir uma nova janela do terminal.
\n\nO nome do ambiente virtual atualmente ativado é mostrado na linha de comando para ajudar você a acompanhar qual deles você está usando. Qualquer coisa que você instalar através do pip enquanto esse nome é exibido será instalado nesse ambiente virtual, isolado de outros ambientes e dos pacotes globais do sistema.
Vá em frente e instale a cópia anteriormente clonada do Django:
\nLinux / macOS
$ python -m pip install -e /path/to/your/local/clone/django/\nWindows
...\\> py -m pip install -e \\path\\to\\your\\local\\clone\\django\\\nA versão instalada do Django agora está apontando para sua cópia local ao instalar no modo editável. Você verá imediatamente quaisquer alterações que fizer, o que é de grande ajuda ao escrever sua primeira contribuição.
\nIt may be helpful to test your local changes with a Django project. First you\nhave to create a new virtual environment, install the previously cloned\nlocal copy of Django in editable mode,\nand create a new Django project outside of your local copy of Django. You will\nimmediately see any changes you make to Django in your new project, which is\nof great help when writing your first contribution, especially if testing\nany changes to the UI.
\nVocê pode seguir o tutorial para obter ajuda na criação de um projeto Django.
\nAo contribuir para o Django, é muito importante garantir que as alterações no seu código não introduzam bugs em outras partes do Django. Uma maneira de verificar se o Django ainda funciona após suas alterações é executando a suíte de testes do Django. Se todos os testes ainda passarem, você pode ter uma segurança razoável de que suas alterações funcionam e não quebraram outras partes do Django. Se você nunca executou a suíte de testes do Django antes, é uma boa ideia rodá-la uma vez antes de começar, para se familiarizar com seu resultado.
\nAntes de executar os testes, entre no diretório tests/ usando o comando cd tests e instale as dependências de teste executando o seguinte:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nSe você encontrar algum erro durante a instalação, talvez esteja faltando no seu sistema alguma dependência de um ou mais pacotes do Python. Consulte a documentação dos pacotes com falha ou faça uma busca na web com a mensagem de erro que você encontrou.
\nAgora estamos prontos para executar o conjunto de testes:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nAgora, sente-se e relaxe. A suíte de testes completa do Django tem milhares de testes e leva pelo menos alguns minutos para executar, dependendo da velocidade do seu computador.
\nEnquanto a suíte de testes do Django estiver sendo executada, você verá um fluxo de caracteres representando o status de cada teste, conforme vão sendo executados. “E” indica que foi lançado um erro durante o teste, “F” indica que as asserções do teste falharam. Ambos são considerados como se o teste tivesse falhado. Enquanto que “x” e “s” indicam falhas esperadas e testes ignorados, respectivamente. Pontos indicam que o teste passou.
\nNormalmente testes são pulados quando faltam bibliotecas externas necessárias para executar o teste; veja Rodando todos os testes para uma lista de dependências e para se certificar de instalar qualquer dependência relacionada com suas mudanças (nós não necessitamos de nenhuma para este tutorial). Alguns testes são específicos para um banco de dados de backend e serão ignorados se não testado com aquele backend. SQLite é o banco de dados do backend padrão nas configurações. Para executar os testes usando diferentes backends, veja Usando outro módulo settings.
\nAssim que os testes são finalizados, você deveria ser notificado com uma mensagem informando se a suíte de testes passou ou falhou. Uma vez que você não realizou mudanças no código do Django, toda a suíte de testes deveria passar. Se você receber notificação de falhas ou erros certifique-se de que você seguiu todos os passos anteriores de maneira apropriada. Ver executando-testes-de-unidade para mais informações.
\nNote que a mais recente branch “main” pode nem sempre estar estável. Quando estiver desenvolvendo na branch “main”, você pode checar os builds de integração contínua do Django para determinar se as falhas ocorrem especificamente na sua máquina ou se elas também estão presentes nos builds oficiais do Django. Se você clicar para ver um build em particular, você pode ver a “Configuration Matrix” que mostra as falhas divididas por versões do Python e banco de dados backend.
\n\nPara este tutorial, nós iremos trabalhar em um “ticket falso” como um caso de estudo. Aqui estão os detalhes imaginários.
\n\nNós iremos agora implementar este recurso e seus testes associados.
\nAntes de fazer qualquer alteração, crie uma nova branch para o ticket:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nVocê pode escolher qualquer nome que queira para um branch, “ticket_99999”é um exemplo. Todas as mudanças feitas neste branch serão específicas do ticket e não irão afetar a cópia principal do código que clonamos mais cedo.
\nIn most cases, for a contribution to be accepted into Django it has to include\ntests. For bug fix contributions, this means writing a regression test to\nensure that the bug is never reintroduced into Django later on. A regression\ntest should be written in such a way that it will fail while the bug still\nexists and pass once the bug has been fixed. For contributions containing new\nfeatures, you’ll need to include tests which ensure that the new features are\nworking correctly. They too should fail when the new feature is not present,\nand then pass once it has been implemented.
\nA good way to do this is to write your new tests first, before making any\nchanges to the code. This style of development is called\n`test-driven development`__ and can be applied to both entire projects and\nsingle changes. After writing your tests, you then run them to make sure that\nthey do indeed fail (since you haven’t fixed that bug or added that feature\nyet). If your new tests don’t fail, you’ll need to fix them so that they do.\nAfter all, a regression test that passes regardless of whether a bug is present\nis not very helpful at preventing that bug from reoccurring down the road.
\nAgora para nosso exemplo mão-na-massa.
\nPara resolver este ticket, adicionaremos uma função make_toast() ao módulo django.shortcuts. Primeiro vamos escrever um teste que tente usar a função e verificar se sua saída está correta.
Navegue para a pasta tests/shortcuts/ do Django e crie um arquivo test_make_toast.py. Adicione o código a seguir:
from django.shortcuts import make_toast\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), "toast")\nEste testa verifica que o make_toast() returna 'toast'.
Como ainda não fizemos nenhuma modificação no django.shortcuts, nosso teste deve falhar. Vamos rodar todos os testes na pasta shortcuts para ter certeza de que isso realmente acontece. cd para o diretório tests/ e execute:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nSe os testes forem executados corretamente, você deverá ver uma falha correspondente ao método de teste que adicionamos, com este erro:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nSe todos os testes passaram, depois irá querer ter certeza de que você adicionou o novo teste mostrado acima na pasta e arquivo apropriados.
\nEm seguida nós adicionaremos a função make_toast().
Navegue até a pasta django/ e abra o arquivo shortcuts.py. No seu final adicione:
def make_toast():\n return "toast"\nAgora precisamos nos assegurar de que o teste que escrevemos mais cedo passa, então podemos verificar se o código que adicionamos está funcionando corretamente. Novamente, vá para o diretório tests/ do Django e execute.
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nTudo deve passar. Caso contrário, certifique-se de que você adicionou corretamente a função ao arquivo correto.
\nOnce you’ve verified that your changes and test are working correctly, it’s\na good idea to run the entire Django test suite to verify that your change\nhasn’t introduced any bugs into other areas of Django. While successfully\npassing the entire test suite doesn’t guarantee your code is bug free, it does\nhelp identify many bugs and regressions that might otherwise go unnoticed.
\nPara executar toda a suíte de testes do Django, `` cd`` no diretório `` testes / `` do Django e execute:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nThis is a new feature, so it should be documented. Open the file\ndocs/topics/http/shortcuts.txt and add the following at the end of the\nfile:
``make_toast()``\n================\n\n.. function:: make_toast()\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nSince this new feature will be in an upcoming release it is also added to the\nrelease notes for the next version of Django. Open the release notes for the\nlatest version in docs/releases/, which at time of writing is 2.2.txt.\nAdd a note under the “Minor Features” header:
:mod:`django.shortcuts`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nPara mais informações sobre escrita de documentação, incluindo uma explicação sobre o que versionadded significa, verifique Escrevendo a documentação. Essa página também inclui uma explicação sobre como construir uma cópia local da documentação, de maneira que você possa pré-visualizar o HTML que será gerado.
Now it’s time to review the changes made in the branch. To stage all the\nchanges ready for commit, run:
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\nThen display the differences between your current copy of Django (with your\nchanges) and the revision that you initially checked out earlier in the\ntutorial with:
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nUse as teclas direcionais para mover para cima e para baixo.
\ndiff --git a/django/shortcuts.py b/django/shortcuts.py\nindex 7ab1df0e9d..8dde9e28d9 100644\n--- a/django/shortcuts.py\n+++ b/django/shortcuts.py\n@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):\n\n # Finally, fall back and assume it's a URL\n return to\n+\n+\n+def make_toast():\n+ return 'toast'\ndiff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\n Minor features\n --------------\n\n+:mod:`django.shortcuts`\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\n+\n :mod:`django.contrib.admin`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ndiff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt\nindex 7b3a3a2c00..711bf6bb6d 100644\n--- a/docs/topics/http/shortcuts.txt\n+++ b/docs/topics/http/shortcuts.txt\n@@ -271,3 +271,12 @@ This example is equivalent to::\n my_objects = list(MyModel.objects.filter(published=True))\n if not my_objects:\n raise Http404("No MyModel matches the given query.")\n+\n+``make_toast()``\n+================\n+\n+.. function:: make_toast()\n+\n+.. versionadded:: 2.2\n+\n+Returns ``'toast'``.\ndiff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py\nnew file mode 100644\nindex 0000000000..6f4c627b6e\n--- /dev/null\n+++ b/tests/shortcuts/test_make_toast.py\n@@ -0,0 +1,7 @@\n+from django.shortcuts import make_toast\n+from django.test import SimpleTestCase\n+\n+\n+class MakeToastTests(SimpleTestCase):\n+ def test_make_toast(self):\n+ self.assertEqual(make_toast(), 'toast')\nWhen you’re done previewing the changes, hit the q key to return to the\ncommand line. If the diff looked okay, it’s time to commit the changes.
Para cometer as alterações:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nIsso abre um editor de texto para digitar a mensagem do commit. Siga o guia de mensagens de commits e escreva uma mensagem tipo:
\nFixed #99999 -- Added a shortcut function to make toast.\nAfter committing the changes, send it to your fork on GitHub (substitute\n“ticket_99999” with the name of your branch if it’s different):
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nVocê pode criar um pull request visitando a página do Django no GitHub. Você verá sua branch abaixo de “Your recently pushed branches”. Clique em “Compare & pull request” depois.
\nPlease don’t do it for this tutorial, but on the next page that displays a\npreview of the changes, you would click “Create pull request”.
\nParabéns, você aprendeu como fazer um pull request para Django! Detalhes de técnicas mais avançadas que você pode precisar estão em Trabalhando com Git e GitHub.
\nAgora você pode contribuir para ajudar a melhorar a base de código do Django.
\nBefore you get too into contributing to Django, there’s a little more\ninformation on contributing that you should probably take a look at:
\nYou should make sure to read Django’s documentation on\nclaiming tickets and submitting pull requests.\nIt covers Trac etiquette, how to claim tickets for yourself, expected\ncoding style (both for code and docs), and many other important details.
Os contribuidores de primeira viagem devem ler o documentação sobre contribuidores de primeira viagem. Ele tem muitos bons conselhos para aqueles que são novos para ajudar com Django.
Depois disso, se você ainda estiver ansioso para obter mais informações sobre como contribuir, você sempre pode navegar pelo resto da documentação do Django em contribuição. Ele contém um monte de informações úteis e deve ser sua primeira fonte para responder quaisquer perguntas que você possa ter.
Once you’ve looked through some of that information, you’ll be ready to go out\nand find a ticket of your own to contribute to. Pay special attention to\ntickets with the “easy pickings” criterion. These tickets are often much\nsimpler in nature and are great for first time contributors. Once you’re\nfamiliar with contributing to Django, you can start working on more difficult\nand complicated tickets.
\nIf you just want to get started already (and nobody would blame you!), try\ntaking a look at the list of `easy tickets without a branch`__ and the\n`easy tickets that have branches which need improvement`__. If you’re familiar\nwith writing tests, you can also look at the list of\n`easy tickets that need tests`__. Remember to follow the guidelines about\nclaiming tickets that were mentioned in the link to Django’s documentation on\nclaiming tickets and submitting branches.
\nAfter a ticket has a branch, it needs to be reviewed by a second set of eyes.\nAfter submitting a pull request, update the ticket metadata by setting the\nflags on the ticket to say “has patch”, “doesn’t need tests”, etc, so others\ncan find it for review. Contributing doesn’t necessarily always mean writing\ncode from scratch. Reviewing open pull requests is also a very helpful\ncontribution. See Triagem de tickets for details.
\n