Εισαγωγή¶

Ενδιαφέρεστε να συνεισφέρετε στην κοινότητα; Ίσως έχετε βρει κάποιο σφάλμα προγράμματος (bug) στο Django και θέλετε να διορθωθεί ή θέλετε να προσθέσετε κάποια επιπλέον λειτουργία ή χαρακτηριστικό.

Contributing back to Django itself is the best way to see your own concerns addressed. This may seem daunting at first, but it’s a well-traveled path with documentation, tooling, and a community to support you. We’ll walk you through the entire process, so you can learn by example.

Κώδικας δεοντολογίας¶

Ως συνεισφέρων, μπορείτε να μας βοηθήσετε να διατηρήσουμε την Django κοινότητα ανοιχτή (open) και περιεκτική (inclusive). Παρακαλούμε διαβάστε και ακολουθήστε το δικό μας Κώδικα Δεοντολογίας.

Εγκατάσταση Git¶

For this tutorial, you’ll need Git installed to download the current development version of Django and to generate a branch for the changes you make.

Για να ελέγξετε αν έχετε εγκατεστημένο το Git, γράψτε στη κονσόλα (ή στη γραμμή εντολών αν έχετε Windows) τη λέξη git. Αν βλέπετε μηνύματα που λένε ότι αυτή η εντολή δεν υπάρχει, θα χρειαστεί να κατεβάσετε το Git και να το εγκαταστήσετε. Δείτε πως, στην επίσημη σελίδα του Git.

Αν δεν είστε εξοικειωμένοι με το Git, μπορείτε να μάθετε περισσότερα σχετικά με τις εντολές του (αφού εγκατασταθεί) πληκτρολογώντας git help στην κονσόλα (ή στη γραμμή εντολών για χρήστες Windows).

Δημιουργία αντίγραφου της αναπτυξιακής έκδοσης του Django¶

Το πρώτο βήμα για την συνεισφορά στο Django είναι να αποκτήσετε ένα αντίγραφο του πηγαίου κώδικα. Πρώτα, κάντε fork το Django από το GitHub. Από την γραμμή εντολών, χρησιμοποιείστε την εντολή cd για να μεταβείτε στον φάκελο στον οποίο θέλετε να αποθηκεύσετε τον πηγαίο κώδικα του Django. Αν δεν υπάρχει κάποιος φάκελος της αρεσκείας σας, τότε χρησιμοποιήστε την εντολή mkdir για να τον δημιουργήσετε και μετά την εντολή cd επιθυμητός_φάκελος για να αποθηκεύσετε εκεί τον πηγαίο κώδικα.

Κατεβάστε το αποθετήριο (εφεξής repository ή repo) του πηγαίου κώδικα του Django χρησιμοποιώντας την ακόλουθη εντολή:

$ git clone https://github.com/YourGitHubName/django.git

...\> git clone https://github.com/YourGitHubName/django.git

Τώρα που έχετε ένα τοπικό αντίγραφο του Django, μπορείτε να το εγκαταστήσετε με το pip, όπως θα εγκαθιστούσατε οποιοδήποτε άλλο πακέτο. ;Ένας καλός τρόπος είναι η δημιουργία virtual environment (απομονωμένο περιβάλλον εργασίας), που θα σας επιτρέψει να έχετε ένα χωριστό φάκελο με τα απαραίτητα πακέτα για κάθε πρότζεκτ σας.

It’s a good idea to keep all your virtual environments in one place, for example in .virtualenvs/ in your home directory.

Create a new virtual environment by running:

$ python3 -m venv ~/.virtualenvs/djangodev

...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev

Η διαδρομή (path) που εισαγάγατε αποτελεί και το καινούργιο virtualenv το οποίο θα αποθηκευτεί στον υπολογιστή σας.

The final step in setting up your virtual environment is to activate it:

$ source ~/.virtualenvs/djangodev/bin/activate

Αν η εντολή source δεν είναι διαθέσιμη, χρησιμοποιήστε την τελεία, όπως:

$ . ~/.virtualenvs/djangodev/bin/activate

You have to activate the virtual environment whenever you open a new terminal window.

...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

The name of the currently activated virtual environment is displayed on the command line to help you keep track of which one you are using. Anything you install through pip while this name is displayed will be installed in that virtual environment, isolated from other environments and system-wide packages.

Go ahead and install the previously cloned copy of Django:

$ python -m pip install -e /path/to/your/local/clone/django/

...\> py -m pip install -e \path\to\your\local\clone\django\

The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when writing your first contribution.

Εκτέλεση της σουίτας δοκιμών του Django για πρώτη φορά¶

When contributing to Django it’s very important that your code changes don’t introduce bugs into other areas of Django. One way to check that Django still works after you make your changes is by running Django’s test suite. If all the tests still pass, then you can be reasonably sure that your changes work and haven’t broken other parts of Django. If you’ve never run Django’s test suite before, it’s a good idea to run it once beforehand to get familiar with its output.

Before running the test suite, enter the Django tests/ directory using the cd tests command, and install test dependencies by running:

$ python -m pip install -r requirements/py3.txt

...\> py -m pip install -r requirements\py3.txt

If you encounter an error during the installation, your system might be missing a dependency for one or more of the Python packages. Consult the failing package’s documentation or search the web with the error message that you encounter.

Now we are ready to run the test suite. If you’re using GNU/Linux, macOS, or some other flavor of Unix, run:

$ ./runtests.py

...\> runtests.py 

Now sit back and relax. Django’s entire test suite has thousands of tests, and it takes at least a few minutes to run, depending on the speed of your computer.

While Django’s test suite is running, you’ll see a stream of characters representing the status of each test as it completes. E indicates that an error was raised during a test, and F indicates that a test’s assertions failed. Both of these are considered to be test failures. Meanwhile, x and s indicated expected failures and skipped tests, respectively. Dots indicate passing tests.

Τα παραλειπόμενα τεστ (τεστ που δεν έγιναν) προκύπτουν συνήθως λόγω έλλειψης κάποιων εξωτερικών βιβλιοθηκών (external libraries) οι οποίες χρειάζονται για να τρέξει το τεστ. Δείτε στο Τρέχοντας όλα τα τεστ για μια λίστα με όλα τα dependencies (εξαρτώμενα πακέτα – εξωτερικές βιβλιοθήκες). Επίσης σιγουρευτείτε ότι έχετε εγκαταστήσει τα απαραίτητα πακέτα (στα οποία εξαρτώνται τα τεστ) προτού τρέξετε κάποιο τεστ (δεν θα χρειαστούμε κάποιο από αυτά σε αυτόν τον οδηγό). Μερικά τεστ είναι γραμμένα και συνδέονται με μια συγκεκριμένη βάση δεδομένων και δεν θα τρέξουν αν δεν υπάρχει εγκατεστημένη η αντίστοιχη βάση δεδομένων καθώς και το πακέτο (βιβλιοθήκη) που συνδέει την database με το Django (π.χ για την PostgreSQL το πακέτο είναι το psycopg2). Η SQLite είναι η βάση δεδομένων που χρησιμοποιεί το Django ως προεπιλογή. Μπορείτε επίσης να τρέξετε τα τεστ χρησιμοποιώντας μια διαφορετική βάση δεδομένων.

Όταν ολοκληρωθούν τα τεστ, θα σας εμφανιστεί κάποιο μήνυμα που θα σας ενημερώνει για την επιτυχή ή όχι εκτέλεση τους. Εφόσον δεν έχετε κάνει κάποια αλλαγή μέχρι τώρα στον πηγαίο κώδικα του Django, όλα τα τεστ θα πρέπει να έχουν επιτυχή έκβαση. Αν δείτε τυχόν σφάλματα ή αποτυχίες κάποιων τεστ, σιγουρευτείτε ότι έχετε ακολουθήσει κατάλληλα τα ανωτέρω βήματα. Δείτε στο τρέχοντας τα unit τεστ για περισσότερες πληροφορίες. Αν χρησιμοποιείτε την Python 3.5+, θα υπάρξουν κάποιες αποτυχίες μερικών τεστ οι οποίες οφείλονται σε προειδοποιήσεις υποβάθμισης (deprecation warnings) στις οποίες μπορείτε να μην δώσετε σημασία. Αυτές οι αποτυχίες έχουν αποκατασταθεί στην τρέχουσα έκδοση του Django. Σας υπενθυμίζουμε ότι σε αυτόν τον οδηγό χρησιμοποιούμε μια παλιά έκδοση του Django.

Note that the latest Django «main» branch may not always be stable. When developing against «main», you can check Django’s continuous integration builds to determine if the failures are specific to your machine or if they are also present in Django’s official builds. If you click to view a particular build, you can view the «Configuration Matrix» which shows failures broken down by Python version and database backend.

Working on a feature¶

For this tutorial, we’ll work on a «fake ticket» as a case study. Here are the imaginary details:

We’ll now implement this feature and associated tests.

Creating a branch¶

Πριν κάνετε αλλαγές, δημιουργήστε ένα νέο τμήμα για το εισητήριο

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

You can choose any name that you want for the branch, «ticket_99999» is an example. All changes made in this branch will be specific to the ticket and won’t affect the main copy of the code that we cloned earlier.

Γράφοντας μερικά τεστ για το ticket¶

In most cases, for a contribution to be accepted into Django it has to include tests. For bug fix contributions, this means writing a regression test to ensure that the bug is never reintroduced into Django later on. A regression test should be written in such a way that it will fail while the bug still exists and pass once the bug has been fixed. For contributions containing new features, you’ll need to include tests which ensure that the new features are working correctly. They too should fail when the new feature is not present, and then pass once it has been implemented.

A good way to do this is to write your new tests first, before making any changes to the code. This style of development is called test-driven development and can be applied to both entire projects and single changes. After writing your tests, you then run them to make sure that they do indeed fail (since you haven’t fixed that bug or added that feature yet). If your new tests don’t fail, you’ll need to fix them so that they do. After all, a regression test that passes regardless of whether a bug is present is not very helpful at preventing that bug from reoccurring down the road.

Ας εργαστούμε λοιπόν στο παράδειγμα μας.

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), "toast")

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

ImportError: cannot import name 'make_toast' from 'django.shortcuts'

Γράφοντας κώδικα για το ticket¶

Next we’ll be adding the make_toast() function.

Navigate to the django/ folder and open the shortcuts.py file. At the bottom, add:

def make_toast():
    return "toast"

Now we need to make sure that the test we wrote earlier passes, so we can see whether the code we added is working correctly. Again, navigate to the Django tests/ directory and run:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Everything should pass. If it doesn’t, make sure you correctly added the function to the correct file.

Εκτέλεση της σουίτας δοκιμών του Django για δεύτερη φορά¶

Once you’ve verified that your changes and 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.

Για να τρέξετε ολόκληρη τη σουίτα δοκιμών του Django, πληκτρολογήστε cd tests/ και τρέξτε:

$ ./runtests.py

...\> runtests.py 

Γράφοντας το εγχειρίδιο (documentation)¶

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'``.

Για περισσότερες πληροφορίες σχετικά με οδηγίες σύνταξης του εγχειριδίου (περιέχει και την εξήγηση του versionadded), δείτε στο γράφοντας το εγχειρίδιο. Αυτή η σελίδα εξηγεί και το πως να δημιουργήσετε ένα αντίγραφο του εγχειριδίου σας τοπικά (στον υπολογιστή σας), ούτως ώστε να δείτε πως θα φαίνεται online στο επίσημο site του Django.

Προβολή των αλλαγών σας¶

Now it’s time to review the changes made in the branch. To stage all the changes ready for commit, run:

$ git add --all

...\> git add --all

Then display the differences between your current copy of Django (with your changes) and the revision that you initially checked out earlier in the tutorial with:

$ git diff --cached

...\> git diff --cached

Χρησιμοποιήστε τα βέλη για να κινηθείτε προς τα επάνω και προς τα κάτω.

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')

When you’re done previewing the changes, hit the q key to return to the command line. If the diff looked okay, it’s time to commit the changes.

Committing the changes¶

Για να κάνετε commit τις αλλαγές γράψτε:

$ git commit

...\> git commit

Η παραπάνω εντολή ανοίγει έναν επεξεργαστή κειμένου για να γράψετε το μήνυμα του commit. Ακολουθήστε τις οδηγίες για ένα σωστό μήνυμα commit και γράψτε ένα μήνυμα όπως:

Fixed #99999 -- Added a shortcut function to make toast.

Κάνοντας push το commit καθώς και ένα pull request¶

After committing the changes, send it to your fork on GitHub (substitute «ticket_99999» with the name of your branch if it’s different):

$ git push origin ticket_99999

...\> git push origin ticket_99999

Μπορείτε να δημιουργήσετε ένα pull request πηγαίνοντας στην επίσημη σελίδα του Django στο GitHub. Εκεί θα δείτε το δικό σας branch κάτω από την ετικέτα «Your recently pushed branches». Κάντε κλικ στο «Compare & pull request».

Please don’t do it for this tutorial, but on the next page that displays a preview of the changes, you would click «Create pull request».

Επόμενα βήματα¶

Συγχαρητήρια! Μόλις μάθατε πως να κάνετε pull requests στο Django! Λεπτομέρειες για περισσότερο ανεπτυγμένες τεχνικές, που ίσως χρειαστείτε, θα βρείτε στο Working with Git and GitHub.

Τώρα μπορείτε να χρησιμοποιήσετε αυτές τις τεχνικές για καλό σκοπό βελτιώνοντας τον πηγαίο κώδικα του Django.