Ti interessa restituire qualcosa alla comunità? Potresti avere trovato un bug in Django che ti piacerebbe vedere corretto, o ci potrebbe essere una piccola funzionalità che vorresti fosse aggiunta.
\nContribuire a Django è il miglior modo per affrontare le tue preoccupazioni. All’inizio questo può scoraggiare ma si tratta di un percorso «battuto» con la documentazione, i tool e la community, che ti supporta. Ti accompagneremo nell’intero processo, in modo che tu possa apprendere con degli esempi.
\nFor this tutorial, we expect that you have at least a basic understanding of\nhow Django works. This means you should be comfortable going through the\nexisting tutorials on writing your first Django app.\nIn addition, you should have a good understanding of Python itself. But if you\ndon’t, Dive Into Python is a fantastic (and free) online book for beginning\nPython programmers.
\nQuelli di voi che non hanno familiarità con i sistemi di controllo di versione e con Trac troveranno che questo tutorial e i suoi link includono le informazioni necessarie per cominciare. Comunque, se prevedete di contribuire a Django regolarmente, probabilmente vorrete leggere di più riguardo questi strumenti.
\nNelle intenzioni, questo tutorial tenta di spiegare il più possibile, per essere di aiuto alla maggior parte dei lettori.
\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:
\nInstallazione di Git.
Scarica una copia della versione di sviluppo di Django
Eseguire la suite di test di Django.
Writing a test for your changes.
Writing the code for your changes.
Testing your changes.
Mandare una pull request.
Dove cercare per ulteriori informazioni.
Una volta terminato il tutorial, puoi dare un’occhiata al resto della Django’s documentation on contributing. Contiene moltissime informazioni utili ed è una lettura imperdibile per chiunque voglia contribuire regolarmente a Django. Se hai delle domande, li probabilmente ci sono le risposte.
\n\n\nCome contributor, puoi aiutarci a tenere la Django community open e inclusa. Per favore leggi e segui i nostri Code of Conduct.
\nFor this tutorial, you’ll need Git installed to download the current\ndevelopment version of Django and to generate a branch for the changes you\nmake.
\nPer verificare se hai installato Git, inserisci «git» nella riga di commando. Se ricevi come risposta che questo commando non può essere trovato, dovrai scaricarlo ed installarlo, vai alla «pagina del download di Git»__.
\nSe non hai molta confidenza con Git, puoi sempre trovare informazioni riguardo ai suoi comandi (una volta installato) digitando «git help» nella riga di commando.
\nIl primo passo per contribuire a Django è ottenere una copia del codice sorgente.\nPrima, fare il fork : fork Django on GitHub. Dopo, dalla riga di commando, utilizza il comando «cd» per navigare fino alla directory dove vorrai posizionare la tua copia locale di Django.
\nScaricare la repository del codice sorgente Django usando il seguente comando
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nOra che hai una copia in locale di Django, puoi installarlo come installeresti qualunque altro pacchetto usando pip. Il modo più pratico per farlo è usando un ambiente virtuale, ovvero una feature all’interno di Python che ti permette di tenere separata una cartella di ogni pacchetto installato per ognuno dei tuoi progetti cosicché non interferiscano tra loro.
È una buona idea mantenere tutti i tuoi ambienti virtuali in un unico posto, per esempio in .virtualenvs/ all’interno della home.
Crea un nuovo ambiente virtuale avviando:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nIl percorso è dove il nuovo environment verrà salvato sul tuo computer.
\nIl passaggio finale nel settare il tuo ambiente virtuale è attivare:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nSe il commando source non è disponibile, puoi invece usare un punto:
$ . ~/.virtualenvs/djangodev/bin/activate\nDevi attivare il virtual environment tutte le volte che apri una nuova finestra del terminale.
\n\nIl nome dell’ambiente virtuale attualmente attivo è mostrato sulla linea di comando per aiutarti a tenere in mente quale stai usando. Tutto ciò che installi usando «pip» mentre questo nome è mostrato verrà installato in quell’ambiente virtuale, isolato da altri ambienti e dai pacchetti del sistema.
\nProcedi e installa la copia precedentemente clonata di 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\\\nThe installed version of Django is now pointing at your local copy by installing\nin editable mode. You will immediately see any changes you make to it, which is\nof great help when writing your first contribution.
\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.
\nYou can follow the tutorial for help in creating a\nDjango project.
\nQuando contribuisci a Django, è molto importante che i cambiamenti che apporti al codice non introducano bug in altre aree di Django. Un modo di controllare che Django funzioni ancora dopo aver apportato i cambiamenti è quello di lanciare la suite di test di Django. Se tutti i test hanno successo, allora puoi essere ragionevolmente sicuro che i tuoi cambiamenti funzionino e che non hai pregiudicato la funzionalità di altre parti di Django. Se non hai mai lanciato la suite di test di Django, è una buona idea lanciarla prima per cominciare ad avere familiarità con i suoi output.
\nPrima di lanciare la suite di test, entra nella directory tests/ di Django usando il comando cd tests ed installa le dipendenze per i test, lanciando:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nSe incontri un errore durante l’installazione, al tuo sistema potrebbe mancare una dipendenza per uno o più package Python. Consulta la documentazione del package per il quale si verifica l’errore o cerca nel web il messaggio di errore che ti si è presentato.
\nOra siamo pronti per far partire la nostra suite di test. Se stai usando GNU/Linux, macOS, o altre variazioni di Unix, esegui:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nAdesso siedi e rilassati. L’intera suite di test di Django si compone di centinaia di test e ci vorrà qualche minuto perchè giri, dipendentemente dalla velocità del tuo computer.
\nMentre la suite di test di Django è in esecuzione, vedrai scorrere lettere rappresentanti lo stato di ogni test man mano che viene completato. «E» indica che un errore è stato trovato, e «F» indica che le asserzioni del test sono fallite. Entrambi i casi sono considerati come fallimenti. Nel mentre, «x» e «s» hanno indicato probabili fallimenti e test omessi. I punti indicano i test passati.
\nQuando i test vengono saltati, questo accade a causa di librerie mancanti necessarie per eseguire il test; guarda Running all the tests per la lista delle dipendenze e assicurati di installare quelle relative ai test delle modifiche che stai facendo (non ne avremo bisogno in questa guida). Alcuni test sono per specifiche banche dati e verranno saltati se non state utilizzando quelle relative ad essi. SQLite è la banca dati di default. Per eseguire i test usandone una differente, guarda Using another settings module.
\nUna volta che il test è terminato, dovresti venir salutato con un messaggio che ti informa se la suite di test ha avuto successo o ha fallito. Poichè non hai ancora fatto modifiche al codice Django, l’intera suite di test dovrebbe aver successo. Se invece fallisce o dà errore assicurati di aver seguito tutti i passaggi precedenti correttamente. Guarda Running the unit tests per ulteriori informazioni.
\nConsidera che l’ultima versione del ramo «main» potrebbe non essere sempre stabile. Quando sviluppi basandoti su «main», puoi controllare `Django's continuous integration builds`__ per determinare se i fallimenti sono relativi alla tua macchina o sono presenti nella build ufficiale di Django. Se controlli una build specifica, puoi vedere la sezione «Configuration Matrix» che mostra i fallimenti dovuti alla versione di Python e al database utilizzato.
\n\nPer questa guida, lavoreremo su un «ticket falso» come caso di studio. Queste sono le ipotesi:
\n\nAggiungeremo ora questa funzionalità e i test associati.
\nPrima di fare qualsiasi modifica, crea una nuova branch per il ticket:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nPuoi scegliere qualunque nome che desideri per il ramo, «ticket_99999» è un esempio. Tutte le modifiche fatte su questo ramo saranno specifiche per il ticket e non andranno a modificare la copia principale del codice che abbiamo clonato in precedenza.
\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.
\nOra vediamo il nostro esempio.
\nPer risolvere questo ticket, aggiungeremo una funzione make_toast() al modulo django.shortcuts. Prima, scriveremo un test che usa la funzione e controlla che il suo output sia corretto.
Naviga fino alla cartella di Django «tests/shortcuts/» e crea un nuovo file «test_make_toast.py». Aggiungi il seguente codice:
\nfrom 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")\nQuesto test controlla che «make_toast()» ritorna «toast».
\n\nPoichè non abbiamo fatto ancora alcuna modifica a «django.shortcuts», il nostro test dovrebbe fallire. Eseguiamo tutti i test nella cartella «shortcuts» per assicurarci che è proprio ciò che sta accadendo. «cd» nella cartella di Django «tests/» ed esegui:
\nLinux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nIf the tests ran correctly, you should see one failure corresponding to the test\nmethod we added, with this error:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nSe tutti i test vengono superati, assicurati di aggiungere il test mostrato in precedenza nella cartella e con il nome file appropriati.
\nSuccessivamente aggiungeremo la funzione make_toast().
Vai alla cartella django/ ed apri il file shortcuts.py. Alla fine, aggiungi:
def make_toast():\n return "toast"\nOra dobbiamo assicurarci che il test che abbiamo scritto in precedenza venga superato, quindi possiamo vedere se il codice che abbiamo scritto funziona correttamente. Ancora una volta, posizionati nella cartella Django tests/ ed esegui:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nTutto dovrebbe funzionare. In caso contrario, assicurati di aver aggiunto la funzione al file corretto.
\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.
\nPer eseguire l’intera suite test di Django, a riga di commando esegui``cd`` nella cartella tests/ di Django ed esegui:
Linux / 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'``.\nPer avere ulteriori informazione riguardo la scrittura della documentazione, includendo una spiegazione di cosa sia versionadded, controlla Writing documentation. Quella pagina include una spiegazione di come creare una copia della documentazione in locale, in modo da poter avere un’anteprima dell’HTML che verrà generato.
\nNow 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\nMostra le differenze tra la tua copia attuale di Django ( con le tue modifiche ) e la revisione di quello che avevi scaricato seguendo la guida.
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nUsa le freccettine per muoverti su e giu.
\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.
Per confermare le modifiche:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nQuesto apre l’editor di test per inserire il messaggio di commit. Segui le linee guida del :ref:”messaggio di commit<committing-guidelines>” e scrivi un messaggio 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\nPuoi creare una pull request vistando la Django GitHub page. Vedrai il tuo branch nella sezione «Your recently pushed branches». Clicca «Compare & pull request» di fianco.
\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».
\nCongratulazioni, hai imparato a fare una richiesta pull a Django! Dettagli su tecniche più avanzate di cui potresti aver bisogno sono in Working with Git and GitHub.
\nOra puoi utilizzare queste conoscenze aiutando a migliorare il codice di 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.
Chi vuole contribuire per la prima volta dovrebbe anche leggere la :doc:”documentazione per i nuovi contributori</internals/contributing/new-contributors/>” di Django. E” piena di buoni consigli per quelli di noi che sono nuovi nell’aiutare con Django.
Dopo questi, se sei ancora in cerca di altre informazioni sul contribuire, puoi sempre cercare nel resto della :doc:”documentazione di Django sul contribuire</internals/contributing/index>”. Contiene molte informazioni utili e dovrebbe essere la tua prima fonte di informazione per rispondere alle domande che potresti avere.
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 Triaging tickets for details.
\n