Scrivere la tua prima patch per Django¶
Introduzione¶
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.
Contribuire 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.
Per chi è questo tutorial?¶
Vedi anche
Se cerchi riferimenti sui dettagli per contribuire al codice, vedi la documentazione Writing code
Per questo tutorial, ci aspettiamo che tu abbia almeno una comprensione di base di come lavora Django. Questo significa che devi essere a tuo agio nel muoverti tra i tutoria esistenti in writing your first Django app. Inoltre devi avere una buona conoscenza di Python. Se non ce l’hai, `Dive Into Python`__ è un libro online fantastico (e gratuito) per programmatori Python alle prime armi.
Quelli 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.
Nelle intenzioni, questo tutorial tenta di spiegare il più possibile, per essere di aiuto alla maggior parte dei lettori.
Dove trovare aiuto:
If you’re having trouble going through this tutorial, please post a message on the Django Forum, django-developers, or drop by `#django-dev on irc.libera.chat`__ to chat with other Django users who might be able to help.
Di che parla questo tutorial?¶
Ti istruiremo su come inviare per la prima volta una patch per Django. Alla fine di questo tutorial, sarai in grado di capire sia quali strumenti che quali processi sono utilizzati. In particolare, comprenderemo i seguenti:
- Installazione di Git.
- Scarica una copia della versione di sviluppo di Django
- Eseguire la suite di test di Django.
- Scrivere un test per la tua patch.
- Scrivere il codice per la tua patch.
- Provare la tua patch.
- 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.
E” necessario Python 3!
La versione correnti di Django non sopporta Python 2.7. Scarica Python 3 da Python’s download page oppure attraverso il packet manager del tuo sistema operativo.
Per gli utenti Windows
Vedi Installa Python sulla documentazione di Windows per una guida aggiuntiva.
Codice di Condotta¶
Come contributor, puoi aiutarci a tenere la Django community open e inclusa. Per favore leggi e segui i nostri Code of Conduct.
Installazione di Git¶
Per questo tutorial, necessiterai di avere Git installato in modo da poter scaricare l’attuale versione per lo sviluppo di Django, e creare files per le modifiche che effettui.
Per 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»__.
Se non hai molta confidenza con Git, puoi sempre trovare informazioni riguardo ai suoi comandi (una volta installato) digitando «git help» nella riga di commando.
Ottenere una copia della versione di sviluppo di Django¶
Il primo passo per contribuire a Django è ottenere una copia del codice sorgente. Prima, 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.
Scaricare la repository del codice sorgente Django usando il seguente comando
$ git clone https://github.com/YourGitHubName/django.git
...\> git clone https://github.com/YourGitHubName/django.git
Connessione lenta?
Puoi aggiungere l’argomento «–depth 1» a «git clone» per saltare il download della cronologia commit di Django che riduce il trasferimento di dati da ~250 MB a ~70 MB.
Ora 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:
$ python3 -m venv ~/.virtualenvs/djangodev
...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev
Il percorso è dove il nuovo environment verrà salvato sul tuo computer.
Il passaggio finale nel settare il tuo ambiente virtuale è attivare:
$ source ~/.virtualenvs/djangodev/bin/activate
Se il commando source non è disponibile, puoi invece usare un punto:
$ . ~/.virtualenvs/djangodev/bin/activate
Devi attivare il virtual environment tutte le volte che apri una nuova finestra del terminale.
Per gli utenti Windows
Per attivare il tuo ambiente virtuale su Windows, avvia:
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
Il 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.
Procedi e installa la copia precedentemente clonata di Django:
$ python -m pip install -e /path/to/your/local/clone/django/
...\> py -m pip install -e \path\to\your\local\clone\django\
La versione installata di Django, in versione modificabile, ora punta alla tua copia locale. Vedrai immediatamente alcuni dei cambiamenti che vi apporterai, il che ti sarà di grande aiuto quando scriverai la tua prima patch.
Creazione di progetti con una copia locale di Django¶
It may be helpful to test your local changes with a Django project. First you have to create a new virtual environment, install the previously cloned local copy of Django in editable mode, and create a new Django project outside of your local copy of Django. You will immediately see any changes you make to Django in your new project, which is of great help when writing your first patch, especially if testing any changes to the UI.
You can follow the tutorial for help in creating a Django project.
Eseguire la suite di test di Django per la prima volta¶
Quando 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.
Prima 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:
$ python -m pip install -r requirements/py3.txt
...\> py -m pip install -r requirements\py3.txt
Se 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.
Ora siamo pronti per far partire la nostra suite di test. Se stai usando GNU/Linux, macOS, o altre variazioni di Unix, esegui:
$ ./runtests.py
...\> runtests.py
Adesso 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.
Mentre 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.
Quando 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.
Una 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.
Considera 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.
Nota
For this tutorial and the ticket we’re working on, testing against SQLite is sufficient, however, it’s possible (and sometimes necessary) to run the tests using a different database. When making UI changes, you will need to run the Selenium tests.
Lavorare su una funzionalità¶
Per questa guida, lavoreremo su un «ticket falso» come caso di studio. Queste sono le ipotesi:
Ticket #99999 – Permette di fare un toast
Django dovrebbe avere a disposizione una funzione «django.shortcuts.make_toast()» che ritorna «toast».
Aggiungeremo ora questa funzionalità e i test associati.
Creare una branch per la tua patch¶
Prima di fare qualsiasi modifica, crea una nuova branch per il ticket:
$ git checkout -b ticket_99999
...\> git checkout -b ticket_99999
Puoi 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.
Scrivere alcuni test per il tuo ticket¶
Nella maggior parte dei casi, affinchè una patch venga accettata in Django deve includere dei test. Per patch di correzione bug, questo significa che è necessario scrivere un test di regressione per assicurarsi che il bug non verrà mai reintrodotto in Django in futuro. Un test di regressione dovrebbe essere scritto in modo da fallire fintanto che il bug esiste ancora, e aver successo quando il bug invece è stato corretto. Per patch contenenti nuove funzionalità, avrai bisogno di includere test che assicurano che le nuove funzionalità stanno funzionando correttamente. Dovrebbero fallire se le nuove funzionalità non sono presenti, e aver successo quando invece sono implementate.
Un buon modo per farlo è quello di scrivere i nuovi test all’inizio, prima di fare modifiche al codice. Questo stile di sviluppo è chiamato “test-driven development’__ e può essere applicato su interi progetti o singole patch. Dopo aver scritto i test, puoi eseguirli per verificare che effettivamente falliscono (poichè non hai corretto il bug o non hai ancora aggiunto quella funzionalità). Se i tuoi nuovi test non falliscono, devi correggerli affinchè lo facciano. Dopotutto, un test di regressione che passa indipendentemente dal fatto che un bug sia presente o no non è molto utile nel prevenire che esso possa ricomparire in futuro.
Ora vediamo il nostro esempio.
Scrivere un test per il ticket #99999¶
Per 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:
from django.shortcuts import make_toast
from django.test import SimpleTestCase
class MakeToastTests(SimpleTestCase):
def test_make_toast(self):
self.assertEqual(make_toast(), "toast")
Questo test controlla che «make_toast()» ritorna «toast».
Ma questa cosa del testing sembra una cosa difficile…
Se non hai mai avuto a che fare con i test prima d’ora, potranno sembrarti un po” difficili da scrivere a prima vista. Per fortuna, fare i test è davvero un grande argomento nella programmazione, quindi ci sono molte informazioni:
- Per iniziare a scrivere test per Django, un buon primo passo è leggere i documenti in Writing and running tests.
- Buttati Into Python ( un libro online gratuito per i principianti sviluppatori di Python ) include alcuni ottimi progetti come `introduction to Unit Testing`__.
- Dopo aver letto queste cose, se vuoi qualcosa di più succulento per i tuoi denti, c’è sempre la documentazione Python
unittest
Eseguire il tuo nuovo test¶
Poichè 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:
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
If the tests ran correctly, you should see one failure corresponding to the test method we added, with this error:
ImportError: cannot import name 'make_toast' from 'django.shortcuts'
Se tutti i test vengono superati, assicurati di aggiungere il test mostrato in precedenza nella cartella e con il nome file appropriati.
Scrivere il codice per il tuo ticket¶
Successivamente aggiungeremo la funzione make_toast().
Vai alla cartella django/ ed apri il file shortcuts.py. Alla fine, aggiungi:
def make_toast():
return "toast"
Ora 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:
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
Tutto dovrebbe funzionare. In caso contrario, assicurati di aver aggiunto la funzione al file corretto.
Eseguire la suite di test di Django per la seconda volta¶
Once you’ve verified that your patch and your test are working correctly, it’s a good idea to run the entire Django test suite to verify that your change hasn’t introduced any bugs into other areas of Django. While successfully passing the entire test suite doesn’t guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed.
Per eseguire l’intera suite test di Django, a riga di commando esegui``cd`` nella cartella tests/ di Django ed esegui:
$ ./runtests.py
...\> runtests.py
Scrivere la Documentazione¶
This is a new feature, so it should be documented. Open the file
docs/topics/http/shortcuts.txt and add the following at the end of the
file:
``make_toast()``
================
.. function:: make_toast()
.. versionadded:: 2.2
Returns ``'toast'``.
Since this new feature will be in an upcoming release it is also added to the
release notes for the next version of Django. Open the release notes for the
latest version in docs/releases/, which at time of writing is 2.2.txt.
Add a note under the «Minor Features» header:
:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~
* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
Per 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.
Visualizzare l’anteprima delle tue modifiche¶
Ora è il momento di esaminare tutte le modifiche apportate nell’aggiornamento. Per preparare tutte le modifiche pronte per il commit, lancia:
$ git add --all
...\> git add --all
Mostra le differenze tra la tua copia attuale di Django ( con le tue modifiche ) e la revisione di quello che avevi scaricato seguendo la guida.
$ git diff --cached
...\> git diff --cached
Usa le freccettine per muoverti su e giu.
diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
# Finally, fall back and assume it's a URL
return to
+
+
+def make_toast():
+ return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
Minor features
--------------
+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
my_objects = list(MyModel.objects.filter(published=True))
if not my_objects:
raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+ def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast')
Quando hai finito di controllare l’anteprima della tua patch, clicca il tasto q per ritornare alla linea di comando. Se il contenuto della patch sembra giusto, è” il momento di committare i cambiamenti.
Salvare le modifiche nella patch¶
Per confermare le modifiche:
$ git commit
...\> git commit
Questo 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:
Fixed #99999 -- Added a shortcut function to make toast.
Inviare il commit e creare una pull request¶
Dopo aver committato la patch, invia il tuo fork su GitHub ( sostituendo «ticket_99999» con il nome del tuo branch, se è diverso):
$ git push origin ticket_99999
...\> git push origin ticket_99999
Puoi 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.
Per favore non farlo per questa guida ma sulla prossima pagina che mostra un’anteprima della patch, cliccheresti «Crea richiesta pull».
Prossimi passi¶
Congratulazioni, 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.
Ora puoi utilizzare queste conoscenze aiutando a migliorare il codice di Django.
Maggiori informazioni per nuovi contributori¶
Prima che anche tu inizi a scrivere patch per Django, ci sono altre informazioni a cui dovresti prima dare un’occhio:
- Dovresti assicurarti di leggere la documentazione Django su :doc:`rivendicare tickets and sottomettere patch</internals/contributing/writing-code/submitting-patches>”. Riguarda l’etichetta Trac, come rivendicare ticket per te stesso, stile di coding per le patch, e molti altri dettagli importanti.
- 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.
Cercare il tuo primo vero ticket¶
Dopo che avrai letto la documentazione riportata sopra, sarai pronto per andare a cercare un ticket per cui scrivere una patch. Presta particolare attenzione ai ticket indicati con il flag «easy pickings». Questi ticket di solito sono di semplice risoluzione e sono perfetti per i tuoi primi contributi. Quando avrai acquisito familiarità con le procedure per contribuire a Django, potrai passare a scrivere patch per ticket più complicati.
Se non vedi l’ora di cominciare (e nessuno si lamenterà per questo!), prova a dare un’occhiata alla lista dei `ticket facili che hanno bisogno di una patch`__ e dei `ticket facili che hanno una patch da migliorare`__. Se hai familiarità nella scrittura di test automatici, puoi anche dare un’occhiata alla lista dei `ticket facili che hanno bisogno di test`__. Ricorda di seguire le linee guida su come diventare l’assegnatario di un ticket che sono menzionate nel link alla documentazione di Django su reclamare i ticket e inviare patch.
Cosa fare dopo aver creato una pull request?¶
Dopo che un ticket ottiene una patch, necessita di una revisione da parte di un altro paio di occhi. Dopo aver inviato una pull request, aggiorna i metadati del ticket impostando il flag in modo che indichi «has patch», «doesn’t need tests» ecc…, così che altri possano trovarlo e rivederlo. Contribuire non vuol dire sempre scrivere una patch da zero. Rivedere le patch esistenti è un tipo di contributo altresì utile. Vedi Triaging tickets per ulteriori dettagli.
