Writing your first contribution for Django

Wprowadzenie

Jesteś zainteresowany odwdzięczeniem się odrobinę społeczności? Może znalazłeś błąd w Django, który chciałbyś, by był rozwiązany, lub jest jakaś mała funkcjonalność, którą chciałbyś, by była dodana.

Pomoc w rozwoju Django jest najlepszym sposobem na rozwiązanie napotkanych przez Ciebie problemów. Na początku może to wydawać się zniechęcające, ale jest to przyjemna droga z dokumentacją, narzędziami i wsparciem społeczności. Przeprowadzimy Cię przez cały proces na przykładzie, abyś mógł się nauczyć tego w praktyce.

Dla kogo jest ten tutorial?

Zobacz także

Jeśli szukasz informacji o szczegółach wprowadzania zmian w kodzie, obejrzyj dokumentację Contributing code.

For this tutorial, we expect that you have at least a basic understanding of how Django works. This means you should be comfortable going through the existing tutorials on writing your first Django app. In addition, you should have a good understanding of Python itself. But if you don’t, Dive Into Python is a fantastic (and free) online book for beginning Python programmers.

Ci z was, którzy nie są zaznajomieni z systemami kontroli wersji i Trakiem przekonają się, że w tym poradniku i jego odnośnikach znajdą wystarczająco informacji, aby zacząć pracę. Pomimo tego, prawdopodobnie będziecie potrzebować przeczytać nieco więcej o tych różnych narzędziach, jeśli planujecie regularnie współtworzyć Django.

Celem tego poradnika w głównej mierze jest wytłumaczenie wszystkiego najdokładniej jak to możliwe, aby mógł być on używany przez szerokie grono odbiorców.

Gdzie szukać pomocy:

Jeśli masz problemy z przejściem tego samouczka, prosimy napisz wiadomość na Forum Django, django-developers lub wpadnij na #django-dev na irc.libera.chat, aby czatować z innymi użytkownikami Django, którzy mogą być w stanie udzielić ci pomocy.

Co zawiera ten przewodnik?

We’ll be walking you through contributing to Django for the first time. By the end of this tutorial, you should have a basic understanding of both the tools and the processes involved. Specifically, we’ll be covering the following:

• Instalacja Gita.

• Pobieranie kopii wersji rozwojowej Django

• Uruchamianie zestawu testów Django.

• Writing a test for your changes.

• Writing the code for your changes.

• Testing your changes.

• Wysyłanie prośby o pull.

• Gdzie szukać więcej informacji.

Kiedy tutorial jest już za tobą, możesz przejrzeć resztę Django’s documentation on contributing. Zawiera ona wiele dobrych informacji i jest lekturą obowiązkową dla każdego, kto chciałby zostać stałym współtwórcą Django. Jeśli masz pytania, tam prawdopodobnie są odpowiedzi.

Wymagany Python 3!

Bieżąca wersja Django nie wspiera Pythona 2.7. Pobierz Pythona 3 ze strony pobrań Pythona lub za pomocą menadżera pakietów swojego systemu operacyjnego.

Dla użytkowników Windows

W dokumentacji Instalacja Pythona w systemie Windows znajdziesz dodatkowe wskazówki.

Kodeks postępowania

Jako współtwórca możesz pomóc nam utrzymać społeczność Django otwartą i zintegrowaną. Przeczytaj i postępuj zgodnie z naszym Kodeksem Postępowania.

Instalacja Gita

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.

Aby sprawdzić, czy posiadasz zainstalowanego Gita, wpisz git w wiersz poleceń. Jeśli otrzymasz informację, że taka komenda nie została znaleziona, będziesz musiał go pobrać i zainstalować. Zobacz stronę pobierania Gita.

Jeśli nie jesteś zaznajomiony z Gitem, możesz zawsze znaleźć więcej informacji na temat komend (kiedy Git jest zainstalowany) wpisując git help w wiersz poleceń.

Pobranie kopii wersji rozwojowej Django

Pierwszym krokiem do współtworzenia Django jest uzyskanie kopii kodu źródłowego. Najpierw rozwidlij Django na GitHubie. Następnie użyj polecenia cd w linii poleceń, aby przejść do katalogu, gdzie będziesz chciał trzymać swoją lokalną kopię Django.

Pobierz repozytorium kodu źródłowego Django używając poniższego polecenia:

Linux/macOS

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

Windows

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

Połączenie o niskiej przepustowości?

Możesz dodać argument --depth 1 do git clone, aby ominąć pobieranie całej historii commitów Django, co zmniejsza transfer danych z ~250 MB do ~70 MB.

Kiedy już masz lokalną kopię Django, możesz go zainstalować tak jak zainstalowałbyś dowolny pakiet za pomocą pipa. Najwygodniejszym sposobem, aby to zrobić, jest użycie środowiska wirtualnego, które jest funkcjonalnością wbudowaną w Pythona, która pozwala ci trzymać oddzielny katalog zainstalowanych pakietów dla każdego z twoich projektów, aby nie wchodziły ze sobą w konflikt.

Dobrą praktyką jest przechowywanie wszystkich swoich wirtualnych środowisk w jednym miejscu, na przykład w .virtualenvs/ w Twoim katalogu domowym.

Stwórz nowe środowisko wirtualne uruchamiając:

Linux/macOS

$ python3 -m venv ~/.virtualenvs/djangodev

Windows

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

Ścieżką jest miejsce gdzie nowe środowisko zostanie zapisane na Twoim komputerze:

Ostatnim krokiem w procesie konfigurowania twojego środowiska wirtualnego jest jego aktywacja:

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

Jeśli komenda source nie jest dostępna, możesz spróbować zamiast niej użyć kropki:

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

Musisz aktywować swoje środowisko wirtualne zawsze, kiedy otwierasz nowe okno terminala.

Dla użytkowników Windows

Aby aktywować swoje środowisko wirtualne w systemie Windows, uruchom:

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

Nazwa obecnie aktywnego środowiska wirtualnego jest wyświetlana w linii komend, aby pomóc śledzić, którego środowiska używasz. Cokolwiek, co zainstalujesz pipem, gdy ta nazwa się wyświetla, zostanie zainstalowane w tym wirtualnym środowisku, wyizolowane od innych środowisk i pakietów systemowych.

Śmiało, zainstaluj wcześniej sklonowaną kopię Django:

Linux/macOS

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

Windows

...\> 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.

Tworzenie projektów z lokalną kopią 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 contribution, especially if testing any changes to the UI.

W tutorialu znajdziesz pomoc w tworzeniu projektu Django.

Uruchomienie zestawu testów Django po raz pierwszy

Dając wkład w kod Django, bardzo ważne jest, aby twoje zmiany nie wprowadzały błędów w innych obszarach Django. Jednym ze sposobów, aby sprawdzić, czy Django nadal działa po twoich zmianach jest uruchomienie zestawu testów Django. Jeśli wszystkie testy nadal przechodzą, wtedy masz podstawy, by sądzić, że twoje zmiany działają i nie popsuły innych części Django. Jeśli nigdy wcześniej nie uruchamiałeś zestawu testów Django, dobrym pomysłem jest uprzednio uruchomienie ich raz po to, abyś zaznajomił się z ich efektem.

Przed uruchomieniem zestawu testów, wejdź do katalogu tests/ Django używając komendy cd tests i zainstaluj zależności dla testów uruchamiając:

Linux/macOS

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

Windows

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

Jeśli napotkasz błąd w trakcie instalacji, może to oznaczać, że w twoim systemie brakuje zależności dla jednego lub więcej pythonowych pakietów. Sprawdź dokumentację pakietów, które zgłaszają błąd lub przeszukaj sieć z komunikatem błędu, który napotkałeś.

Now we are ready to run the test suite:

Linux/macOS

$ ./runtests.py

Windows

...\> runtests.py 

Teraz usiądź i odpręż się. Cały zestaw testów Django ma ich tysiące a ich wykonanie może zająć co najmniej kilka minut, w zależności od szybkości twojego komputera.

Kiedy uruchomisz zestaw testów Django, zobaczysz strumień znaków oznaczających status każdego testu po jego zakończeniu. E oznacza, że został zgłoszony błąd podczas testu, F oznacza, że asercje testu nie zostały spełnione. Obie z nich są traktowane jako porażki testów. Jednocześnie x i s oznaczają kolejno spodziewane porażki i ominięte testy. Kropki oznaczają pomyślne przechodzenie testu.

Testy omijane są zazwyczaj z powodu brakujących zewnętrznych bibliotek wymaganych do uruchomienia testu; zobacz Running all the tests, aby obejrzeć listę zależności i upewnij się, że zainstalowałeś te, które są związane ze zmianami, które wprowadzasz (nie będziemy potrzebować żadnej w tym tutorialu). Niektóre testy są właściwe dla wybranego back-endu bazodanowego i zostaną ominięte, jeśli test nie odbywa się z tym back-endem. Aby uruchomić testy z użyciem innego back-endu, sprawdź Using another settings module.

Kiedy testy się skończą, powinieneś zobaczyć komunikat informujący, czy zestaw testów udał się czy odniósł porażkę. Nie zrobiłeś żadnych zmian w kodzie Django, więc cały zestaw testów powinien się udać. Jeśli otrzymujesz porażki lub błędy upewnij się, że poprzednie kroki wykonałeś odpowiednio. Zobacz więcej informacji w Running the unit tests.

Zwróć uwagę, że najnowsza wersja brancha „main” Django może nie zawsze być stabilna. Kiedy dewelopujesz z użyciem „maina”, możesz sprawdzić Django’s continous integration builds, aby zweryfikować czy porażki są specyficzne dla twojej maszyny czy są również obecne w oficjalnych buildach Django. Jeśli klikniesz, aby zobaczyć poszczególny build, możesz zobaczyć „Configuration Matrix”, która pokazuje porażki uzyskane w poszczególnych wersjach Pythona i bazodanowego backendu.

Informacja

Na potrzeby tego tutorialu i zgłoszenia, nad którym pracujemy, testowanie z użyciem SQLite wystarczy, chociaż jest możliwe (i czasem niezbędne), aby uruchomić testy używając innej bazy danych. Przy zmianach interfejsu, przyda ci się uruchomienie testów Selenium.

Praca nad funkcjonalnością

Na potrzeby tego tutoriala będziemy pracowali nad „sztucznym zgłoszeniem” jako studium przypadku. Tutaj są fikcyjne szczegóły:

Zgłoszenie #99999 – Umożliwić tworzenie toastów

Django powinno zawierać funkcję django.shortcuts.make_toast(), która zwraca 'toast'.

Teraz zaimplementujemy tę funkcjonalność i związane z nią testy.

Creating a branch

Przed wprowadzeniem jakichkolwiek zmian, stwórz nowy branch dla zgłoszenia:

Linux/macOS

$ git checkout -b ticket_99999

Windows

...\> git checkout -b ticket_99999

Możesz wybrać dowolną nazwę dla brancha, na przykład „ticket_99999”. Wszystkie zmiany zrobione w tym branchu będą specyficzne dla zgłoszenia i nie wpłyną na główną kopię kodu, którą wcześniej sklonowaliśmy.

Pisanie testów do twojego zgłoszenia

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.

Pora na nasz praktyczny przykład.

Pisanie testu do zgłoszenia #99999

Aby rozwiązać to zgłoszenie, dodamy funkcję make_toast() do modułu django.shortcuts. Najpierw dodamy test, który próbuje użyć funkcji i sprawdza, że jej wynik wygląda poprawnie.

Przejdź do folderu tests/shortcuts Django i stwórz nowy plik test_make_toast.py. Dodaj następujący kod:

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


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

Ten test sprawdza, że make_toast() zwraca 'toast'.

Ale to całe testowanie wygląda na dość ciężkie…

Jeśli nie miałeś nigdy wcześniej do czynienia z testami, mogą wyglądać na trochę trudne do pisania na pierwszy rzut oka. Na szczęście testowanie jest bardzo dużym tematem w programowaniu komputerów, więc można znaleźć na jego temat wiele informacji:

• Dobry artykuł na początek o pisaniu testów do Django można znaleźć w dokumentacji: Writing and running tests.

• Dive Into Python (darmowa książka online dla początkujących Python-deweloperów) zawiera świetny wstęp do testów jednostkowych.

• Po ich przeczytaniu, jeśli chcesz zanurzyć zęby w czymś bardziej mięsistym, jest zawsze dokumentacja unittest Pythona.

Uruchomienie twojego nowego testu

Jako że nie wprowadziliśmy jeszcze żadnych zmian do django.shortcuts, nasz test powinien się nie powieźć. Uruchommy wszystkie testy w folderze shortcuts, aby upewnić się, że tak naprawdę się dzieje. cd-uj do katalogu tests/ Django i uruchom:

Linux/macOS

$ ./runtests.py shortcuts

Windows

...\> runtests.py shortcuts

Jeśli testy uruchomiły się poprawnie, powinieneś zobaczyć jedną porażkę odpowiadającą metodzie testowej, którą dodaliśmy, z tym błędem:

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

Jeśli wszystkie testy przeszły, wtedy musisz upewnić się, że dodałeś nowy test pokazany powyżej do odpowiedniego folderu i pliku o odpowiedniej nazwie.

Pisanie kodu do twojego zgłoszenia

Następnie dodamy funkcję make_toast().

Przejdź do folderu django/ i otwórz plik shortcuts.py. Na jego końcu dodaj:

def make_toast():
    return "toast"

Teraz powinniśmy się upewnić, że test, który napisaliśmy wcześniej, przechodzi, abyśmy zobaczyli, czy kod, który dodaliśmy, działa poprawnie. Znów przejdź do katalogu tests/ Django i uruchom:

Linux/macOS

$ ./runtests.py shortcuts

Windows

...\> runtests.py shortcuts

Wszystko powinno przejść. Jeśli nie przeszło, upewnij się, że poprawnie dodałeś funkcję do odpowiedniego pliku.

Uruchamianie zestawu testów Django drugi raz

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.

Aby uruchomić zestaw testów Django w całości, wejdź cd w katalog tests/ Django i uruchom:

Linux/macOS

$ ./runtests.py

Windows

...\> runtests.py 

Pisanie dokumentacji

To nowa funkcjonalność, więc powinna zostać udokumentowana. Otwórz plik docs/topics/http/shortcuts.txt i dodaj co następuje na końcu tego pliku:

``make_toast()``
================

.. function:: make_toast()

.. versionadded:: 2.2

Returns ``'toast'``.

Jako że ta nowa funkcjonalność będzie w nadchodzącym wydaniu, dodamy ją również do informacji na temat wydania dla następnej wersji Django. Otwórz informacje o wydaniu dla ostatniej wersji w docs/releases/, która w momencie pisania to 2.2.txt. Dodaj notatkę pod nagłówkiem „Minor Features”:

:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~

* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

Po więcej informacji na temat pisania dokumentacji, wliczając wyjaśnienie o co chodzi w cząstce versionadded, odsyłamy do Writing documentation. Ta strona zawiera również wyjaśnienie jak zbudować lokalnie kopię dokumentacji, aby móc obejrzeć HTML, który zostanie później wygenerowany.

Podgląd twoich zmian

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

Linux/macOS

$ git add --all

Windows

...\> git add --all

Następnie wyświetl różnice między twoją bieżącą kopią Djang (z twoimi zmianami) i rewizją, którą pierwotnie zcheck-outowałeś wcześniej w tym tutorialu, używając:

Linux/macOS

$ git diff --cached

Windows

...\> git diff --cached

Użyj klawiszy strzałek, aby przesuwać się do góry i w dół.

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

Aby scommitować zmiany:

Linux/macOS

$ git commit

Windows

...\> git commit

Powoduje to otwarcie edytora tekstu do wpisania „commit message”. Zrealizuj zalecenia commit message’y i napisz notatkę w ten sposób:

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

Pushowanie commita i tworzenie pull requesta

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

Linux/macOS

$ git push origin ticket_99999

Windows

...\> git push origin ticket_99999

Możesz stworzyć pull request odwiedzając stronę Django na GitHubie. Zobaczysz swój branch pod „Your recently pushed branches”. Kliknij „Compare & pull request” obok niego.

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”.

Następne kroki

Gratulacje, nauczyłeś się tworzyć pull requesty do Django! Szczegóły bardziej zaawansowanych technik, których możesz potrzebować są w Working with Git and GitHub.

Teraz możesz dobrze wykorzystać te umiejętności pomagając ulepszać bazowy kod Django.

Więcej informacji dla nowych kontrybutorów

Before you get too into contributing to Django, there’s a little more information on contributing that you should probably take a look at:

• You should make sure to read Django’s documentation on claiming tickets and submitting pull requests. It covers Trac etiquette, how to claim tickets for yourself, expected coding style (both for code and docs), and many other important details.

• Ci, którzy mają styczność pierwszy raz z wnoszeniem wkładu do kodu, powinni przeczytać też dokumentację Django dla nowych kontrybutorów. Zawiera wiele dobrych rad dla tych, którzy są nowi w pomaganiu w Django.

• Dalej, jeśli wciąż jesteś głodny informacji o współtworzeniu, zawsze możesz przejrzeć resztę dokumentacji Django na temat współtorzenia. Zawiera tonę przydatnych informacji i powinna być twoim pierwszym źródłem, odpowiadającym na każde pytanie, które możesz mieć.

Znajdowanie twojego pierwszego prawdziwego zgłoszenia

Once you’ve looked through some of that information, you’ll be ready to go out and find a ticket of your own to contribute to. Pay special attention to tickets with the „easy pickings” criterion. These tickets are often much simpler in nature and are great for first time contributors. Once you’re familiar with contributing to Django, you can start working on more difficult and complicated tickets.

If you just want to get started already (and nobody would blame you!), try taking a look at the list of easy tickets without a branch and the easy tickets that have branches which need improvement. If you’re familiar with writing tests, you can also look at the list of easy tickets that need tests. Remember to follow the guidelines about claiming tickets that were mentioned in the link to Django’s documentation on claiming tickets and submitting branches.

Co dalej po stworzeniu pull requesta?

After a ticket has a branch, it needs to be reviewed by a second set of eyes. After submitting a pull request, update the ticket metadata by setting the flags on the ticket to say „has patch”, „doesn’t need tests”, etc, so others can find it for review. Contributing doesn’t necessarily always mean writing code from scratch. Reviewing open pull requests is also a very helpful contribution. See Triaging tickets for details.