Writing your first contribution for Django

Kata Pengantar

Tertarik membalas kepada komunitas kecil? Mungkin Anda menemukan bug di Django yang ingin Anda perbaiki, atau mungkin ada fitur kecil yang ingin Anda tambahkan.

Membantu kembali ke Django adalah cara terbaik untuk melihat alamat perhatian anda. ini mungkin terlihat menakutkan awalnya, tetapi itu adalah jalur bepergian-dengan-baik dengan dokumentasi, peralatan, dan komunitas untuk mendukung anda. Kami akan berjalan melalui proses keseluruhan, sehingga anda dapat belajar berdasarkan contoh.

Untuk siapa saja tutorial ini?

Lihat juga

Jika anda mencari acuan pada rincian dari membuat bantuan kode, lihat dokumentasi 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.

Bagi anda yang tidak akrab dengan vesi kendali sistem dan Trac akan menemukan bahwa tutorial ini dan tautannya memasukkan informasi cukup untuk memulai. Bagaimanapun, anda akan mungkin membaca beberapa lebih alat berbeda jika anda berencana sering untuk membantu Django.

Untuk sebagian besar, tutorial ini mencoba menjelaskan sebanyak mungkin, sehingga itu dapat digunakan pada pendengar luas.

Dimana mendapatkan bantuan:

If you're having trouble going through this tutorial, please post a message on the Django Forum, django-developers, or drop by #django-dev on irc.libera.chat to chat with other Django users who might be able to help.

Tutorial ini meliputi apa?

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:

  • Memasang Git

  • Mengunduh salinan versi pengembangan Django.

  • Menjalankan rangkaian percobaan Django.

  • Writing a test for your changes.

  • Writing the code for your changes.

  • Testing your changes.

  • Mengajukan pull request

  • Dimana mencari untuk informasi lebih.

Sekali anda selesai dengan tutorial, anda dapat mencari sisa dari Django's documentation on contributing. Itu mengandung banyak informasi hebat dan harus dibaca untuk siapapun yang suka menjadi penyumbang rutin ke Django. Jika anda mendapatkan pertanyaan, itu mungkin mendapatkan jawaban.

Python 3 wajib!

Versi Django ini tidak mendukung Python 2.7. Dapatkan Python 3 di Halaman unduh Python atau menggunakan paket manajer dari sistem operasi yang Anda gunakan.

Untuk pengguna Windows

Lihat Pasang Phyton di dokumen Windows untuk panduan tambahan.

Kode Etik

Sebagai penyumbang, anda dapat membantu kami menjaga komunitas Django terbuka dan inklusif. Silahkan baca dan ikuti ``Code of Conduct <https://www.djangoproject.com/conduct/>`_ kami.

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

Untuk memeriksa apakah atau tidak anda telah terpasang Git, masukkan git ke baris perintah. Jika anda mendapatkan pesan dimana perintah ini tidak ditemukan, anda akan perlu mengunduh dan memasangnya, lihat Halaman unduh Git.

Jika anda tidak akrab dengan Git, anda dapat selalu menemukan lebih tentang perintahnya (pertama dia dipasang) dengan mengetik git help kedalam baris perintah.

Mendapatkan salinan versi pengembangan Django

Langkah pertama untuk membantu Django adalah mendapatkan sebuah salinan dari kode sumber. Pertama, fork Django on GitHub. Kemudian, dari baris perintah, gunakan perintah cd untuk melayari ke direktori dimana anda akan ingin salinan lokal anda dari Django menjadi langsung.

Unduh gudang kode sumber Django menggunakan perintah berikut:

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

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

Hubungan lebar pita rendah?

Anda dapat menambah argumen --depth 1 pada git clone untuk melewati pengunduhan semua dari riwayat penyerahan Django, yang mengurangi perpindahan data dari ~250 MB menjadi ~70 MB.

Sekarang dimana anda memiliki salinan lokal Django, anda dapat memasang itu seperti anda memasang paket apapun menggunakan pip. Cara paling nyaman melakukannya adalah dengan menggunakan virtual environment, yaitu fitur dibangun kedalam Python yang mengizinkan anda menjaga direktori terpisah dari paket-paket terpasang untuk setiap dari proyek-proyek anda sehingga mereka tidak mengganggu satu sama lain.

Itu adalah ide bagus menjaga semua lingkungan maya anda dalam satu tempat, sebagai contoh dalam .virtualenvs/ di direktori rumah anda.

Buat lingkungan maya baru dengan menjalankan:

$ python3 -m venv ~/.virtualenvs/djangodev

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

Jalur dimana lingkungan baru akan disimpan ke komputer anda.

langkah akhir dalam mengatur lingkungan maya adalah mengaktifkan itu:

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

Jika perintah source tidak tersedua, anda dapat mencoba menggunakan titik:

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

Anda harus mengaktifkan lingkungan virtual setiap kali Anda membuka jendela terminal baru.

Untuk pengguna Windows

Untuk mengaktifkan lingkungan maya pada Windows, jalankan:

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

Nama dari lingkungan maya diaktivasi sekarang ditampilkan pada baris perintah untuk membantu anda melacak dimana yang anda sedang gunakan. Apapun anda pasang melalui pip selagi nama ini ditampilkan akan dipasang dalam lingkungan maya, terpencil dari lingkungan dan paket-paket sistem-lebar.

Lanjutkan dan pasang klon salinan sebelumnya dari 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.

Membuat proyek dengan salinan lokal 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.

You can follow the tutorial for help in creating a Django project.

Menjalankan rangkaian percobaan Django untuk pertama kali

Ketika membantu Django adalah sangat penting bahwa perubahan kode anda tidak memperkenalkan kesalahan kedalam kawasan Django lain. Satu cara untuk memeriksa bahwa Django masih bekerja setelah anda membuat perubahan anda adalah dengan menjalankan deretan percobaan Django. Jika semua percobaan masih terlewati, lalu anda cukup yakin bahwa perubahan anda bekerja dan tidak merusak bagian lain dari Django. Jika anda tidak pernah menjalankan deretan percobaan Django sebelumnya, adalah ide bagus untuk menjalankannya sekali sebelumnya untuk lebih akrab dengan keluarannya.

Sebelum menjalankan deretan pengujian, masukkan direktori tests/ Django menggunakan perintah cd tests dan pasang ketergantungan pengujian dengan menjalankan:

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

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

Jika anda mengalami sebuah kesalahan selama pemasangan, sisem anda mungkin kehilangan ketergantungan untuk satu atau lebih paket Python. Obrolkan dokumentasi paket yang gagal atau cari di jaringan dengan pesan kesalahan yang anda alami.

Now we are ready to run the test suite:

$ ./runtests.py

...\> runtests.py

Sekarang duduk dan rileks. Keseluruhan rangkaian pengujian Django mempunyai ribuan pengujian, dan itu membutuhkan paling sedikit beberapa menit untuk dijalankan, tergantung pada kecepatan komputer anda.

Selagi deretan percobaan Django berjalan, anda akan melihat aliran karakter mewakili keadaan dari setiap percobaan sampai itu lengkap. E menunjukkan bahwa sebuah kesalahan memunculkan selama percobaan, dan F menunjukkan bahwa tuntutan percobaan gagal. Kedua dari ini dipertimbangkan menjadi kegagalan percobaan. Sementara itu, x dan s menunjukkan diharapkan kegagalan dan melewati percobaan, masing-masing. Titik menunjukkan percobaan lolos.

Lewati percobaan biasanya karena kehilangan pustaka luar yang diwajibkan untuk menjalankan percobaan; lihat Menjalankan semua percobaan untuk daftar dari ketergantungan dan pastikan memasang tiap untuk percobaan terhubung ke perubahan anda sedang buat (kami tidak akan butuh untuk tutorial ini). Beberapa percobaan sangat khusus pada backend basisdata tertentu dan akan dilewati jika tidak dicobakan dengan backend itu. SQLite adalah backend basisdata untuk pengaturan awal. Untuk menjalankan percobaan menggunakan backend berbeda, lihat Gunakan modul pengaturan lain.

Ketika percobaan lengkap, anda akan disapa dengan pesan menginformasikan bahwa deretan percobaan lulus atau gagal. Sejak anda tidak mempunyai perubahan apapun ke kode Django, deretan percobaan seluruhnya harus lulus. Jika anda mendapatkan kegagalan atau kesalahan pastikan anda telah mengikuti langkah sebelumnya dengan benar. Lihat Menjalankan satuan percobaan untuk informasi lebih.

Catat bahwacabang "main" Django mungkin tidak selalu stabil. Ketika mengembangkan terhadap "main", anda dapat memeriksa Django's continuous integration builds untuk menentukan jika kegagalan spesifik pada mesin anda atau jika mereka juga hadir dalam bangunan resmi Django. Jika anda mengklik untuk melihat bangunan tertentu, anda dapat melihat "Configuration Matrix" yang menunjukkan kegagalan dipecah oleh versi Python dan backend basisdata.

Catatan

For this tutorial and the ticket we're working on, testing against SQLite is sufficient, however, it's possible (and sometimes necessary) to run the tests using a different database. When making UI changes, you will need to run the Selenium tests.

Bekerja pada fitur

Untuk pengajaran tambahan ini, kami akan bekerja pada "tiket palsu" sebagai sebuah kasus pelajaran. Disini adalah rincian gambaran:

Tiket #99999 -- Mengizinkan membuat tos

Django harus menyediakan sebuah fungsi django.shortcuts.make_toast() yang mengembalikan 'toast'.

Kami akan menerapkan fitur ini dan percobaan terkait.

Creating a branch

Sebelum membuat perubahan apapun, buat sebuah cabang baru untuk tiket:

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

Anda dapat memilih nama apapun yang anda ingin untuk cabang, "ticket_99999" adalah sebuah contoh. Semua perubahan dibuat dalam cabang ini akan khusus pada tiket dan tidak akan mempengaruhi salinan uta,a dari kode yang kami kloning diawal.

Menulis beberapa percobaan untuk tiket anda

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.

Sekarang untuk contoh meneruskan kami.

Menulir percobaan untuk tiket #99999

Untuk menyelesaikan tiket ini, kami akan menambahkan sebuah fungsi make_toast() ke dalam modul django.shortcuts. Pertama kami akan menulis sebuah pengujian yang mencoba menggunakan fungsi dan memeriksa bahwa keluarannya terlihat benar.

Kemudikan ke folder tests/shortcuts/ Django dan buat sebuah berkas baru test_make_toast.py. Tambah kode berikut:

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


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

Percobaan ini memeriksa bahwa make_toast() mengembalikan 'toast'.

Tetapi percobaan ini terlihat sangat sulit...

Jika anda tidak pernah berurusan dengan percobaan sebelumnya, mereka dapat kelihatan sedikir sulit untuk menulis pandangan pertama. Untungnya, percobaan adalah subyek sangat besar di pemrograman komputer, sehingga terdapat banyak informasi diluar sana:

  • Tampilan bagus pertama pada penulisan percobaan untuk Django dapat ditemukan di dokumentasi pada Menulis dan menjalankan percobaan.

  • Dive Into Python (sebuah buku daring bebas untuk pengembang Phyton pemula) termasuk Perkenalan ke Unit Percobaan hebat.

  • Setelah membaca itu, jika anda ingin sesuatu sedikit daging untuk menengelamkan gigi anda kedalamnya, selalu ada dokumentasi unittest Python.

Menjalankan percobaan baru anda

Sejak kami belum membuat perubahan apapun pada django.shortcuts, percobaan kami harus gagal. Mari kita jalankan semua percobaan dalam folder shortcuts untuk memastikan bahwa itu memang terjadi. cd ke direktori tests/ Django dan jalankan:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

If the tests ran correctly, you should see one failure corresponding to the test method we added, with this error:

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

Jika semua percobaan dilewati, kemudian anda akan ingin memastikan bahwa anda menambahkan percobaan terbaru ditampilkan diatas pada folder dan nama berkas sesuai.

Menulis kode untuk tiket anda

Selanjutnya kami akan menambahkan fungsi make_toast().

Kemudikan ke folder django/ dan buka berkas shortcuts.py. Pada bagian bawah, tambah:

def make_toast():
    return "toast"

Sekarang kami butuh memastikan bahwa percobaan kami tulis sebelumnya lolos, jadi kami dapat melihat apakah kode kami tambahkan bekerja dengan benar. Kembali, kemudikan ke direktori tests/ Django dan jalankan:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Semuanya harus dilewatkan. Jika itu tidak, pastikan anda dengan benar menambahkan fungsi ke berkas benar.

Menjalankan rangkaian percobaan Django untuk kedua kali

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.

Untuk menjalankan seluruh rangkaian percobaan Django, cd kedalam direktori test/ Django dan jalankan:

$ ./runtests.py

...\> runtests.py

Menulis Dokumentasi

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

Untuk informasi lebih dalam menulis dokumen, termasuk penjelasan dari apa semua tentang bit versionadded, lihat Menulis dokumentasi. Halaman itu juga menyertakan sebuah penjelasan dari bagaimana membangun salinan dari dokumentasi secara lokal, sehingga anda dapat meninjau HTML yang akan dibangkitkan.

Pratinjau perubahan anda

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

Kemudian tampilkan perbedaan diantara salinan saat ini dari Django (dengan perubahan anda) dan perbaikan yang anda awali periksa di paling awal dengan petunjuk penggunaan:

$ git diff --cached

...\> git diff --cached

Gunakan kunci panah untuk pindah ke atas dan ke bawah.

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

Memperbaiki perubahan:

$ git commit

...\> git commit

Ini membuka penyunting teks untuk mengetik pesanperbaikan. Ikuti commit message guidelines dan tulis sebuah pesan seperti:

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

Mendorong perbaikan dan membuat sebuah 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

Anda dapat membuat sebuah pull request dengan mengunjungi Django GitHub page. Anda akan melihat cabang anda dibawah "Your recently pushed branches". Klik "Compare & pull request" dekatnya.

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

Langkah-langkah selanjutnya

Selamat, anda telah belajar bagaimana membuat sebuah pull request pada Django! Rincian dari teknik-teknik lebih lanjut anda mungkin butuh adalah di Bekerja dengan Git dan GitHub.

Sekarang anda dapat menaruh keahlian-keahlian tersebut untuk penggunaan bagus dengan membantu memperbaiki kode dasar Django.

Informasi lebih untuk penyumbang baru

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.

  • Pertama kali penyumbang harus juga membaca documentation for first time contributors. Django. Itu mempunyai banyak saran baik untuk siapa dari kita yang baru untuk dibantu dengan Django.

  • Setelah itu, jika anda masih terburu-buru untuk informasi lebih tentang bantuan, anda dapat selalu menjelajah melalui sisa Django's documentation on contributing. Itu mengandung ton dari informasi berguna dan harus menjadi sumber pertama anda untuk menjawab pertanyaan papun anda mungkin punya.

Temukan tiket sungguhan pertama anda

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.

Apa selanjutnya setelah membuat sebuah pull request?

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 Mendahulukan tiket for details.

Back to Top