Mengubah proyek Python pribadi menjadi perpustakaan yang dapat dirilis

Saya seorang akademis daripada seorang programmer, dan saya memiliki pengalaman bertahun-tahun menulis program Python untuk saya gunakan sendiri, untuk mendukung penelitian saya. Proyek terbaru saya mungkin bermanfaat bagi banyak orang lain seperti halnya saya, dan saya berpikir untuk melepaskannya sebagai pustaka Python open-source.

Namun, tampaknya ada beberapa rintangan untuk menyeberang dari proyek pribadi yang berfungsi ke perpustakaan yang dapat diinstal dan digunakan tanpa rasa sakit oleh orang lain. Pertanyaan ini adalah tentang langkah pertama yang harus saya ambil untuk mulai bekerja menuju rilis publik.

Saat ini, saya memiliki repositori git tunggal yang berisi kode saya yang menggunakan pustaka serta pustaka itu sendiri, dan saya menggunakan git sebagai tombol urung darurat jika terjadi kerusakan. Semua ini berfungsi dengan baik untuk satu pengguna tetapi jelas tidak sesuai jika saya ingin melepaskannya. Di mana saya ingin berakhir adalah bahwa perpustakaan saya berada di repositori terpisah dan dapat diinstal oleh orang lain menggunakan pip, dan memiliki API yang stabil.

Belajar menggunakan setuptools dll. Mungkin tidak begitu sulit begitu saya pada titik ingin mempublikasikannya - masalah saya adalah mengetahui bagaimana saya harus bekerja untuk sampai ke titik itu.

Jadi pertanyaan saya adalah, apa langkah pertama yang harus diambil seseorang untuk mulai menyiapkan proyek perpustakaan Python untuk konsumsi publik? Bagaimana saya harus mengatur ulang struktur direktori saya, git repositori, dll. Agar dapat mulai bekerja ke publik, rilis perpustakaan?

Secara umum, akan sangat membantu jika ada sumber daya yang diketahui sangat membantu ketika mencoba ini untuk pertama kalinya. Menunjuk pada praktik terbaik dan kesalahan yang harus dihindari, dll., Juga akan sangat membantu.

Beberapa klarifikasi: jawaban saat ini menjawab pertanyaan di sepanjang baris "bagaimana saya bisa membuat perpustakaan Python saya menjadi yang baik untuk digunakan orang lain?" Ini berguna, tetapi berbeda dari pertanyaan yang ingin saya tanyakan.

Saya saat ini sedang memulai perjalanan panjang untuk merilis proyek saya. Inti dari implementasi saya bekerja (dan bekerja dengan sangat baik), tetapi saya merasa kewalahan dengan jumlah pekerjaan di depan saya, dan saya sedang mencari panduan tentang cara menavigasi proses. Sebagai contoh:

• Kode perpustakaan saya saat ini digabungkan ke kode khusus domain saya sendiri yang menggunakannya. Ia hidup dalam subfolder dan berbagi repositori git yang sama. Akhirnya, itu harus dibuat menjadi perpustakaan yang berdiri sendiri dan dimasukkan ke dalam repositori sendiri, tetapi saya terus menunda-nunda ini karena saya tidak tahu bagaimana melakukannya. (Entah bagaimana cara menginstal perpustakaan dalam 'mode pengembangan' sehingga saya masih bisa mengeditnya, atau bagaimana menjaga agar kedua repo git tetap sinkron.)

• Dokumen saya singkat, karena saya tahu bahwa pada akhirnya saya harus menggunakan Sphinx atau alat lain. Tetapi alat-alat ini tampaknya tidak mudah dipelajari, jadi ini menjadi sub-proyek utama dan saya terus menundanya.

• Pada titik tertentu saya perlu belajar menggunakan setuptools atau alat lain untuk mengemasnya dan melacak dependensinya, yang cukup rumit. Saya tidak yakin apakah saya perlu melakukan ini sekarang atau tidak, dan dokumentasinya adalah labirin absolut untuk pengguna baru, jadi saya terus memutuskan untuk melakukannya nanti.

• Saya tidak pernah harus melakukan pengujian sistematis, tetapi saya pasti akan melakukannya untuk proyek ini, jadi saya harus (i) cukup belajar tentang pengujian untuk mengetahui metodologi mana yang tepat untuk proyek saya; (ii) mempelajari alat apa yang tersedia untuk metodologi yang saya pilih; (iii) belajar menggunakan alat yang saya pilih; (iv) mengimplementasikan test suites dll untuk proyek saya. Ini adalah proyek itu sendiri.

• Mungkin ada hal-hal lain yang harus saya lakukan juga. Sebagai contoh, jonrsharpe memposting tautan bermanfaat yang menyebutkan git-flow, tox, TravisCI, virtualenv dan CookieCutter, yang belum pernah saya dengar sebelumnya. (Posnya dari tahun 2013, jadi saya juga harus melakukan beberapa pekerjaan untuk mengetahui berapa banyak yang masih ada saat ini.)

Ketika Anda menyatukan semua ini, ini adalah pekerjaan yang sangat besar, tapi saya yakin saya bisa menyelesaikan semuanya jika saya terus berusaha melakukannya, dan saya tidak terburu-buru. Masalah saya adalah mengetahui bagaimana memecahnya menjadi langkah-langkah yang dapat dikelola yang dapat dilakukan satu per satu.

Dengan kata lain, saya menanyakan langkah konkret yang paling penting yang dapat saya ambil sekarang, untuk mencapai produk yang dapat dirilis pada akhirnya. Jika saya memiliki akhir pekan gratis, manakah dari hal-hal ini yang harus saya fokuskan? Yang mana (jika ada) yang bisa dilakukan secara terpisah dari yang lain, sehingga saya setidaknya bisa menyelesaikan satu langkah tanpa perlu melakukan semuanya? Apa cara paling efisien untuk mempelajari hal-hal ini sehingga saya masih punya waktu untuk fokus pada proyek itu sendiri? (Mengingat bahwa semua ini pada dasarnya adalah proyek hobi, bukan pekerjaan saya.) Apakah ada yang benar-benar tidak perlu saya lakukan , sehingga menghemat banyak waktu dan usaha?

Semua jawaban sangat dihargai, tetapi saya akan sangat menyambut jawaban yang berfokus pada aspek manajemen proyek ini, dengan referensi khusus untuk pengembangan Python modern.

Menambahkan setup.py, saat diperlukan, bukan langkah paling penting jika Anda ingin perpustakaan Anda digunakan. Yang lebih penting adalah menambahkan dokumentasi dan mengiklankan perpustakaan Anda. Karena poin kedua sangat tergantung pada perpustakaan, izinkan saya lebih fokus pada aspek dokumentasi.

1. Anda tahu segalanya tentang perpustakaan Anda. Dan ini bermasalah. Anda sudah tahu cara menginstal dan cara menggunakannya, begitu banyak hal yang tampak intuitif atau jelas bagi Anda. Sayangnya, hal yang sama mungkin tidak jelas, tidak intuitif untuk pengguna. Cobalah untuk melihat perpustakaan Anda seolah-olah Anda tidak tahu apa-apa tentang itu, dan yang lebih penting, mintalah orang lain untuk menggunakannya dan cobalah untuk menemukan semua kesulitan yang mereka miliki.

2. Jelaskan, dalam bahasa Inggris yang sederhana, tentang apa perpustakaan Anda. Terlalu banyak perpustakaan menganggap bahwa semua orang tahu tentang mereka. Ketika ini tidak terjadi, mungkin sulit untuk memahami apa tujuan perpustakaan.

3. Menulis dokumentasi teknis terperinci, tetapi juga jangan lupa tentang potongan kode pendek yang menunjukkan bagaimana melakukan beberapa tugas dengan perpustakaan Anda. Sebagian besar pengembang sedang terburu-buru, dan jika mereka perlu menghabiskan berjam-jam mencoba memahami bagaimana melakukan hal dasar, mereka mungkin cenderung beralih ke perpustakaan lain.

4. Sertakan informasi kontak Anda. Jika perpustakaan Anda sukses (dan pengalaman saya sendiri telah menunjukkan bahwa ini adalah kasus bahkan untuk yang agak tidak dikenal juga), orang akan mengalami kesulitan dengan itu: baik bug atau hanya kesulitan memahami atau menggunakan beberapa bagian dari itu. Seringkali berguna untuk menerima umpan balik mereka untuk meningkatkan perpustakaan Anda: untuk setiap orang yang melaporkan masalah, mungkin ada ratusan orang yang, ketika menjumpainya, akan lebih memilih untuk beralih ke perpustakaan lain.

Selain itu:

1. Jelaskan jika pustaka Anda berfungsi dengan Python 2 atau 3 atau keduanya.

2. Jika perpustakaan tidak berfungsi di Windows, katakan demikian.

3. Pastikan Anda menggunakan konvensi resmi (gunakan pep8 untuk memeriksa). Jika tidak, jelaskan dengan jelas atau perbaiki.

4. Jaga penanganan tepi kasus. Ketika pustaka Anda dipanggil dengan tipe yang salah atau dengan nilai yang tidak didukung, seharusnya dikatakan, dalam bahasa Inggris biasa, apa sebenarnya yang salah. Apa yang seharusnya tidak dilakukan adalah untuk meningkatkan pengecualian samar sepuluh tingkat di tumpukan dan membiarkan pengguna mencari tahu apa yang salah.

Setelah menggunakan beberapa perpustakaan yang kurang dari cukup matang selama bertahun-tahun sepotong saran utama adalah setelah Anda memilih alat penyebaran Anda lakukan hal berikut: Apakah perpustakaan Anda melakukan sesuatu yang benar-benar berguna sehingga Anda dapat membangun komunitas di sekitar?

Identifikasi dependensi perpustakaan Anda.

Mencoba penyebaran ke lingkungan yang bersih baik wadah map atau VM. Saya menganggap langkah ini penting karena seringkali ada sesuatu yang unik tentang lingkungan pribadi yang menyebabkan masalah.

Pertimbangkan siapa yang akan memelihara perpustakaan di masa depan, tidak ada yang lebih menyebalkan daripada menjumpai perpustakaan yang merupakan proyek kesayangan seseorang selama tiga atau empat tahun dan kemudian tidak mendapatkan pembaruan yang diperlukan untuk menjaga perpustakaan tetap terkini.

Pertimbangkan apakah Anda atau tim Anda ingin membuat komitmen agar perpustakaan diuji dan didokumentasikan (unit test dan pipa CI mulai menjadi bagian dari persamaan ihere).

Mungkin Anda bisa menemukan proyek OSS dewasa di bidang Anda dan menyumbangkan kode Anda ke proyek itu? Mungkin ada beberapa keuntungan, seperti:

• Anda dapat memaksimalkan kontribusi Anda. Memang, banyak proyek "hobi" OSS berpotensi berharga tetapi hanya digunakan sedikit oleh komunitas (lih. @ReaddyEddy menjawab). Ini hanya banyak upaya untuk membuat proyek tergores pada awalnya, kemudian untuk mempertahankannya, mengiklankannya, memberikan contoh dan dokumentasi yang tepat, dll.
• Banyak masalah teknis yang Anda sebutkan akan diselesaikan dalam proyek yang matang.
• Jika perpustakaan Anda menambah nilai pada proyek OSS, kontributornya dapat membantu Anda membawa kode Anda ke standar proyek. Jadi Anda bisa menghemat usaha dan mendapatkan pengalaman. Anda juga akan mendapatkan jawaban spesifik tentang Sphinx, TravisCI, CookieCutter dan aspek teknis lainnya.

Jika ada proyek OSS yang relevan yang Anda sukai dan mungkin gunakan, mengapa tidak membuka masalah atau permintaan tarik atau menghubungi pengelola? (Cara yang baik untuk memulai mungkin adalah dengan memecahkan masalah yang ada.)

Ini tahun 2019, saya sangat menyarankan memulai dengan alat paling modern. Anda tidak perlu setup.py, itu adalah sesuatu yang ingin orang-orang di komunitas Python singkirkan, dan saya yakin pada akhirnya mereka akan berhasil.

Coba Puisi , Anda tidak akan menyesalinya.

Ini adalah pertanyaan rumit yang Anda tanyakan, dan saya sepenuhnya setuju dengan jawaban Arseni . Dokumentasi yang baik adalah aspek yang sangat penting. Jika saya tidak berhasil mengaktifkan dan menjalankan perpustakaan Anda dengan beberapa langkah sederhana, saya hanya menjatuhkannya di sana (kecuali saya benar-benar ingin mencobanya).

Beberapa hal yang pasti Anda pertimbangkan

• Pikirkan tentang bagaimana Anda akan versi perpustakaan Anda. Anda ingin memiliki kompatibilitas ke belakang ke tingkat tertentu, dan perbaikan bug di sepanjang rute juga. Baca tentang versi semantik
• Anda menggunakan git dengan cara yang relatif linier (untuk membatalkan). Apakah Anda terbiasa dengan bercabang di git . Ini benar-benar tidak sulit, dan membuat hidup mudah. Setelah Anda menguasai cabang. Adaptasikan model percabangan untuk repositori Anda. Pilih bagian-bagian dari model percabangan ini yang Anda anggap relevan. Bandingkan juga dengan cabang dari repositori yang Anda gunakan.
• Lisensi: Anda harus memberikan lisensi untuk perpustakaan Anda. Saya bukan ahli hukum dalam hal ini, jadi saya hanya bisa membagikan tautan ke perbandingan antara lisensi umum ini . Jangan menganggap enteng pilihan ini.
• Bugtracker. Anda ingin agar pengguna dapat memberi Anda laporan bug. Ini membantu Anda meningkatkan kualitas kode. Untuk setiap bug yang Anda selesaikan, tambahkan tes ke kerangka kerja pengujian Anda, yang memastikan bahwa itu tidak mengerem di masa depan (pengujian regresi). Sistem pelacakan bug dapat digunakan untuk permintaan fitur.
• Kontribusi pengguna. Apakah Anda ingin kontribusi pengguna? Saya tidak yakin bagaimana ini biasanya bekerja pada produk-produk open-source, tetapi saya dapat membayangkan bahwa Anda dapat mengizinkan pengguna untuk membuat cabang fitur. Melalui github Anda tampaknya dapat mengendalikan ini melalui permintaan tarik

Saya tidak punya pengalaman yang relevan dengan Python, jadi saya tidak bisa memberi Anda petunjuk ke arah itu. Namun, dimungkinkan untuk mengotomatiskan semua pengujian yang dipicu oleh masing-masing komit pada repositori jarak jauh Anda (yaitu menggunakan Jenkins ). Namun saya menyarankan untuk menunda ini, karena banyak pekerjaan yang harus dilakukan tanpa pengalaman sebelumnya.

Ini adalah pertanyaan bagus.

Tentang langkah inkremental penting yang penting menuju perpustakaan yang dapat dirilis:

• Pisahkan file yang akan menjadi perpustakaan dari sisa proyek.
  • Pustaka harus masuk ke repositori gitnya sendiri tetapi Anda mungkin menganggapnya sebagai langkah perantara yang berguna untuk meletakkannya di direktori tingkat atas yang terpisah dalam repositori Anda saat ini. Ketika Anda membuatnya menjadi repositori terpisah, simpan yang bersebelahan dengan sisa proyek Anda, yang kemudian dapat merujuk melalui ../librarysampai Anda berkeliling ke langkah-langkah pemaketan pip dan mode pengembangan.
  • Semua akses dari sisa proyek ke perpustakaan ini harus melalui API publiknya. Anda mungkin menemukan beberapa saling ketergantungan untuk menggoda.
• Jadilah menulis dokumen secara bertahap untuk mendokumentasikan API perpustakaan.
  • Akhirnya dokumen akan dimasukkan ke dalam alat dokumentasi, tetapi pekerjaan yang penting adalah menulis teks yang menjelaskan API secara ringkas dan memadai kepada orang lain. Lebih mudah mengisinya sedikit demi sedikit daripada sekaligus, dan itu akan jauh lebih baik dengan menulis draft kasar dan kembali lagi nanti ketika penjelasan dan contoh yang lebih baik muncul di benak.
  • Jika Anda menemukan beberapa bagian dari API sulit untuk didokumentasikan, tanyakan apakah bagian dari API tersebut memiliki ruang untuk perbaikan. Mungkinkah ini lebih sederhana? Lebih teratur? Apakah ini terlalu umum? Terlalu terspesialisasi? Bisakah itu menggunakan nama yang lebih akrab?
  • Docstrings dapat mendokumentasikan tipe argumen menggunakan komentar terstruktur yang dapat diperiksa oleh alat. Saya belum menemukan dokumentasi yang sebenarnya tentang itu, tetapi IDE PyCharm akan membantu membangun dokumen-dokumen itu dan akan segera memeriksa jenis argumen saat mengedit panggilan metode.
  • Omong-omong, PyCharm adalah alat yang luar biasa untuk menghemat waktu pengembang dan meningkatkan kualitas kode. Ini akan menjalankan "inspeksi" untuk memeriksa kode saat Anda mengeditnya, mis. Memeriksa jenis kapan saja, memeriksa impor yang hilang dan tidak terpakai, metode duplikat, kesalahan gaya PEP 8, dan sebagainya.
• Mulai menulis tes unit menggunakan pytest. Jauh sebelum Anda membuat rilis, unit test akan terbayar dalam pengembangan Anda sendiri dengan menemukan bug di kasing sudut dan memberikan keyakinan bahwa perubahan kode tidak merusak banyak hal. Sekali lagi, Anda dapat membangun ini dari waktu ke waktu. Cukup mudah untuk memulai.
• Membaca dengan teliti perpustakaan open source yang ada (yang kira-kira berukuran sama) di GitHub untuk melihat bagaimana mereka mengatur file dan rilis. Lihat bagaimana mereka melakukan pelacakan bug / masalah dan menarik permintaan. Berkontribusi kepada satu atau lebih dari mereka untuk mendapatkan pengalaman dengan proses organisasi proyek multi-orang ini jika Anda tidak memiliki pengalaman di sana. GitHub memiliki alat yang bagus untuk proses ini. Itu melakukan hal-hal baik dengan README.mdfile dokumentasi di tingkat atas dan di direktori apa pun, dan dengan file lisensi.
• Pertimbangkan untuk meminta kolaborator untuk mendapatkan umpan balik tentang perpustakaan, API, dan dokumentasinya.
  • Ketika Anda merilis, itu akan membantu untuk memiliki satu atau lebih kolaborator untuk memperbaiki bug ketika Anda sedang berlibur, untuk membantu menjawab pertanyaan pengguna, dan sementara itu untuk mulai melakukan Permintaan Tarik dengan ulasan kode, untuk membagi tugas-tugas yang melepaskan perpustakaan, dan membawa pengalaman tambahan dengan manajemen proyek dan desain perpustakaan.
• Sejauh ini Anda telah melakukan sejarah komit linear git. Akhirnya akan berguna untuk menggunakan "cabang masalah" untuk perbaikan dan perubahan tertentu, "cabang rilis" untuk run-up terkontrol ke rilis, dan "cabang pengembangan" untuk semua pekerjaan multi-orang dalam proses yang belum siap untuk digabung ke cabang master. Jadi sisihkan satu atau dua hari di sepanjang jalan untuk mempelajari hal ini dan mulai berlatih dengannya sebelum Anda harus bergantung pada keterampilan git tersebut. git sangat fleksibel dan berguna tetapi antarmuka pengguna bisa menjadi penuh .
  • Satu tempat untuk membaca tentang cabang git dan kegunaannya ada di buku Pro Git . Dari banyak cara untuk menggunakan cabang, mulailah dengan "cabang masalah" saja.
  • Aplikasi GitHub Desktop adalah alat yang hebat untuk mengelola cabang. Ini juga bagus untuk membuat komitmen karena membuatnya mudah untuk menulis pesan komit sambil meninjau semua perubahan.