Pisanie pierwszej poprawki do 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 tak naprawdę jest całkiem proste. 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 jak zgłaszać poprawki, obejrzyj dokumentację Submitting patches.

Na potrzeby tego tutorialu oczekujemy posiadanie co najmniej podstawowego rozumienia, jak działa Django. To znaczy, że czytelnik powinien być już obeznany z istniejącymi tutorialami na temat pisania jego pierwszej aplikacji Django. Dodatkowo, powinien dobrze rozumieć samego Pythona. W przypadku jeśli tak nie jest, Dive Into Python jest fantastyczną (i darmową) książką online dla początkujących programistów Pythona.

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ść do django-developers lub wpadnij na #django-dev na irc.freenode.net, aby czatować z innymi użytkownikami Django, którzy mogą być w stanie udzielić ci pomocy.

Co zawiera ten przewodnik?

Przeprowadzimy cię przez pierwsze tworzenie poprawki do Django. Pod koniec tego tutoriala, powinieneś(nnaś) rozumieć podstawy zarówno narzędzi jak i wykorzystanych procesów. W szczególności poruszymy następujące tematy:

  • Instalacja Gita.
  • Jak pobrać rozwojową wersję Django.
  • Uruchamianie zestawu testów Django.
  • Pisanie testu dla twojej poprawki.
  • Pisanie kodu dla twojej poprawki.
  • Testowanie twojej poprawki.
  • 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!

Ten tutorial zakłada, że używasz Pythona 3. Pobierz najnowszą wersję ze strony pobierania Pythona lub za pomocą menadżera pakietów twojego systemu operacyjnego.

Dla użytkowników Windows

Instalując Pythona na Windowsie upewnij się, że zaznaczyłeś opcję „Add python.exe to Path”, aby zawsze był dostępny z linii komend.

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 Git’a

Do tego poradnika będziesz potrzebował mieć zainstalowanego Gita, aby pobrać aktualną wersję rozwojową Django i wygenerować pliki poprawek dla zmian, które dokonasz.

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.

Dla użytkowników Windows

Podczas instalacji Gita na Windowsie, zalecane jest, abyś wybrał opcję „Git Bash”, dzięki której Git uruchamia się we własnej powłoce. Ten poradnik zakłada, że tak właśnie go zainstalowałeś.

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

Uzyskiwanie 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:

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

Kiedy już masz lokalną kopię Django, możesz go zainstalować tak jak zainstalowałbyś dowolny pakiet za pomocą pip-a. Najwygodniejszy sposób, aby to zrobić jest użyć virtual environment (inaczej virtualenv) 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 virtualenv w jednym miejscu, na przykład w .virtualenvs/ w Twoim katalogu domowym. Utwórz ten katalog jeśli jeszcze nie istnieje:

$ mkdir ~/.virtualenvs

Następnie utwórz nowe środowisko wirtualne uruchamiając:

$ python3 -m venv ~/.virtualenvs/djangodev

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

Dla użytkowników Windows

Używanie wbudowanego modułu venv nie zadziała jeśli używasz shella Git Bash na Windowsie od czasu, gdy skrypty aktywacyjne są stworzone jedynie dla shella systemowego (.bat) i PowerShell (.ps1). Zamiast tego użyj pakietu virtualenv

$ pip install virtualenv
$ virtualenv ~/.virtualenvs/djangodev

Dla użytkowników Ubuntu

Na niektórych wersjach Ubuntu powyższa komenda może nie zadziałać. W takim przypadku użyj w zamian pakietu virtualenv, upewniając się przed tym, że posiadasz pip3:

$ sudo apt-get install python3-pip
$ # Prefix the next command with sudo if it gives a permission denied error
$ pip3 install virtualenv
$ virtualenv --python=`which python3` ~/.virtualenvs/djangodev

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

Dla użytkowników Windows

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

$ source ~/virtualenvs/djangodev/Scripts/activate

Musisz aktywować swoje środowisko wirtualne zawsze, kiedy otwierasz nowe okno terminala. virtualenvwrapper jest przydatnym narzędziem ułatwiającym ten proces.

Wszystko, co zainstalujesz poprzez pip od teraz będzie instalowane w Twoim nowym środowisku wirtualnym, odizolowane od innych środowisk i pakietów w systemie. Ponadto nazwa aktualnie aktywowanego środowiska wirtualnego jest wyświetlana w wierszu poleceń, aby ułatwić Ci śledzenie, którego z nich używasz. Śmiało zainstaluj wcześniej sklonowaną kopię Django:

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

Zainstalowana wersja Django od teraz wskazuje na Twoją lokalną kopię. Dzięki temu natychmiastowo będziesz widział wszelkie zmiany, których dokonasz co jest bardzo przydatne podczas pisania Twojej pierwszej poprawki.

Powracanie do poprzedniej wersji Django

Na potrzeby tutoriala, użyjemy zgłoszenia #24788 jako studium przypadku, więc przewiniemy historię wersji Django w git’cie do momentu zanim dodana została poprawka tego zgłoszenia. To pozwoli nam przejść wszystkie kroki składające się na napisanie tej poprawki od podstaw, włączając uruchomienie pakietu testów Django.

Zwróć uwagę, że mimo iż będziemy używać starszej wersji trunka Django na potrzeby poniższego tutoriala, powinieneś zawsze używać bieżącej wersji deweloperskiej Django pracując nad poprawką do zgłoszenia!

Informacja

Poprawka do tego zgłoszenia została napisana przez Pawła Marczewskiego i została zastosowana w Django jako commit 4df7e8483b2679fc1cba3410f08960bac6f51115. Stąd użyjemy wersji Django bezpośrednio ją poprzedzającej, commit 4ccfc4439a7add24f8db4ef3960d02ef8ae09887.

Wejdź do głównego katalogu Django (to ten, który zawiera django, docs, tests, AUTHORS itd.). Następnie możesz zcheckoutować starszą wersję Django, którą będziemy używać w poniższym tutorialu:

$ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887

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 nie popsuły kompletnie Django. Jeśli nigdy wcześniej nie uruchamiałeś zestawu testów Django, dobrym pomysłem jest uprzednio uruchomienie ich raz, tylko po to, abyś zaznajomił się, jak powinien wyglądać ich efekt.

Przed uruchomieniem modułu testów zainstaluj jego zależności przed z``cd``owanie do katalogu tests/ Django a następnie uruchomienie:

$ 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ś.

Jesteśmy gotowi do uruchomienia zestawu testów. Jeśli używasz GNU/Linuksa, macOS-a lub innego rodzaju Uniksa, uruchom:

$ ./runtests.py

Teraz usiądź i odpręż się. Cały zestaw testów Django ma ich ponad 9600, więc ich wykonywanie może zająć coś pomiędzy 5 a 15 minutami, 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 w trakcie uruchomienia. 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 wymaganaych 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. Jeśli używasz Pythona 3.5+, zobaczysz kilka porażek związanych z ostrzeżeniami o dezaktualizacji, które możesz zignorować. Te błędy zostały już poprawione w Django.

Zwróć uwagę, że najnowsza wersja trunka Django może nie zawsze być stabilna. Kiedy dewelopujesz z użyciem trunka, 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.

Tworzenie brancha dla swojego patcha

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

$ git checkout -b ticket_24788

Możesz wybrać dowolną nazwę dla brancha, na przykład „ticket_24788”. 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

W większości przypadków, aby poprawka została wcielona do Django, musi zawierać testy. Dla poprawek błędów znaczy to napisanie testu regresyjnego, aby upewnić się, że bug nie zostanie wprowadzony z powrotem w przyszłości. Test regresyjny powinien zostać napisany w taki sposób, aby nie przechodził jeśli bug nadal istnieje i aby przechodził wtedy, kiedy bug zostanie naprawiony. Dla poprawek zawierających nowe funkcjonalności, musisz załączyć testy, które pozwolą się upewnić, że ta nowa funkcja działa poprawnie. One też powinny nie przechodzić kiedy nie ma nowej funkcji i przechodzić wtedy, kiedy zostanie ona zaimplementowana.

Dobrym sposobem na to jest napisanie twoich testów najpierw, przed jakimikolwiek zmianami w kodzie. Taki styl pracy jest nazywany test-driven development i może być zastosowany zarówno do całych projektów jak i pojedynczych poprawek. Po napisaniu testów możesz je uruchomić, aby upewnić się, że nie przechodzą (bo przecież nie naprawiłeś tego błędu lub nie dodałeś tej funkcjonalności). Jeśli twoje nowe testy przechodzą pomyślnie, musisz poprawić je, aby nie przechodziły. Koniec końców test regresyjny, który przechodzi pomyślnie niezależnie od obecności buga w kodzie, nie pomoże za bardzo w ochronie przed pojawieniem się go w przyszłości.

Pora na nasz praktyczny przykład.

Pisanie kilku testów do zgłoszenia #24788

Zgłoszenie #24788 jest propozycją dodania małej funkcjonalności: możliwości ustalenia atrybutu prefix na poziomie klasy dla klas From, aby:

[…] forms which ship with apps could effectively namespace themselves such
that N overlapping form fields could be POSTed at once and resolved to the
correct form.

Aby rozwiązać zgłoszenie, dodamy atrybut prefix do klasy BaseForm. Podczas tworzenia instancji tej klasy, podanie prefiksu do metody __init__() nadal będzie ustawiać ten prefiks na tworzonej instancji. Lecz nie podanie prefiksu (lub podanie None) spowoduje użycie prefiksu na poziomie klasy. Ale zanim wprowadzimy te zmiany, napiszemy kilka testów, aby zweryfikować, że nasze modyfikacje działają poprawnie i będą działać poprawnie w przyszłości.

Przejdź do folderu Django tests/forms_tests/tests/ i otwórz plik test_forms.py. Dodaj poniższy kod w linii 1674, tuż przed funkcją test_forms_with_null_boolean:

def test_class_prefix(self):
    # Prefix can be also specified at the class level.
    class Person(Form):
        first_name = CharField()
        prefix = 'foo'

    p = Person()
    self.assertEqual(p.prefix, 'foo')

    p = Person(prefix='bar')
    self.assertEqual(p.prefix, 'bar')

Ten nowy test sprawdza czy ustawienie prefiksu na poziomie klasy działa zgodnie z oczekiwaniami i czy przekazanie parametru prefix podczas tworzenia instancji też nadal działa.

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

Pamiętaj, że nie wprowadziliśmy jeszcze żadnych zmian do BaseForm, więc nasze testy się powiodą. Uruchommy wszystkie testy w katalogu forms_tests, aby upewnić się, że to rzeczywiście się dzieje. Z linii komend, wejdź cd do katalogu tests/ Django i odpal:

$ ./runtests.py forms_tests

Jeśli testy przebiegły poprawnie, powinieneś zobaczyć jeden błąd związany z metodą testującą, którą dodaliśmy. Jeśli wszystkie testy przeszły bez błędów, upewnij się, że dodałeś nowy test pokazany powyżej do odpowiedniego folderu i klasy.

Pisanie kodu do twojego zgłoszenia

Następnie będziemy dodawać do Django funkcjonalność opisaną w zgłoszeniu #24788.

Pisanie kodu do zgłoszenia #24788

Przejdź do folderu django/django/forms i otwórz plik forms.py. Znajdź klasę BaseForm (linia 72.) i dodaj atrybut klasy prefix tuż za atrybutem field_order:

class BaseForm(object):
    # This is the main implementation of all the Form logic. Note that this
    # class is different than Form. See the comments by the Form class for
    # more information. Any improvements to the form API should be made to
    # *this* class, not to the Form class.
    field_order = None
    prefix = None

Weryfikacja, czy twoje testy teraz przechodzą

Gdy już skończysz modyfikować Django, musimy się upewnić, że testy, które napisaliśmy wcześniej przechodzą, aby sprawdzić czy kod, który napisaliśmy powyżej działa poprawnie. Aby uruchomić testy w folderze forms_tests, wejdź cd w katalog tests/ Django i uruchom:

$ ./runtests.py forms_tests

Ups, całe szczęście że napisaliśmy te testy! Powinieneś widzieć dalej jedną porażkę z następującym wyjątkiem:

AssertionError: None != 'foo'

Zapomnieliśmy dodać wyrażenie warunkowe w metodzie __init__. Zmień self.prefix = prefix, które jest teraz w linii 87. pliku django/forms/forms.py, dodając wyrażenie warunkowe:

if prefix is not None:
    self.prefix = prefix

Uruchom ponownie testy, wszystko powinno przejść. Jeśli nie przejdzie, upewnij się, że poprawnie zmodyfikowałeś klasę BaseForm jak jest pokazane powyżej i skopiowałeś poprawnie nowy test.

Uruchamianie zestawu testów Django drugi raz

Kiedy zweryfikowałeś, że twoje poprawki i testy działają poprawnie, dobrym pomysłem jest uruchomić cały zestaw testów Django, aby zweryfikować tylko, czy twoja zmiana nie wprowadziła żadnych bugów w innych obszarach Django.

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

$ ./runtests.py

Jeśli nie widzisz żadnych błędów, śmiało możesz iść dalej.

Pisanie dokumentacji

To nowa funkcjonalność, więc powinna zostać udokumentowana. Dodaj następującą sekcję w linii 1068. (na końcu pliku) w pliku django/docs/ref/forms/api.txt:

The prefix can also be specified on the form class::

    >>> class PersonForm(forms.Form):
    ...     ...
    ...     prefix = 'person'

.. versionadded:: 1.9

    The ability to specify ``prefix`` on the form class was added.

Jako że ta nowa funkcjonalność będzie w nadchodzącym wydaniu, dodajemy ją też do informacji o wydaniu dla Django 1.9, w linii 164. w sekcji „Forms” w pliku docs/releases/1.9.txt:

* A form prefix can be specified inside a form class, not only when
  instantiating a form. See :ref:`form-prefix` for details.

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

Teraz przejrzyjmy wszystkie zmiany, które wprowadziliśmy przy naszej poprawce. Wyświetl różnice pomiędzy swoją kopią Django (z twoimi zmianami) a wersją, którą pierwotnie zcheckoutowałeś wcześniej w tym tutorialu:

$ git diff

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

diff --git a/django/forms/forms.py b/django/forms/forms.py
index 509709f..d1370de 100644
--- a/django/forms/forms.py
+++ b/django/forms/forms.py
@@ -75,6 +75,7 @@ class BaseForm(object):
     # information. Any improvements to the form API should be made to *this*
     # class, not to the Form class.
     field_order = None
+    prefix = None

     def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,
                  initial=None, error_class=ErrorList, label_suffix=None,
@@ -83,7 +84,8 @@ class BaseForm(object):
         self.data = data or {}
         self.files = files or {}
         self.auto_id = auto_id
-        self.prefix = prefix
+        if prefix is not None:
+            self.prefix = prefix
         self.initial = initial or {}
         self.error_class = error_class
         # Translators: This is the default suffix added to form field labels
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 3bc39cd..008170d 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -1065,3 +1065,13 @@ You can put several Django forms inside one ``<form>`` tag. To give each
     >>> print(father.as_ul())
     <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
     <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>
+
+The prefix can also be specified on the form class::
+
+    >>> class PersonForm(forms.Form):
+    ...     ...
+    ...     prefix = 'person'
+
+.. versionadded:: 1.9
+
+    The ability to specify ``prefix`` on the form class was added.
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 5b58f79..f9bb9de 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -161,6 +161,9 @@ Forms
   :attr:`~django.forms.Form.field_order` attribute, the ``field_order``
   constructor argument , or the :meth:`~django.forms.Form.order_fields` method.

+* A form prefix can be specified inside a form class, not only when
+  instantiating a form. See :ref:`form-prefix` for details.
+
 Generic Views
 ^^^^^^^^^^^^^

diff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py
index 690f205..e07fae2 100644
--- a/tests/forms_tests/tests/test_forms.py
+++ b/tests/forms_tests/tests/test_forms.py
@@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):
         self.assertEqual(p.cleaned_data['last_name'], 'Lennon')
         self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))

+    def test_class_prefix(self):
+        # Prefix can be also specified at the class level.
+        class Person(Form):
+            first_name = CharField()
+            prefix = 'foo'
+
+        p = Person()
+        self.assertEqual(p.prefix, 'foo')
+
+        p = Person(prefix='bar')
+        self.assertEqual(p.prefix, 'bar')
+
     def test_forms_with_null_boolean(self):
         # NullBooleanField is a bit of a special case because its presentation (widget)
         # is different than its data. This is handled transparently, though.

Kiedy skończysz oglądać patch, kliknij przycisk q, aby wyjść i wrócić do linii komend. Jeśli treść patcha wyglądała w porządku, czas na scommitowanie zmian.

Commitowanie zmian w patchu

Aby scommitować zmiany:

$ git commit -a

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

Fixed #24788 -- Allowed Forms to specify a prefix at the class level.

Pushowanie commita i tworzenie pull requesta

Po skomitowaniu patcha, wyślij go do swojego forka na GitHubie (zamień „ticket_24788” z nazwą swojego brancha, jeśli jest inna):

$ git push origin ticket_24788

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.

Prosimy nie rób tego z powodu tego tutoriala, ale na następnej stronie, która prezentuje podgląd zmian, kliknąłbyś „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

Zanim za bardzo wsiąkniesz w pisanie patchy Django, jest trochę więcej informacji o dawaniu wkładu, na które prawdopodobnie powinieneś spojrzeć:

  • Powinieneś się upewnić, że przeczytałeś dokumentację Django na temat tworzenia zgłoszeń i wysyłania patchy. Zawiera ona etykietę Traca, jak przypisywać sobie zgłoszenia, oczekiwany styl kodowania w patchach i wiele innych ważnych szczegółów.
  • 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

Kiedy już przejrzałeś trochę z tych informacji, będziesz gotowy iść i znaleźć zgłoszenie, do którego napiszesz patcha. Zwróć szczególną uwagę na zgłoszenia z kryterium „easy pickings”. Te zgłoszenia często są z natury dużo prostsze i są świetne dla pierwszorazowych kontrybutorów. Gdy już będziesz zaznajomiony z wnoszeniem wkładu w Django, możesz iść dalej i pisać patche do trudniejszych i bardziej skomplikowanych zgłoszeń.

Jeśli po prostu już chcesz zacząć (nikt nie będzie cię winił!), spróbuj rzucić okiem na listę łatwych zgłoszeń, które potrzebują patchy i łatwych zgłoszeń, które mają patche potrzebujące poprawy. Jeśli umiesz pisać testy, możesz też spojrzeć na listę łatwych zgłoszeń, które potrzebują testów. Pamiętaj tylko przestrzegać wskazówek dotyczących przypisywania zgłoszeń, o czym było wspomniane w odnośniku do dokumentacji Django na temat przypisywania zgłoszeń i wgrywaniu patchy.

Co dalej po stworzeniu pull requesta?

Po tym, jak ticket ma patcha, musi zostać przejrzany przez drugą parę oczu. Po wysłaniu pull requesta zaktualizuj metadane ticketu ustawiając na tickecie flagi, które mówią „has patch”, „doesn’t need tests” i tak dalej, aby inni mogli go znaleźć do przejrzenia. Wnoszenie wkładu niekoniecznie zawsze znaczy pisanie patcha od zera. Przeglądanie istniejących patchy jest również bardzo pomocnym wkładem. Zobacz Triaging tickets po szczegóły.

Back to Top