Lewati ke isi

Panduan Kontribusi

Kami ingin Anda berkontribusi pada Pydantic!

Masalah

Pertanyaan, permintaan fitur, dan laporan bug diterima sebagai diskusi atau masalah. Namun, untuk melaporkan kerentanan keamanan, silakan lihat kebijakan keamanan kami.

Untuk mempermudah kami membantu Anda, harap sertakan keluaran panggilan berikut dalam masalah Anda:

python -c "import pydantic.version; print(pydantic.version.version_info())"

Jika Anda menggunakan Pydantic sebelum v2.0 silakan gunakan:

python -c "import pydantic.utils; print(pydantic.utils.version_info())"

Jika Anda menggunakan Pydantic sebelum v1.3 (saat version_info() ditambahkan), harap sertakan OS, versi Python, dan versi pydantic secara manual.

Harap selalu menyertakan hal di atas kecuali Anda tidak dapat menginstal Pydantic atau tahu itu tidak relevan dengan pertanyaan atau permintaan fitur Anda.

Tarik Permintaan

Seharusnya sangat mudah untuk memulai dan membuat Permintaan Tarik. Pydantic dirilis secara berkala sehingga Anda akan melihat peningkatan Anda dirilis dalam hitungan hari atau minggu 🚀.

Kecuali jika perubahan Anda sepele (salah ketik, perubahan dokumen, dll.), harap buat masalah untuk mendiskusikan perubahan tersebut sebelum membuat permintaan penarikan.

!!! catatan "Pydantic V1 sedang dalam mode pemeliharaan" Pydantic v1 sedang dalam mode pemeliharaan, artinya hanya perbaikan bug dan perbaikan keamanan yang akan diterima. Fitur baru harus ditargetkan pada Pydantic v2.

To submit a fix to Pydantic v1, use the `1.10.X-fixes` branch.

Jika Anda sedang mencari sesuatu untuk membuat gigi Anda tertarik, lihatlah "dibutuhkan bantuan" label di github.

Untuk membuat kontribusi semudah dan secepat mungkin, Anda sebaiknya menjalankan pengujian dan linting secara lokal. Untungnya, Pydantic memiliki sedikit ketergantungan, tidak memerlukan kompilasi dan pengujian tidak memerlukan akses ke database, dll. Oleh karena itu, pengaturan dan menjalankan pengujian seharusnya sangat sederhana.

!!! tip tl;dr: gunakan make format untuk memperbaiki pemformatan, make untuk menjalankan tes dan linting & membuat dokumen untuk membuat dokumen.

Prasyarat

Anda memerlukan prasyarat berikut:

  • Versi Python apa pun antara Python 3.8 dan 3.11
  • virtualenv atau alat lingkungan virtual lainnya
  • git
  • membuat
  • PDM

Instalasi dan pengaturan

Fork repositori di GitHub dan kloning fork Anda secara lokal.

# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/pydantic.git
cd pydantic

# Install PDM and pre-commit
# We use pipx here, for other options see:
# https://pdm.fming.dev/latest/#installation
# https://pre-commit.com/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install pdm
pipx install pre-commit

# Install pydantic, dependencies, test dependencies and doc dependencies
make install

Kunjungi cabang baru dan buat perubahan Anda

Buat cabang baru untuk perubahan Anda.

# Checkout a new branch and make your changes
git checkout -b my-new-feature-branch
# Make your changes...

Jalankan pengujian dan linting

Jalankan pengujian dan linting secara lokal untuk memastikan semuanya berfungsi sesuai harapan.

# Run automated code formatting and linting
make format
# Pydantic uses ruff, an awesome Python linter written in rust
# https://github.com/astral-sh/ruff

# Run tests and linting
make
# There are a few sub-commands in Makefile like `test`, `testcov` and `lint`
# which you might want to use, but generally just `make` should be all you need.
# You can run `make help` to see more options.

Bangun dokumentasi

Jika Anda telah membuat perubahan apa pun pada dokumentasi (termasuk perubahan pada tanda tangan fungsi, definisi kelas, atau docstring yang akan muncul di dokumentasi API), pastikan dokumentasi tersebut berhasil dibuat.

# Build documentation
make docs
# If you have changed the documentation, make sure it builds successfully.
# You can also use `pdm run mkdocs serve` to serve the documentation at localhost:8000

Komit dan dorong perubahan Anda

Komit perubahan Anda, dorong cabang Anda ke GitHub, dan buat permintaan tarik.

Silakan ikuti templat permintaan tarik dan isi informasi sebanyak mungkin. Tautkan ke masalah apa pun yang relevan dan sertakan deskripsi perubahan Anda.

Saat permintaan penarikan Anda siap untuk ditinjau, tambahkan komentar dengan pesan "harap tinjau" dan kami akan memeriksanya sesegera mungkin.

Gaya dan persyaratan kode

SEMUA

Gaya dokumentasi

Dokumentasi ditulis dalam Markdown dan dibuat menggunakan Material untuk MkDocs. Dokumentasi API dibuat dari docstrings menggunakan mkdocstrings.

Dokumentasi kode

Saat berkontribusi ke Pydantic, pastikan semua kode didokumentasikan dengan baik. Hal berikut ini harus didokumentasikan menggunakan dokumen yang diformat dengan benar:

  • Modul
  • Definisi kelas
  • Definisi fungsi
  • Variabel tingkat modul

Pydantic menggunakan dokumen gaya Google yang diformat sesuai dengan pedoman PEP 257. (Lihat Contoh Google Style Python Docstrings untuk contoh lebih lanjut.)

pydocstyle digunakan untuk linting dokumen. Anda dapat menjalankan make format untuk memeriksa dokumen Anda.

Jika terdapat konflik antara dokumen gaya Google dan linting pydocstyle, ikuti petunjuk linting pydocstyle.

Atribut kelas dan argumen fungsi harus didokumentasikan dalam format "nama: deskripsi". Jika berlaku, jenis pengembalian harus didokumentasikan hanya dengan deskripsi. Jenis disimpulkan dari tanda tangan.

class Foo:
    """A class docstring.

    Attributes:
        bar: A description of bar. Defaults to "bar".
    """

    bar: str = 'bar'


def bar(self, baz: int) -> str:
    """A function docstring.

    Args:
        baz: A description of `baz`.

    Returns:
        A description of the return value.
    """

    return 'bar'

Anda dapat memasukkan kode contoh di docstrings. Kode ini harus lengkap, mandiri, dan dapat dijalankan. Contoh docstring diuji menggunakan doctest, jadi pastikan sudah benar dan lengkap. Lihat FieldInfo.from_annotated_attribute() sebagai contoh.

!!! catatan "Atribut kelas dan instance" Atribut kelas harus didokumentasikan dalam dokumen kelas.

Instance attributes should be documented as "Args" in the `__init__` docstring.

Gaya Dokumentasi

Secara umum, dokumentasi harus ditulis dengan gaya yang bersahabat dan mudah didekati. Itu harus mudah dibaca dan dipahami, dan harus sesingkat mungkin namun tetap lengkap.

Contoh kode dianjurkan, tetapi harus dibuat singkat dan sederhana. Namun, setiap contoh kode harus lengkap, mandiri, dan dapat dijalankan. (Jika Anda tidak yakin bagaimana melakukan ini, mintalah bantuan!) Kami lebih memilih keluaran cetak daripada penegasan telanjang, tetapi jika Anda menguji sesuatu yang tidak memiliki keluaran cetak yang berguna, penegasan tidak masalah.

Pengujian unit Pydantic akan menguji semua contoh kode dalam dokumentasi, jadi penting agar contoh kode tersebut benar dan lengkap. Saat menambahkan contoh kode baru, gunakan yang berikut ini untuk menguji contoh dan memperbarui format dan outputnya:

# Run tests and update code examples
pytest tests/test_docs.py --update-examples

Men-debug Python dan Rust

Jika Anda bekerja dengan pydantic dan pydantic-core, Anda mungkin akan terbantu jika men-debug kode Python dan Rust secara bersamaan. Berikut panduan singkat tentang cara melakukannya. Tutorial ini dilakukan di VSCode, tetapi Anda dapat menggunakan langkah serupa di IDE lain.

Lencana

Pydantic v1 Pydantic v2

Pydantic memiliki lencana yang dapat Anda gunakan untuk menunjukkan bahwa proyek Anda menggunakan Pydantic. Anda dapat menggunakan lencana ini di README.md Anda:

Dengan penurunan harga

[![Pydantic v1](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json)](https://pydantic.dev)

[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)

Dengan reStructuredText

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json
    :target: https://pydantic.dev
    :alt: Pydantic

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json
    :target: https://pydantic.dev
    :alt: Pydantic

Dengan HTML

<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json" alt="Pydantic Version 1" style="max-width:100%;"></a>

<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json" alt="Pydantic Version 2" style="max-width:100%;"></a>
本文总阅读量次