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).
\nPomoc 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.
\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.
\nCi 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.
\nCelem 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.
\n\nWe’ll be walking you through contributing to Django for the first time.\nBy the end of this tutorial, you should have a basic understanding of both the\ntools and the processes involved. Specifically, we’ll be covering the following:
\nInstalacja 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.
\n\n\nJako 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.
\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.
\nAby 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ń.
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:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nKiedy 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:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nŚcieżką jest miejsce gdzie nowe środowisko zostanie zapisane na Twoim komputerze:
\nOstatnim krokiem w procesie konfigurowania twojego środowiska wirtualnego jest jego aktywacja:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nJeśli komenda source nie jest dostępna, możesz spróbować zamiast niej użyć kropki:
$ . ~/.virtualenvs/djangodev/bin/activate\nMusisz aktywować swoje środowisko wirtualne zawsze, kiedy otwierasz nowe okno terminala.
\n\nNazwa 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:
\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 installing\nin editable mode. You will immediately see any changes you make to it, which is\nof great help when testing your first contribution.
\nDają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.
\nPrzed 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\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nJeś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ś.
\nNow we are ready to run the test suite:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nTeraz 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.
\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.
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.
\nKiedy 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.
\nZwróć 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.
\n\nFor this tutorial, we’ll work on a „fake accepted ticket” as a case study. Here\nare the imaginary details:
\n\nTeraz zaimplementujemy tę funkcjonalność i związane z nią testy.
\nPrzed wprowadzeniem jakichkolwiek zmian, stwórz nowy branch dla zgłoszenia:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nMoż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.
\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.
\nPora na nasz praktyczny przykład.
\nAby 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\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), "toast")\nTen test sprawdza, że make_toast() zwraca 'toast'.
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\nWindows
...\\> runtests.py shortcuts\nJeśli testy uruchomiły się poprawnie, powinieneś zobaczyć jedną porażkę odpowiadającą metodzie testowej, którą dodaliśmy, z tym błędem:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nJeś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.
\nNastępnie dodamy funkcję make_toast().
Przejdź do folderu django/ i otwórz plik shortcuts.py. Na jego końcu dodaj:
def make_toast():\n return "toast"\nTeraz 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\nWindows
...\\> runtests.py shortcuts\nWszystko powinno przejść. Jeśli nie przeszło, upewnij się, że poprawnie dodałeś funkcję do odpowiedniego pliku.
\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.
\nAby uruchomić zestaw testów Django w całości, wejdź cd w katalog tests/ Django i uruchom:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nTo 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()``\n================\n\n.. function:: make_toast()\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nJako ż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`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nPo 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.
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\nNastę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:
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nUżyj klawiszy strzałek, aby przesuwać się do góry i w dół.
\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/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\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:: 2.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.
Aby scommitować zmiany:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nPowoduje to otwarcie edytora tekstu do wpisania „commit message”. Zrealizuj zalecenia commit message’y i napisz notatkę w ten sposób:
\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\nMoż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.
\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”.
\nGratulacje, 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.
\nTeraz możesz dobrze wykorzystać te umiejętności pomagając ulepszać bazowy kod 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.
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ć.
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