Interested in giving back to the community a little? Maybe you’ve found a bug\nin Django that you’d like to see fixed, or maybe there’s a small feature you\nwant added (but remember that proposals for new features should follow the\nprocess for suggesting new features).
\nContributing back to Django itself is the best way to see your own concerns\naddressed. This may seem daunting at first, but it’s a well-traveled path with\ndocumentation, tooling, and a community to support you. We’ll walk you through\nthe entire process, so you can learn by example.
\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.
\nΓια όσους από εσάς δεν είστε εξοικειωμένοι με τα εργαλεία συστημάτων ελέγχου εκδόσεων (VCS – version control system) και το Trac, δεν υπάρχει λόγος να ανησυχείτε. Αυτός ο οδηγός (και όποιοι σύνδεσμοι-links του) έχει τις απαραίτητες πληροφορίες για να ξεκινήσετε. Ωστόσο, ίσως να θέλετε να μάθετε περισσότερα σχετικά με αυτά τα εργαλεία, αν σκοπεύετε να συνεισφέρετε στο Django τακτικά.
\nΕν τούτοις, αυτός ο οδηγός στο μεγαλύτερο του μέρος, προσπαθεί να εξηγήσει όσα περισσότερα μπορεί, ώστε να μπορεί να φανεί χρήσιμος στο μεγαλύτερο δυνατό ευρύ κοινό.
\n\nWe’ll be walking you through contributing to Django for the first time. By the\nend of this tutorial, you should have a basic understanding of both the tools\nand the processes involved. Specifically, we’ll be covering the following:
\nΕγκατάσταση Git.
Downloading a copy of Django’s development version.
Εκτέλεση της σουίτας δοκιμών του Django (test suite).
Writing a test for your changes.
Writing the code for your changes.
Testing your changes.
Υποβολή αιτήματος έλξης.
Που να κοιτάξετε για περισσότερες πληροφορίες.
Once you’re done with the tutorial, you can look through the rest of\nDjango’s documentation on contributing.\nIt contains lots of great information and is a must-read for anyone who’d like\nto become a regular contributor to Django. If you’ve got questions, it’s\nprobably got the answers.
\n\nΩς συνεισφέρων, μπορείτε να μας βοηθήσετε να διατηρήσουμε την Django κοινότητα ανοιχτή (open) και περιεκτική (inclusive). Παρακαλούμε διαβάστε και ακολουθήστε το δικό μας Κώδικα Δεοντολογίας.
\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.
\nΓια να ελέγξετε αν έχετε εγκατεστημένο το Git, γράψτε στη κονσόλα (ή στη γραμμή εντολών αν έχετε Windows) τη λέξη git. Αν βλέπετε μηνύματα που λένε ότι αυτή η εντολή δεν υπάρχει, θα χρειαστεί να κατεβάσετε το Git και να το εγκαταστήσετε. Δείτε πως, στην επίσημη σελίδα του Git.
Αν δεν είστε εξοικειωμένοι με το Git, μπορείτε να μάθετε περισσότερα σχετικά με τις εντολές του (αφού εγκατασταθεί) πληκτρολογώντας git help στην κονσόλα (ή στη γραμμή εντολών για χρήστες Windows).
Το πρώτο βήμα για την συνεισφορά στο Django είναι να αποκτήσετε ένα αντίγραφο του πηγαίου κώδικα. Πρώτα, κάντε fork το Django από το GitHub. Από την γραμμή εντολών, χρησιμοποιείστε την εντολή cd για να μεταβείτε στον φάκελο στον οποίο θέλετε να αποθηκεύσετε τον πηγαίο κώδικα του Django. Αν δεν υπάρχει κάποιος φάκελος της αρεσκείας σας, τότε χρησιμοποιήστε την εντολή mkdir για να τον δημιουργήσετε και μετά την εντολή cd επιθυμητός_φάκελος για να αποθηκεύσετε εκεί τον πηγαίο κώδικα.
Κατεβάστε το αποθετήριο (εφεξής repository ή repo) του πηγαίου κώδικα του Django χρησιμοποιώντας την ακόλουθη εντολή:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nΤώρα που έχετε ένα τοπικό αντίγραφο του Django, μπορείτε να το εγκαταστήσετε με το pip, όπως θα εγκαθιστούσατε οποιοδήποτε άλλο πακέτο. ;Ένας καλός τρόπος είναι η δημιουργία virtual environment (απομονωμένο περιβάλλον εργασίας), που θα σας επιτρέψει να έχετε ένα χωριστό φάκελο με τα απαραίτητα πακέτα για κάθε πρότζεκτ σας.
It’s a good idea to keep all your virtual environments in one place, for\nexample in .virtualenvs/ in your home directory.
Create a new virtual environment by running:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nΗ διαδρομή (path) που εισαγάγατε αποτελεί και το καινούργιο virtualenv το οποίο θα αποθηκευτεί στον υπολογιστή σας.
\nThe final step in setting up your virtual environment is to activate it:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nΑν η εντολή source δεν είναι διαθέσιμη, χρησιμοποιήστε την τελεία, όπως:
$ . ~/.virtualenvs/djangodev/bin/activate\nYou have to activate the virtual environment whenever you open a new\nterminal window.
\n\nThe name of the currently activated virtual environment is displayed on the\ncommand line to help you keep track of which one you are using. Anything you\ninstall through pip while this name is displayed will be installed in that\nvirtual environment, isolated from other environments and system-wide packages.
Go ahead and install the previously cloned copy of 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\ninstalling in editable mode. You will immediately see any changes you make to\nit, which is of great help when testing your first contribution.
\nWhen contributing to Django it’s very important that your code changes don’t\nintroduce bugs into other areas of Django. One way to check that Django still\nworks after you make your changes is by running Django’s test suite. If all the\ntests still pass, then you can be reasonably sure that your changes work and\nhaven’t broken other parts of Django. If you’ve never run Django’s test suite\nbefore, it’s a good idea to run it once beforehand to get familiar with its\noutput.
\nBefore running the test suite, enter the Django tests/ directory using the\ncd tests command, and install test dependencies by running:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nIf you encounter an error during the installation, your system might be missing\na dependency for one or more of the Python packages. Consult the failing\npackage’s documentation or search the web with the error message that you\nencounter.
\nNow we are ready to run the test suite:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nNow sit back and relax. Django’s entire test suite has thousands of tests, and\nit takes at least a few minutes to run, depending on the speed of your\ncomputer.
\nWhile Django’s test suite is running, you’ll see a stream of characters\nrepresenting the status of each test as it completes. E indicates that an\nerror was raised during a test, and F indicates that a test’s assertions\nfailed. Both of these are considered to be test failures. Meanwhile, x and\ns indicate expected failures and skipped tests, respectively. Dots indicate\npassing tests.
Τα παραλειπόμενα τεστ (τεστ που δεν έγιναν) προκύπτουν συνήθως λόγω έλλειψης κάποιων εξωτερικών βιβλιοθηκών (external libraries) οι οποίες χρειάζονται για να τρέξει το τεστ. Δείτε στο Τρέχοντας όλα τα τεστ για μια λίστα με όλα τα dependencies (εξαρτώμενα πακέτα – εξωτερικές βιβλιοθήκες). Επίσης σιγουρευτείτε ότι έχετε εγκαταστήσει τα απαραίτητα πακέτα (στα οποία εξαρτώνται τα τεστ) προτού τρέξετε κάποιο τεστ (δεν θα χρειαστούμε κάποιο από αυτά σε αυτόν τον οδηγό). Μερικά τεστ είναι γραμμένα και συνδέονται με μια συγκεκριμένη βάση δεδομένων και δεν θα τρέξουν αν δεν υπάρχει εγκατεστημένη η αντίστοιχη βάση δεδομένων καθώς και το πακέτο (βιβλιοθήκη) που συνδέει την database με το Django (π.χ για την PostgreSQL το πακέτο είναι το psycopg2). Η SQLite είναι η βάση δεδομένων που χρησιμοποιεί το Django ως προεπιλογή. Μπορείτε επίσης να τρέξετε τα τεστ χρησιμοποιώντας μια διαφορετική βάση δεδομένων.
Όταν ολοκληρωθούν τα τεστ, θα σας εμφανιστεί κάποιο μήνυμα που θα σας ενημερώνει για την επιτυχή ή όχι εκτέλεση τους. Εφόσον δεν έχετε κάνει κάποια αλλαγή μέχρι τώρα στον πηγαίο κώδικα του Django, όλα τα τεστ θα πρέπει να έχουν επιτυχή έκβαση. Αν δείτε τυχόν σφάλματα ή αποτυχίες κάποιων τεστ, σιγουρευτείτε ότι έχετε ακολουθήσει κατάλληλα τα ανωτέρω βήματα. Δείτε στο τρέχοντας τα unit τεστ για περισσότερες πληροφορίες. Αν χρησιμοποιείτε την Python 3.5+, θα υπάρξουν κάποιες αποτυχίες μερικών τεστ οι οποίες οφείλονται σε προειδοποιήσεις υποβάθμισης (deprecation warnings) στις οποίες μπορείτε να μην δώσετε σημασία. Αυτές οι αποτυχίες έχουν αποκατασταθεί στην τρέχουσα έκδοση του Django. Σας υπενθυμίζουμε ότι σε αυτόν τον οδηγό χρησιμοποιούμε μια παλιά έκδοση του Django.
\nNote that the latest Django «main» branch may not always be stable. When\ndeveloping against «main», you can check Django’s continuous integration\nbuilds to determine if the failures are specific to your machine or if they\nare also present in Django’s official builds. If you click to view a particular\nbuild, you can view the «Configuration Matrix» which shows failures broken down\nby Python version and database backend.
\n\nFor this tutorial, we’ll work on a «fake accepted ticket» as a case study. Here\nare the imaginary details:
\n\nWe’ll now implement this feature and associated tests.
\nΠριν κάνετε αλλαγές, δημιουργήστε ένα νέο τμήμα για το εισητήριο
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nYou can choose any name that you want for the branch, «ticket_99999» is an\nexample. All changes made in this branch will be specific to the ticket and\nwon’t affect the main copy of the code that we cloned earlier.
\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\ntest-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.
\nΑς εργαστούμε λοιπόν στο παράδειγμα μας.
\nIn order to resolve this ticket, we’ll add a make_toast() function to the\ndjango.shortcuts module. First we are going to write a test that tries to\nuse the function and check that its output looks correct.
Navigate to Django’s tests/shortcuts/ folder and create a new file\ntest_make_toast.py. Add the following code:
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")\nThis test checks that the make_toast() returns 'toast'.
Since we haven’t made any modifications to django.shortcuts yet, our test\nshould fail. Let’s run all the tests in the shortcuts folder to make sure\nthat’s really what happens. cd to the Django tests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nIf the tests ran correctly, you should see one failure corresponding to the\ntest method we added, with this error:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nIf all of the tests passed, then you’ll want to make sure that you added the\nnew test shown above to the appropriate folder and file name.
\nNext we’ll be adding the make_toast() function.
Navigate to the django/ folder and open the shortcuts.py file. At the\nbottom, add:
def make_toast():\n return "toast"\nNow we need to make sure that the test we wrote earlier passes, so we can see\nwhether the code we added is working correctly. Again, navigate to the Django\ntests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nEverything should pass. If it doesn’t, make sure you correctly added the\nfunction to the correct file.
\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.
\nΓια να τρέξετε ολόκληρη τη σουίτα δοκιμών του Django, πληκτρολογήστε cd tests/ και τρέξτε:
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:: 6.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 6.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'``.\nΓια περισσότερες πληροφορίες σχετικά με οδηγίες σύνταξης του εγχειριδίου (περιέχει και την εξήγηση του versionadded), δείτε στο γράφοντας το εγχειρίδιο. Αυτή η σελίδα εξηγεί και το πως να δημιουργήσετε ένα αντίγραφο του εγχειριδίου σας τοπικά (στον υπολογιστή σας), ούτως ώστε να δείτε πως θα φαίνεται online στο επίσημο site του Django.
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\nΧρησιμοποιήστε τα βέλη για να κινηθείτε προς τα επάνω και προς τα κάτω.
\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/6.2.txt b/docs/releases/6.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/6.2.txt\n+++ b/docs/releases/6.2.txt\n@@ -34,6 +34,11 @@\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:: 6.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.
Για να κάνετε commit τις αλλαγές γράψτε:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nΗ παραπάνω εντολή ανοίγει έναν επεξεργαστή κειμένου για να γράψετε το μήνυμα του commit. Ακολουθήστε τις οδηγίες για ένα σωστό μήνυμα commit και γράψτε ένα μήνυμα όπως:
\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\nΜπορείτε να δημιουργήσετε ένα pull request πηγαίνοντας στην επίσημη σελίδα του Django στο GitHub. Εκεί θα δείτε το δικό σας branch κάτω από την ετικέτα «Your recently pushed branches». Κάντε κλικ στο «Compare & pull request».
\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».
\nΣυγχαρητήρια! Μόλις μάθατε πως να κάνετε pull requests στο Django! Λεπτομέρειες για περισσότερο ανεπτυγμένες τεχνικές, που ίσως χρειαστείτε, θα βρείτε στο Working with Git and GitHub.
\nΤώρα μπορείτε να χρησιμοποιήσετε αυτές τις τεχνικές για καλό σκοπό βελτιώνοντας τον πηγαίο κώδικα του 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.
Όσοι από εσάς συνεισφέρουν για πρώτη φορά στο Django θα πρέπει να διαβάσουν το εγχειρίδιο του Django για τους νέους συνεισφέροντες. Περιέχει πολλές και χρήσιμες συμβουλές για εκείνους που θέλουν να βοηθήσουν-υποστηρίξουν την Django κοινότητα.
Κατόπιν των ανωτέρω, αν θέλετε να μάθετε ακόμη περισσότερα σχετικά με την συνεισφορά, μπορείτε πάντα να ανατρέχετε στην ενότητα του εγχειρίδίου του Django σχετικά με την συνεισφορά. Περιέχει τόνους πληροφορίας και θα πρέπει να είναι η πρώτη πηγή που θα κοιτάξετε για τυχόν ερωτήσεις ή απορίες που μπορεί να προκύψουν.
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\neasy tickets that have branches which need improvement. If you’re familiar\nwith writing tests, you can also look at the list of\neasy 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