Ενδιαφέρεστε να συνεισφέρετε στην κοινότητα; Ίσως έχετε βρει κάποιο σφάλμα προγράμματος (bug) στο Django και θέλετε να διορθωθεί ή θέλετε να προσθέσετε κάποια επιπλέον λειτουργία ή χαρακτηριστικό.
\nΟ καλύτερος τρόπος να δείτε τις δικές σας προτάσεις-ιδέες να γίνονται πραγματικότητα είναι συνεισφέροντας στο Django. Αυτό στην αρχή ίσως σας φανεί περίπλοκο αλλά στην πραγματικότητα είναι αρκετά απλό. Θα σας καθοδηγήσουμε βήμα-βήμα μέσα σε όλη την διαδικασία ώστε να μπορέσετε να μάθετε μέσα από ένα παράδειγμα.
\nΓια αυτόν τον οδηγό (tutorial), θα πρέπει να γνωρίζετε τουλάχιστον τη βασική λειτουργία του Django. Αυτό σημαίνει ότι θα πρέπει να είστε εξοικειωμένοι με τους ήδη υπάρχοντες οδηγούς Γράφοντας το πρώτο σας Django app. Επίσης, θα πρέπει να γνωρίζετε αρκετά καλά τη γλώσσα προγραμματισμού Python. Αν πάλι όχι, το βιβλίο Dive Into Python είναι ένα εκπληκτικό (και δωρεάν) online βιβλίο για νέους προγραμματιστές στη γλώσσα Python.
\nΓια όσους από εσάς δεν είστε εξοικειωμένοι με τα εργαλεία συστημάτων ελέγχου εκδόσεων (VCS – version control system) και το Trac, δεν υπάρχει λόγος να ανησυχείτε. Αυτός ο οδηγός (και όποιοι σύνδεσμοι-links του) έχει τις απαραίτητες πληροφορίες για να ξεκινήσετε. Ωστόσο, ίσως να θέλετε να μάθετε περισσότερα σχετικά με αυτά τα εργαλεία, αν σκοπεύετε να συνεισφέρετε στο Django τακτικά.
\nΕν τούτοις, αυτός ο οδηγός στο μεγαλύτερο του μέρος, προσπαθεί να εξηγήσει όσα περισσότερα μπορεί, ώστε να μπορεί να φανεί χρήσιμος στο μεγαλύτερο δυνατό ευρύ κοινό.
\n\nΣε αυτόν τον οδηγό θα φτιάξουμε παρέα ένα patch για το Django και θα το συνεισφέρουμε (contribute) στην κοινότητα για πρώτη φορά. Στο τέλος αυτού του οδηγού, θα έχετε λάβει τις βασικές γνώσεις των εργαλείων (tools) και των διαδικασιών (processes) που εμπλέκονται. Πιο συγκεκριμένα, θα καλύψουμε τα ακόλουθα:
\nΕγκατάσταση Git.
Δημιουργία αντίγραφου της αναπτυξιακής έκδοσης (development version) του Django.
Εκτέλεση της σουίτας δοκιμών του Django (test suite).
Γράφοντας τεστ για το patch.
Γράφοντας κώδικα για το ίδιο το patch.
Πραγματοποίηση τεστ για το patch.
Υποβολή αιτήματος έλξης.
Που να κοιτάξετε για περισσότερες πληροφορίες.
Αφού ολοκληρώσετε τον οδηγό, μπορείτε να διαβάσετε το :doc:` εγχειρίδιο (documentation) του Django σχετικά με την συνεισφορά </internals/contributing/index>`. Περιέχει πολλές πληροφορίες και αν θέλετε να συνεισφέρετε τακτικά στο Django θα πρέπει να το διαβάσετε. Αν έχετε απορίες, τότε πιθανόν το εγχειρίδιο να έχει την απάντηση.
\n\n\nΩς συνεισφέρων, μπορείτε να μας βοηθήσετε να διατηρήσουμε την Django κοινότητα ανοιχτή (open) και περιεκτική (inclusive). Παρακαλούμε διαβάστε και ακολουθήστε το δικό μας Κώδικα Δεοντολογίας.
\nΓια αυτόν τον οδηγό θα χρειαστεί να έχετε εγκατεστημένο το Git ούτως ώστε να κατεβάσετε την αναπτυξιακή έκδοση (development version) του Django και να δημιουργήσετε patch αρχεία για τις αλλαγές που κάνετε.
\nΓια να ελέγξετε αν έχετε εγκατεστημένο το Git, γράψτε στη κονσόλα (ή στη γραμμή εντολών αν έχετε Windows) τη λέξη git. Αν βλέπετε μηνύματα που λένε ότι αυτή η εντολή δεν υπάρχει, θα χρειαστεί να κατεβάσετε το Git και να το εγκαταστήσετε. Δείτε πως, στην επίσημη σελίδα του Git.
Αν δεν είστε εξοικειωμένοι με το Git, μπορείτε να μάθετε περισσότερα σχετικά με τις εντολές του (αφού εγκατασταθεί) πληκτρολογώντας git help στην κονσόλα (ή στη γραμμή εντολών για χρήστες Windows).
Το πρώτο βήμα για την συνεισφορά στο Django είναι να αποκτήσετε ένα αντίγραφο του πηγαίου κώδικα. Πρώτα, κάντε fork το Django από το GitHub. Από την γραμμή εντολών, χρησιμοποιείστε την εντολή cd για να μεταβείτε στον φάκελο στον οποίο θέλετε να αποθηκεύσετε τον πηγαίο κώδικα του Django. Αν δεν υπάρχει κάποιος φάκελος της αρεσκείας σας, τότε χρησιμοποιήστε την εντολή mkdir για να τον δημιουργήσετε και μετά την εντολή cd επιθυμητός_φάκελος για να αποθηκεύσετε εκεί τον πηγαίο κώδικα.
Κατεβάστε το αποθετήριο (εφεξής repository ή repo) του πηγαίου κώδικα του Django χρησιμοποιώντας την ακόλουθη εντολή:
\n$ git clone git@github.com:YourGitHubName/django.git\nΤώρα που έχετε ένα τοπικό αντίγραφο του Django, μπορείτε να το εγκαταστήσετε, όπως ακριβώς ένα οποιοδήποτε πακέτο, με την χρήση της εντολής pip. Ο πιο βολικός και προτεινόμενος τρόπος να το κάνετε είναι μέσω ενός εικονικού περιβάλλοντος (εφεξής virtualenv, από τις λέξεις virtual environment) το οποίο είναι ένα προεγκατεστημένο χαρακτηριστικό (feature) της Python για την διαχείριση ξεχωριστών εγκαταστάσεων ανά εφαρμογή. Η φιλοσοφία είναι ότι κρατάτε σε ξεχωριστό φάκελο (περιβάλλον) τα πακέτα (π.χ Django 1.9 ή Django 1.10 ή κάποια third party εφαρμογή) που απαιτούνται για την εφαρμογή σας (π.χ Django app) και έτσι κάθε εφαρμογή δεν θα παρεμβαίνει με τις υπόλοιπες.
Είναι καλή πρακτική να κρατάτε όλα τα virtualenvs σε ένα σημείο, για παράδειγμα στο φάκελο .virtualenvs/ μέσα στο home φάκελο σας. Δημιουργήστε το, αν δεν υπάρχει ήδη:
$ mkdir ~/.virtualenvs\nΤώρα δημιουργήστε ένα καινούργιο virtualenv (π.χ με το όνομα djangoenv) τρέχοντας την εντολή:
\n$ python3 -m venv ~/.virtualenvs/djangodev\nΗ διαδρομή (path) που εισαγάγατε αποτελεί και το καινούργιο virtualenv το οποίο θα αποθηκευτεί στον υπολογιστή σας.
\n\n\nΤο τελευταίο βήμα σχετικά με την ολοκλήρωση του virtualenv είναι η ενεργοποίηση του:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nΑν η εντολή source δεν είναι διαθέσιμη, χρησιμοποιήστε την τελεία, όπως:
$ . ~/.virtualenvs/djangodev/bin/activate\nΚάθε φορά που ανοίγετε μια κονσόλα (γραμμή εντολών) και σκοπεύετε να αλληλεπιδράτε με την εφαρμογή σας, θα πρέπει σε κάθε κονσόλα να ενεργοποιείτε το virtualenv. Το εργαλείο virtualenvwrapper θα σας φανεί πολύ χρήσιμο και βολικό για τέτοιου είδους καταστάσεις.
\nΌταν ένα virtualenv ενεργοποιηθεί, το πρόθεμα στη γραμμή εντολών θα είναι το όνομα του virtualenv σας μέσα σε παρένθεση. Οποιοδήποτε πακέτο εγκαταστήσετε, από δω και στο εξής μέσω του pip, θα εγκατασταθεί στον φάκελο που αποθηκεύονται όλα τα virtualenvs (π.χ .virtualenvs) και πιο συγκεκριμένα μέσα στο φάκελο με την ονομασία του virtualenv σας (π.χ .virtualenvs/djangoenv). Με αυτό τον τρόπο κάθε virtualenv περιέχει τα δικά του πακέτα και έτσι επιτυγχάνεται η απομόνωση μεταξύ άλλων πακέτων άλλων virtualenvs και των πακέτων του συστήματος σας (global/system-wide). Εγκαταστήστε τώρα την έκδοση του Django που κατεβάσατε πριν μέσω του git clone:
$ pip install -e /path/to/your/local/clone/django/\nΗ εγκατεστημένη έκδοση του Django είναι τώρα μέσα στο virtualenv σας και μπορείτε να κάνετε import django σε Python κονσόλα χωρίς να σας επιστρέψει σφάλμα (cannot import module django). Τώρα μπορείτε να δείτε απ’ ευθείας τις αλλαγές που κάνετε σε αυτό το πακέτο, το οποίο είναι εξαιρετικά χρήσιμο, ειδικά όταν θα γράψετε το πρώτο σας patch αρχείο.
Σε αυτό τον οδηγό, θα χρησιμοποιήσουμε το ticket #24788 ως αντικείμενο μελέτης. Γι’ αυτό το λόγο θα χρειαστεί να μεταβούμε σε μια προγενέστερη έκδοση του Django πριν εφαρμοστεί αυτό το patch. Με άλλα λόγια θέλουμε να αναπαράγουμε το σφάλμα που εμφανιζόταν πριν, να γράψουμε το patch και να διορθώσουμε το σφάλμα εφαρμόζοντας το, στην τότε έκδοση. Αυτό θα μας βοηθήσει να δούμε όλα τα εμπλεκόμενα βήματα τα οποία απαιτούνται για να γραφτεί από την αρχή ένα patch (συμπεριλαμβάνοντας και την σουίτα δοκιμών του Django).
\nΈχετε υπόψη σας ότι παρόλο που θα χρησιμοποιήσουμε μια παλιά έκδοση του Django σε αυτόν τον οδηγό, εσείς θα πρέπει πάντα να χρησιμοποιείτε την τρέχουσα αναπτυξιακή έκδοση (development version) του Django όταν πρόκειται να γράψετε ένα patch για κάποιο ticket
\n\nΜεταβείτε στο root φάκελο του Django (είναι αυτός που περιέχει τους φακέλους django, docs, tests, AUTHORS, κλπ), ο οποίος βρίσκεται μέσα στο φάκελο με το όνομα του virtualenv σας. Αφού μεταβείτε εκεί, μπορείτε να κάνετε checkout (εντολή git) σε μια παλαιότερη έκδοση του Django, την οποία θα χρησιμοποιήσουμε σε αυτόν τον οδηγό:
$ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887\nΌταν συνεισφέρετε στο Django είναι πολύ σημαντικό ο κώδικας που γράφετε (π.χ για την επίλυση ενός ticket) να μην επιφέρει σφάλματα (bugs) σε άλλα σημεία του Django. Με άλλα λόγια όταν προσπαθείτε να διορθώσετε κάποια κομμάτια στον πηγαίο κώδικα του Django, να μην δημιουργούνται νέα σφάλματα σε άλλο σημείο του πηγαίου κώδικα. Ένας τρόπος για να γνωρίζετε ότι το Django τρέχει ορθά μετά τις αλλαγές σας, είναι τρέχοντας την σουίτα δοκιμών του Django (test suite). Αν όλα τα τεστ περάσουν, τότε μπορείτε εκ του ασφαλούς να ξέρετε ότι ο κώδικας σας δεν προκάλεσε σφάλματα αλλού. Αν δεν έχετε τρέξει ποτέ τη σουίτα δοκιμών του Django, μια καλή ιδέα είναι να την τρέξετε πριν ξεκινήσετε τη διαδικασία των αλλαγών (πριν την συγγραφή του patch), ούτως ώστε να εξοικειωθείτε με την εμφάνιση των αποτελεσμάτων του (output results).
\nΠριν τρέξετε την σουίτα, θα πρέπει να εγκαταστήσετε πρώτα κάποια πακέτα τα οποία είναι απαραίτητα για να ολοκληρωθούν τα τεστ. Μεταβείτε στον φάκελο tests/ (με την εντολή cd tests/) και τρέξτε την εντολή:
$ pip install -r requirements/py3.txt\nΑν αντιμετωπίσατε κάποιο πρόβλημα κατά την εγκατάσταση, ίσως να λείπει απ” το σύστημα σας κάποιο dependency (τα dependencies είναι και αυτά με τη σειρά τους πακέτα) για ένα ή περισσότερα Python πακέτα. Συμβουλευτείτε το εγχειρίδιο των πακέτων που δεν εγκαταστάθηκαν ή αναζητήστε στο ίντερνετ το σφάλμα, όπως ακριβώς αυτό εμφανίστηκε όταν προέκυψε.
\nΤώρα είμαστε έτοιμοι να τρέξουμε τη σουίτα δοκιμών του Django. Αν χρησιμοποιείτε GNU/Linux, Mac OS X ή κάποια άλλη Unix διανομή, τρέξτε:
\n$ ./runtests.py\nΚαθίστε αναπαυτικά και χαλαρώστε! Η σουίτα δοκιμών του Django περιλαμβάνει πάνω από 9,600 διαφορετικά τεστ. Αυτό σημαίνει ότι η διαδικασία ενδέχεται να διαρκέσει μεταξύ 5 – 15 λεπτά, ανάλογα την ισχύ του υπολογιστή σας.
\nΌσο τα τεστ τρέχουν, θα παρατηρήσετε διάφορες ακολουθίες χαρακτήρων οι οποίες αναπαριστούν την κατάσταση (status) του κάθε τεστ. Το E υποδηλώνει ότι προέκυψε σφάλμα κατά την εκτέλεση του συγκεκριμένου τεστ. Το F ότι τα assertions του τεστ απέτυχαν. Οι δύο ανωτέρω καταστάσεις δηλώνουν ότι το τεστ απέτυχε. Επίσης, τα x και s υποδηλώνουν αναμενόμενες αποτυχίες (expected failures) και παραλειπόμενα τεστ (skipped tests), αντίστοιχα. Οι τελείες υποδηλώνουν επιτυχή τεστ.
Τα παραλειπόμενα τεστ (τεστ που δεν έγιναν) προκύπτουν συνήθως λόγω έλλειψης κάποιων εξωτερικών βιβλιοθηκών (external libraries) οι οποίες χρειάζονται για να τρέξει το τεστ. Δείτε στο Τρέχοντας όλα τα τεστ για μια λίστα με όλα τα dependencies (εξαρτώμενα πακέτα – εξωτερικές βιβλιοθήκες). Επίσης σιγουρευτείτε ότι έχετε εγκαταστήσει τα απαραίτητα πακέτα (στα οποία εξαρτώνται τα τεστ) προτού τρέξετε κάποιο τεστ (δεν θα χρειαστούμε κάποιο από αυτά σε αυτόν τον οδηγό). Μερικά τεστ είναι γραμμένα και συνδέονται με μια συγκεκριμένη βάση δεδομένων και δεν θα τρέξουν αν δεν υπάρχει εγκατεστημένη η αντίστοιχη βάση δεδομένων καθώς και το πακέτο (βιβλιοθήκη) που συνδέει την database με το Django (π.χ για την PostgreSQL το πακέτο είναι το psycopg2). Η SQLite είναι η βάση δεδομένων που χρησιμοποιεί το Django ως προεπιλογή. Μπορείτε επίσης να τρέξετε τα τεστ χρησιμοποιώντας μια διαφορετική βάση δεδομένων.
Όταν ολοκληρωθούν τα τεστ, θα σας εμφανιστεί κάποιο μήνυμα που θα σας ενημερώνει για την επιτυχή ή όχι εκτέλεση τους. Εφόσον δεν έχετε κάνει κάποια αλλαγή μέχρι τώρα στον πηγαίο κώδικα του Django, όλα τα τεστ θα πρέπει να έχουν επιτυχή έκβαση. Αν δείτε τυχόν σφάλματα ή αποτυχίες κάποιων τεστ, σιγουρευτείτε ότι έχετε ακολουθήσει κατάλληλα τα ανωτέρω βήματα. Δείτε στο τρέχοντας τα unit τεστ για περισσότερες πληροφορίες. Αν χρησιμοποιείτε την Python 3.5+, θα υπάρξουν κάποιες αποτυχίες μερικών τεστ οι οποίες οφείλονται σε προειδοποιήσεις υποβάθμισης (deprecation warnings) στις οποίες μπορείτε να μην δώσετε σημασία. Αυτές οι αποτυχίες έχουν αποκατασταθεί στην τρέχουσα έκδοση του Django. Σας υπενθυμίζουμε ότι σε αυτόν τον οδηγό χρησιμοποιούμε μια παλιά έκδοση του Django.
\nΥπογραμμίζεται ότι η τελευταία αναπτυξιακή έκδοση του Django ενδέχεται να μην είναι σταθερή (stable). Όταν δουλεύετε με τέτοιου είδους εκδόσεις, μπορείτε να ενημερώνεστε μέσω των εκδόσεων συνεχούς ενσωμάτωσης του Django (Django’s continuous integration builds) για να διαπιστώσετε αν οι αποτυχίες των τεστ οφείλονται στο σύστημα σας ή οι αποτυχίες συμβαίνουν και στις επίσημες αναπτυξιακές εκδόσεις του Django. Αν κλικάρετε για να δείτε μια συγκεκριμένη έκδοση, μπορείτε να δείτε το «Configuration Matrix» το οποίο δείχνει τις αποτυχίες (failures) αναλυτικά ανά έκδοση Python και βάση δεδομένων.
\n\nΠριν κάνετε αλλαγές, δημιουργήστε ένα νέο τμήμα για το εισητήριο
\n$ git checkout -b ticket_24788\nΜπορείτε να επιλέξετε οποιοδήποτε όνομα θέλετε για το τμήμα, το «ticket_24788» είναι ένα παράδειγμα. Όλες οι αλλαγές που έγιναν σε αυτόν το τμήμα θα είναι ειδικά για το εισιτήριο και δεν θα επηρεάσουν το κύριο αντίγραφο του κώδικα που έχουμε κλωνοποιήσαμε νωρίτερα.
\nΣτις περισσότερες περιπτώσεις, για να θεωρηθεί ένα patch αποδεκτό για την ενσωμάτωση του στο Django, θα πρέπει να περιέχει τεστ. Για περιπτώσεις που αφορούν κάποια επιδιόρθωση σφάλματος (bug fix), θα πρέπει να γραφτεί ένα τεστ οπισθοδρόμησης (regression test) του οποίου η σημασία είναι η βεβαίωση ότι το σφάλμα (που επρόκειτο να διορθωθεί) δεν θα ξαναεμφανιστεί σε μεταγενέστερη έκδοση του Django. Ένα regression τεστ θα πρέπει να γραφτεί με τέτοιο τρόπο ούτως ώστε θα αποτυγχάνει (fail) όσο το σφάλμα θα υπάρχει και θα επιτυγχάνει όταν το σφάλμα διορθωθεί. Για patches τα οποία περιέχουν καινούργιο κώδικα (δεν προσπαθούν, δηλαδή, να διορθώσουν υπάρχον κώδικα αλλά προσθέτουν νέα χαρακτηριστικά-λειτουργία), θα χρειαστεί να συμπεριλάβετε τεστ τα οποία εξασφαλίζουν ότι το καινούργιο χαρακτηριστικό λειτουργεί ορθά (π.χ δημιουργία ενός καινούργιου django.db.models.fields ή δημιουργία καινούργιου template tag). Τα τεστ αυτά, θα πρέπει να αποτυγχάνουν όταν τα καινούργια αυτά χαρακτηριστικά δεν υπάρχουν (π.χ σε παλαιότερες εκδόσεις του Django) και αντιθέτως να επιτυγχάνουν όταν αυτά (τα χαρακτηριστικά) εμφανιστούν.
\nΜια καλή πρακτική για να επιτύχετε τα παραπάνω είναι να γράψετε πρώτα τα τεστ, προτού κάνετε οποιεσδήποτε αλλαγές στον πηγαίο κώδικα. Αυτού του είδους το development ονομάζεται test-driven development και μπορεί να εφαρμοστεί από απλά patches μέχρι ολόκληρα projects. Αφού γράψετε τα τεστ, μπορείτε να τα τρέξετε για να διαπιστώσετε ότι όντως αποτυγχάνουν (λογικό, αφού δεν έχετε γράψει ακόμη κώδικα που να διορθώνει το σφάλμα ή κώδικα που προσθέτει κάποιο καινούργιο χαρακτηριστικό στο Django). Αν τα τεστ σας δεν αποτυγχάνουν, θα πρέπει να φροντίσετε ώστε να το κάνουν. Αν ένα regression test περνά, ανεξαρτήτως αν το σφάλμα (bug) υπάρχει ή όχι, δεν βοηθάει καθόλου και θα δυσκολέψει το έργο (όχι μόνο το δικό σας) της αποσφαλμάτωσης (debugging) στο μέλλον.
\nΑς εργαστούμε λοιπόν στο παράδειγμα μας.
\nΤο ticket #24788 προτείνει μια μικρή προσθήκη ενός νέου χαρακτηριστικού: την δυνατότητα να προσδιοριστεί το class attribute με το όνομα prefix μέσα στις Form classes, ούτως ώστε:
[…] forms which ship with apps could effectively namespace themselves such\nthat N overlapping form fields could be POSTed at once and resolved to the\ncorrect form.\nΓια να επιλύσουμε αυτό το ticket, θα προσθέσουμε το prefix attribute στην BaseForm class. Έτσι, όταν θα δημιουργούμε instances από αυτή την class περνώντας ένα prefix όρισμα στην __init__() μέθοδο, το instance θα έχει καταχωρημένο αυτό το prefix attribute. Αλλά όταν δεν περνάμε (μέσω της __init__()) το prefix (ή περνάμε None) τότε θα χρησιμοποιηθεί το prefix σε επίπεδο class (το prefix attribute της class δηλαδή). Πριν γράψουμε αυτές τις αλλαγές όμως, θα γράψουμε μερικά τεστ τα οποία θα αντικατοπτρίζουν τις αλλαγές αυτές και θα ακολουθούν την ιδεολογία του Test Driven Development (TDD), όπως αναφέρθηκε παραπάνω.
Μεταβείτε στον φάκελο tests/forms_tests/tests/ και ανοίξτε το αρχείο test_forms.py. Προσθέστε τον ακόλουθο κώδικα στην γραμμή 1674, ακριβώς πριν την συνάρτηση test_forms_with_null_boolean:
def test_class_prefix(self):\n # Prefix can be also specified at the class level.\n class Person(Form):\n first_name = CharField()\n prefix = 'foo'\n\n p = Person()\n self.assertEqual(p.prefix, 'foo')\n\n p = Person(prefix='bar')\n self.assertEqual(p.prefix, 'bar')\nΑυτό το καινούργιο τεστ ελέγχει δύο πράγματα (τα οποία ήταν στις προδιαγραφές παραπάνω). Πρώτον, αν το instance δημιουργηθεί χωρίς prefix (δεν περαστεί στην __init__) τότε το p.prefix θα είναι ίσο με ένα προεπιλεγμένο prefix attribute που θα το ορίζει η εκάστοτε class. Δεύτερον, αν το instance δημιουργηθεί με κάποιο prefix attribute (πάντα μέσω της __init__) τότε το p.prefix θα ισούται με αυτό που πέρασε στην __init__.
Θυμηθείτε ότι δεν έχουμε πειράξει (ακόμη) τον πηγαίο κώδικα του Django (παρεμβαίνοντας συγκεκριμένα στην BaseForm). Το μόνο που αλλάξαμε είναι η προσθήκη ενός ακόμη τεστ (το οποίο θα πρέπει να αποτυγχάνει). Ας τρέξουμε όλα τα τεστ στον φάκελο forms_tests ούτως ώστε να σιγουρευτούμε ότι το δικό μας αποτυγχάνει. Από τη γραμμή εντολών, χρησιμοποιώντας την εντολή cd tests/ μεταβαίνετε στο φάκελο tests/ και τρέχετε την εντολή:
$ ./runtests.py forms_tests\nΑν τα τεστ εκτελεστούν με επιτυχία (προσοχή, αυτό δεν σημαίνει ότι πέρασαν, απλώς ότι εκτελέστηκαν επιτυχώς) τότε θα πρέπει να δείτε στο τεστ που γράψαμε πριν, αποτυχία (failure). Αν όλα τα τεστ πέρασαν, τότε κάτι δεν πήγε καλά και θα πρέπει να σιγουρευτείτε ότι προσθέσατε το παραπάνω τεστ στο σωστό φάκελο κάτω από τη σωστή class.
\nΠαρακάτω θα γράψουμε τον κώδικα που απαιτείται για να επιλύσουμε το ticket #24788.
\nΜεταβείτε στο φάκελο django/django/forms/ και ανοίξτε το αρχείο forms.py. Βρείτε την BaseForm class στη γραμμή 72 και προσθέστε το prefix class attribute ακριβώς κάτω από το field_order attribute:
class BaseForm(object):\n # This is the main implementation of all the Form logic. Note that this\n # class is different than Form. See the comments by the Form class for\n # more information. Any improvements to the form API should be made to\n # *this* class, not to the Form class.\n field_order = None\n prefix = None\nΌταν τελειώσετε την τροποποίηση του πηγαίου κώδικα του Django, πρέπει να σιγουρευτούμε ότι τα τεστ που γράψαμε νωρίτερα περνούν επιτυχώς, κάτι το οποίο θα επιβεβαιώσει ότι ο κώδικας που γράψαμε (στην BaseForm) είναι σωστός. Για να τρέξουμε τα τεστ στο φάκελο forms_tests, πληκτρολογήστε cd tests/ (για μετάβαση στον φάκελο tests/) και μετά:
$ ./runtests.py forms_tests\nOops, φαίνεται ότι κάναμε καλά και γράψαμε αυτό το τεστ νωρίτερα! Θα πρέπει να δείτε μια αποτυχία (failure) με το ακόλουθο exception:
\nAssertionError: None != 'foo'\nΠαραλείψαμε να προσθέσουμε μια δομή ελέγχου (conditional statement) μέσα στην μέθοδο __init__. Πηγαίνετε λοιπόν και αλλάξτε το self.prefix = prefix που βρίσκεται στη γραμμή 87 του αρχείου django/forms/forms.py, με το:
if prefix is not None:\n self.prefix = prefix\nΞανά-τρέξτε τα τεστ και πλέον όλα θα έχουν περάσει επιτυχώς. Αν όχι, σιγουρευτείτε ότι έχετε τροποποιήσει την BaseForm σωστά (όπως στο παράδειγμα) και επίσης έχετε γράψει το τεστ όπως στο παράδειγμα.
Όταν έχετε επιβεβαιώσει ότι το patch και το τεστ δουλεύουν ορθά, τότε είναι ώρα για ένα τελευταίο τεστ όλης της σουίτας του Django, ούτως ώστε να είστε σίγουροι ότι οι αλλαγές που κάνατε (στο συγκεκριμένο οδηγό, στην BaseForm) δεν επιφέρουν σφάλματα σε άλλα σημεία του Django. Ωστόσο, αν το patch περάσει επιτυχώς απ’ όλα τα τεστ, αυτό δεν εγγυάται ότι ο κώδικας σας δεν περιέχει σφάλματα (bug free). Βοηθάει, όμως, στην αναγνώριση πολλών σφαλμάτων που ειδάλλως θα περνούσαν απαρατήρητα.
Για να τρέξετε ολόκληρη τη σουίτα δοκιμών του Django, πληκτρολογήστε cd tests/ και τρέξτε:
$ ./runtests.py\nΕφόσον δε δείτε κάποια αποτυχία (failure), είστε έτοιμοι!
\nΤο εγχειρίδιο είναι ένα νέο χαρακτηριστικό και θα πρέπει να σας απασχολήσει στον ίδιο βαθμό με τον κώδικα που γράφετε. Κάθε κομμάτι που γράφετε μέσα στο εγχειρίδιο, βοηθάτε όχι μόνο τον εαυτό σας αλλά και τους υπόλοιπους προγραμματιστές οι οποίοι θα διαβάσουν τον κώδικα σας. Προσθέστε το ακόλουθο κομμάτι στη γραμμή 1068, στο τέλος του αρχείου django/docs/ref/forms/api.txt:
The prefix can also be specified on the form class::\n\n >>> class PersonForm(forms.Form):\n ... ...\n ... prefix = 'person'\n\n.. versionadded:: 1.9\n\n The ability to specify ``prefix`` on the form class was added.\nΕφόσον αυτό το νέο χαρακτηριστικό (prefix) θα είναι διαθέσιμο από την έκδοση 1.9 (και μετά) του Django, θα πρέπει να προστεθεί στις σημειώσεις έκδοσης (release notes) του Django 1.9. Το προσθέσαμε λοιπόν στη γραμμή 164 κάτω από την ενότητα «Forms» στο αρχείο docs/releases/1.9.txt:
* A form prefix can be specified inside a form class, not only when\n instantiating a form. See :ref:`form-prefix` for details.\nΓια περισσότερες πληροφορίες σχετικά με οδηγίες σύνταξης του εγχειριδίου (περιέχει και την εξήγηση του versionadded), δείτε στο γράφοντας το εγχειρίδιο. Αυτή η σελίδα εξηγεί και το πως να δημιουργήσετε ένα αντίγραφο του εγχειριδίου σας τοπικά (στον υπολογιστή σας), ούτως ώστε να δείτε πως θα φαίνεται online στο επίσημο site του Django.
Τώρα ήρθε η ώρα να περάσει μέσα από όλες τις αλλαγές που έγιναν στην ενημέρωσή μας. Για να εμφανίσετε τις διαφορές μεταξύ του τρέχοντος αντίγραφο σας του Django (με τις αλλαγές σας) και την αναθεώρηση που αρχικά ελέγξατε νωρίτερα στο σεμινάριο:
\n$ git diff\nΧρησιμοποιήστε τα βέλη για να κινηθείτε προς τα επάνω και προς τα κάτω.
\ndiff --git a/django/forms/forms.py b/django/forms/forms.py\nindex 509709f..d1370de 100644\n--- a/django/forms/forms.py\n+++ b/django/forms/forms.py\n@@ -75,6 +75,7 @@ class BaseForm(object):\n # information. Any improvements to the form API should be made to *this*\n # class, not to the Form class.\n field_order = None\n+ prefix = None\n\n def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,\n initial=None, error_class=ErrorList, label_suffix=None,\n@@ -83,7 +84,8 @@ class BaseForm(object):\n self.data = data or {}\n self.files = files or {}\n self.auto_id = auto_id\n- self.prefix = prefix\n+ if prefix is not None:\n+ self.prefix = prefix\n self.initial = initial or {}\n self.error_class = error_class\n # Translators: This is the default suffix added to form field labels\ndiff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt\nindex 3bc39cd..008170d 100644\n--- a/docs/ref/forms/api.txt\n+++ b/docs/ref/forms/api.txt\n@@ -1065,3 +1065,13 @@ You can put several Django forms inside one ``<form>`` tag. To give each\n >>> print(father.as_ul())\n <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>\n <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>\n+\n+The prefix can also be specified on the form class::\n+\n+ >>> class PersonForm(forms.Form):\n+ ... ...\n+ ... prefix = 'person'\n+\n+.. versionadded:: 1.9\n+\n+ The ability to specify ``prefix`` on the form class was added.\ndiff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt\nindex 5b58f79..f9bb9de 100644\n--- a/docs/releases/1.9.txt\n+++ b/docs/releases/1.9.txt\n@@ -161,6 +161,9 @@ Forms\n :attr:`~django.forms.Form.field_order` attribute, the ``field_order``\n constructor argument , or the :meth:`~django.forms.Form.order_fields` method.\n\n+* A form prefix can be specified inside a form class, not only when\n+ instantiating a form. See :ref:`form-prefix` for details.\n+\n Generic Views\n ^^^^^^^^^^^^^\n\ndiff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py\nindex 690f205..e07fae2 100644\n--- a/tests/forms_tests/tests/test_forms.py\n+++ b/tests/forms_tests/tests/test_forms.py\n@@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):\n self.assertEqual(p.cleaned_data['last_name'], 'Lennon')\n self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))\n\n+ def test_class_prefix(self):\n+ # Prefix can be also specified at the class level.\n+ class Person(Form):\n+ first_name = CharField()\n+ prefix = 'foo'\n+\n+ p = Person()\n+ self.assertEqual(p.prefix, 'foo')\n+\n+ p = Person(prefix='bar')\n+ self.assertEqual(p.prefix, 'bar')\n+\n def test_forms_with_null_boolean(self):\n # NullBooleanField is a bit of a special case because its presentation (widget)\n # is different than its data. This is handled transparently, though.\nΑφότου ρίξετε μια ματιά στο κείμενο, πιέστε το πλήκτρο q για να βρεθείτε πάλι στη γραμμή εντολών. Αν το περιεχόμενο του patch δείχνει σωστό, μπορείτε να κάνετε commit τις αλλαγές (υποτίθεται ότι βρίσκεστε στο root directory του project):
Για να κάνετε commit τις αλλαγές γράψτε:
\n$ git commit -a\nΗ παραπάνω εντολή ανοίγει έναν επεξεργαστή κειμένου για να γράψετε το μήνυμα του commit. Ακολουθήστε τις οδηγίες για ένα σωστό μήνυμα commit και γράψτε ένα μήνυμα όπως:
\nFixed #24788 -- Allowed Forms to specify a prefix at the class level.\nΑφού κάνατε commit το patch, στείλτε το στο fork που φτιάξατε στο GitHub (αντικαθιστώντας το «ticket_24788» με το όνομα του δικού σας branch, αν είναι διαφορετικό):
\n$ git push origin ticket_24788\nΜπορείτε να δημιουργήσετε ένα pull request πηγαίνοντας στην επίσημη σελίδα του Django στο GitHub. Εκεί θα δείτε το δικό σας branch κάτω από την ετικέτα «Your recently pushed branches». Κάντε κλικ στο «Compare & pull request».
\nΠαρακαλούμε να μην το κάνετε για αυτό τον οδηγό, αλλά στην επόμενη σελίδα που θα εμφανιστεί μια προεπισκόπιση του patch σας, θα κάνετε κλικ στο «Create pull request».
\nΣυγχαρητήρια! Μόλις μάθατε πως να κάνετε pull requests στο Django! Λεπτομέρειες για περισσότερο ανεπτυγμένες τεχνικές, που ίσως χρειαστείτε, θα βρείτε στο Working with Git and GitHub.
\nΤώρα μπορείτε να χρησιμοποιήσετε αυτές τις τεχνικές για καλό σκοπό βελτιώνοντας τον πηγαίο κώδικα του Django.
\nΠροτού ξεκινήσετε να γράφετε patches για το Django, υπάρχουν μερικές ακόμη πληροφορίες στις οποίες θα πρέπει να ρίξετε μια ματιά:
\nΘα πρέπει να διαβάσετε το εγχειρίδιο του Django σχετικά με κατάθεση patches και διεκδίκηση tickets. Καλύπτει την δεοντολογία του Trac, πως να διεκδικήσετε tickets για τον εαυτό σας, προτεινόμενο στυλ γραφής κώδικα για patches και πολλές άλλες σημαντικές λεπτομέρειες.
Όσοι από εσάς συνεισφέρουν για πρώτη φορά στο Django θα πρέπει να διαβάσουν το εγχειρίδιο του Django για τους νέους συνεισφέροντες. Περιέχει πολλές και χρήσιμες συμβουλές για εκείνους που θέλουν να βοηθήσουν-υποστηρίξουν την Django κοινότητα.
Κατόπιν των ανωτέρω, αν θέλετε να μάθετε ακόμη περισσότερα σχετικά με την συνεισφορά, μπορείτε πάντα να ανατρέχετε στην ενότητα του εγχειρίδίου του Django σχετικά με την συνεισφορά. Περιέχει τόνους πληροφορίας και θα πρέπει να είναι η πρώτη πηγή που θα κοιτάξετε για τυχόν ερωτήσεις ή απορίες που μπορεί να προκύψουν.
Αφού διαβάσατε και κατανοήσατε τη λογική των patches και των συνεισφορών, πιθανόν να είστε έτοιμοι να αναζητήσετε κάποιο ticket προκειμένου να γράψετε το κατάλληλο patch. Δώστε μεγάλη προσοχή στα tickets με το κριτήριο «easy pickings». Αυτού του είδους τα tickets είναι αρκετά απλά στη φύση τους (όπως απλό ήταν και αυτό που γράψαμε σε αυτόν τον οδηγό) και είναι κομμένα και ραμμένα στα μέτρα των νέων προγραμματιστών που θέλουν να συνεισφέρουν. Όταν εξοικειωθείτε με την συνεισφορά στο Django, μπορείτε να συνεχίσετε και να γράφετε patches\nκαι για πιο δύσκολα-περίπλοκα tickets. Η λογική είναι να ξεκινήσετε την επίλυση απλών tickets και σιγά σιγά να επιλύετε ακόμη πιο δύσκολα. Αν πάλι θέλετε να παραμείνετε στην επίλυση απλών tickets κανένα πρόβλημα.
\nΑν θέλετε να ξεκινήσετε άμεσα (και κανείς δε πρόκειται να σας κατηγορήσει γι” αυτό!), ρίξτε μια ματιά στη λίστα των easy tickets που χρειάζονται patches και στα easy tickets που έχουν patches αλλά χρειάζονται βελτίωση. Αν έχετε εξοικειωθεί με την συγγραφή τεστ, μπορείτε επίσης να κοιτάξετε τη λίστα των easy tickets που χρειάζονται τεστ. Θυμηθείτε μόνο τις κατευθηντήριες γραμμές (guidelines) σχετικά με την διεκδίκηση tickets οι οποίες αναφέρθηκαν στον σύνδεσμο του εγχειρίδίου του Django σχετικά με την :doc:` κατάθεση patches και διεκδίκηση tickets </internals/contributing/writing-code/submitting-patches>`.
\nΌταν ένα ticket συνοδεύεται από ένα patch, θα χρειαστεί να κοιταχτεί και από άλλους. Αφού κατατεθεί ένα pull request, θα πρέπει να ενημερώσετε τα metadata του ticket θέτοντας τα κατάλληλα flags πάνω σε αυτό, πχ «has patch», «doesn’t need tests» κλπ, ούτως ώστε άλλοι προγραμματιστές να μπορέσουν να το βρουν και να το κοιτάξουν και εκείνοι. Η συνεισφορά δεν σημαίνει πάντα να γράφετε ένα patch από το μηδέν. Αναθεωρώντας ήδη υπάρχοντα patches αποτελεί μια πολύ σημαντική συνεισφορά. Δείτε λεπτομέρειες στο Triaging tickets.
\n