<p>kargo baru: buat README</p>

Format bundler itu bukan yang akan saya masukkan. Saya pikir pendekatan SYNOPSIS yang dipelopori oleh cpan dan sebagian besar disalin oleh banyak paket npm adalah hal terpenting yang harus dimiliki dalam readme. Selalu di atas dengan contoh kode pendek yang menunjukkan cara menggunakan paket. Memulai dengan cara menginstal sebuah paket kurang membantu karena ketika seseorang pertama kali menemukan sebuah paket, mereka belum tahu apakah sebuah paket menyelesaikan masalah mereka dengan tepat.

Ya, saya tidak mengatakan kita harus benar-benar menyalin Bundler.

Sepertinya ide yang bagus untuk saya!

Dalam survei yang kami lakukan , orang-orang juga menyebutkan pergi ke dokumentasi dan ingin melihat konten seperti readme (tujuan dan contoh) di halaman depan dokumen. Saya pikir kami dapat mendorong halaman depan dokumentasi yang lebih baik dengan menambahkan komentar modul ke atas src/lib.rs yang dihasilkan seperti:

//! This is the top-level module documentation in src/lib.rs. //! This text appears on the front page of your crate's documentation; //! preview it by running `cargo doc --open`. //! //! # Example //! //! This is a great place to add an example of how to use your crate! //! //! ``` //! assert(true); //! ```

Teks berbicara tentang di mana ia tinggal dan di mana Anda akan melihatnya sehingga jika Anda melihat file itu, Anda akan tahu di mana teks itu berakhir, dan jika Anda melihat dokumen yang Anda buat, Anda akan tahu ke mana harus pergi untuk mengedit teks yang Anda lihat di halaman depan.

Membuat file apa pun sebagai bagian dari templat proyek menyiratkan bahwa file tersebut harus distandarisasi dalam format, IMO. Ini sulit dilakukan untuk data informal/semi-terstruktur seperti dokumentasi. Juga, bahasa markup default itu sendiri perlu diselesaikan, yang akan mengarah pada diskusi.
Mungkin langkah pertama yang baik/lebih baik adalah menuju RFC/standar untuk dokumentasi proyek? Dalam diskusi itu standar dokumentasi API Rust harus dimasukkan sebagai latar belakang, saya pikir.

Ini sulit dilakukan untuk data informal/semi-terstruktur seperti dokumentasi.

Meskipun ini benar, ada beberapa hal yang umum untuk semua proyek, dan jika tidak berhasil untuk Anda, Anda dapat menghapusnya.

Juga, bahasa markup default itu sendiri perlu diselesaikan, yang akan mengarah pada diskusi.

Ini sudah penurunan harga, oleh sebagian besar.

Mungkin langkah pertama yang baik/lebih baik adalah menuju RFC/standar untuk dokumentasi proyek?

Kami sudah memiliki dua di antaranya! https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md menjadi yang terbaru, yang dibangun di atasnya.

Tidak setuju pada poin pertama Anda. Hal yang sama berlaku untuk misalnya template masalah di GitHub, akhirnya ditolak (https://github.com/rust-lang/rust/pull/33164) karena akan merepotkan mereka yang merasa tidak cocok dengan masalah mereka. Mungkin lebih banyak orang menganggap cargo - yang dihasilkan README berisik (tidak berguna, tidak memadai) daripada membantu.

Agak tidak setuju dengan poin kedua Anda. AsciiDoctor adalah format lain yang IMO jauh lebih sesuai untuk dokumentasi perangkat lunak daripada penurunan harga (beberapa motivasi melalui https://news.ycombinator.com/item?id=11292280). Diskusi tentang ini bahkan dalam konteks Rust adalah normal (https://internals.rust-lang.org/t/rustdoc-asciidoctor-vs-markdown/4161).

Saya tidak mengacu pada dokumentasi API, tetapi pada dokumentasi pengguna. Apakah Anda setuju harus diputuskan konten apa yang sebenarnya 'umum untuk semua proyek', selanjutnya bagaimana menyajikannya secara optimal, berdasarkan studi bukti, sebelum mengeluarkan README template dengan cargo ?

Saya akan senang untuk mengambil ini. Saya ingin menetapkan ruang lingkup masalah khusus ini.

Apakah ini akan menjadi perilaku default dengan perintah cargo new ? Dan apakah akan ada tanda untuk menonaktifkan pembuatan dokumentasi otomatis?

Pemahaman saya tentang ruang lingkup sejauh ini adalah bahwa akan ada templat untuk README.md dan templat standar untuk komentar dokumentasi tingkat modul. Sudahkah kita menyepakati format standar mengenai format yang pertama?

Apakah kami juga ingin memperingatkan pengguna tentang cargo package atau cargo publish jika template dokumentasi belum dimodifikasi dari pembuatan awal? Bagaimana jika tidak ada dokumentasi dalam peti yang mungkin akan diterbitkan oleh seorang penulis?

Saya tidak berada di tim Cargo, tetapi saya berharap itu menjadi bagian dari perilaku default cargo new .

Saya baru mengetahui https://github.com/RichardLitt/standard-readme , saya belum benar-benar membacanya.

Proyek itu terlihat bagus, saya akan melihatnya. Apakah kami ingin tanda menonaktifkan pembuatan dokumentasi default?

@vignesh-sankaran: Bisakah Anda memberikan komentar @carols10cents di templat komentar dokumen ? Bagi saya itu jauh lebih kontroversial dan lebih produktif daripada membuat file README dalam format markup setiap kali Cargo diminta untuk menginisialisasi proyek baru. Bisakah Anda menerapkan proposalnya terlebih dahulu, atau bisakah kami membagi proposalnya menjadi masalah yang berbeda?

Membuat file README.md secara default menyiratkan bahwa kami menganggap penjelajahan proyek baru seperti GitHub dan preferensi untuk Penurunan Harga. Mungkin tepat untuk sebagian besar proyek (tetapi tidak ada bukti yang disajikan di sini oleh @steveklabnik), tetapi di mana kita berhenti dengan fitur creep semacam ini? Mengapa tidak memasang template proyek lengkap dengan berbagai file konfigurasi (misalnya Travis CI, dll.)? Terus terang, saya sangat menyukai alternatif, solusi komprehensif: cara Cargo membuat proyek baru sesuai dengan template, sepenuhnya independen dari file README . Tidak masalah bagi saya jika Cargo memiliki templat default untuk perpustakaan dan executable utama yang memiliki README.md . Tapi template default tidak boleh sembarangan diputuskan. Konsensus seperti RFC pada konten template akan jauh lebih tepat. Saya memperkirakan akan sangat menjengkelkan bagi pemrogram untuk harus membersihkan proyek Kargo yang baru dibuat dari cruft default karena @steveklabnik tampaknya menerima sebagai solusi. Atau dan sedikit lebih bijaksana daripada konsensus seperti RFC, adalah memulai proyek terpisah untuk setiap template dan membiarkan masalah diajukan terhadapnya oleh komunitas untuk menyelesaikan berbagai detail.

Argumen dapat dibuat bahwa alat standar (misalnya, rsync ) cukup untuk membuat perancah proyek Kargo yang baru dibuat berdasarkan template standar. Dari sudut pandang itu, menambahkan kode ke proyek scaffold ke Cargo tidak akan berguna dan memang menambah beban perawatan Cargo.

Saya tidak akan bisa mengerjakan ini sampai pertengahan November karena kuliah dan tidak ingin terlalu banyak bekerja sendiri. Jika ada orang lain yang ingin membahas masalah ini, mereka dipersilakan untuk melakukannya, jika tidak, saya akan dapat menyelesaikannya dalam waktu satu bulan.

Argumen dapat dibuat bahwa alat standar (misalnya, rsync) cukup untuk membuat perancah proyek Kargo yang baru dibuat berdasarkan template standar. Dari sudut pandang itu, menambahkan kode ke proyek scaffold ke Cargo tidak akan berguna dan memang menambah beban perawatan Cargo.

@sanmai-NL dapatkah argumen itu benar-benar didukung? Windows tidak memiliki rsync , misalnya, dan tidak ada jaminan bahwa instalasi Linux apa pun akan memiliki rsync juga. Faktanya, menurut saya, Cargo sudah memiliki semua peralatan yang diperlukan untuk mendukung templating. Salah satu pendekatan sederhana adalah mengizinkan siapa pun untuk memublikasikan proyek sebagai templat ke crates.io, dengan tag 'templat' atau yang serupa. Maka siapa pun dapat cargo new --template template_name project_name , dan selama peti template_name memiliki tag 'template', cargo dapat mengkloningnya ke direktori saat ini sebagai project_name , menggunakan fasilitas yang sama yang telah digunakan selama resolusi ketergantungan untuk menarik peti dari crates.io.

Saya juga tidak setuju bahwa README.md menyiratkan GitHub dengan cara apa pun. Semua situs web berbagi kode utama yang saya ketahui mendukung desain ini, termasuk GitLab, yang kemungkinan besar akan populer di antara orang-orang yang menghindari platform berpemilik. README sendiri adalah standar kuno yang ada jauh sebelum GitHub. README.md hanyalah modernisasinya, dan Markdown dapat dibaca dengan sempurna tanpa rendering. Ini hampir tidak sama dengan berintegrasi dengan layanan pihak ketiga seperti Travis, menurut saya.

Lebih lanjut tentang topik ini, saya telah banyak berpikir tentang betapa menyenangkannya jika cargo secara otomatis menghasilkan file README.md saat membuat proyek baru. Pikiran ini didorong dengan melihat bagaimana Crystal melakukannya, dan melihat betapa bagusnya ide itu dalam pandangan saya.

Pikiran-pikiran ini bersama-sama telah membuat saya bertanya-tanya apakah cargo harus memiliki mode interaktif untuk memungkinkan Anda mengonfigurasi berbagai hal, dengan asumsi bahwa cargo new dipanggil tanpa argumen lain. Gambar ini:

$ kargo baru
masukkan nama proyek:
haruskah ini berisi perpustakaan? [Y/t]
ini harus mengandung biner? [y/T]
tambahkan README.md default? [Y/t]
VCS mana yang digunakan? [GIT, lincah, pijul]

yang juga akan memungkinkan pengguna memilih untuk memiliki perpustakaan + peti biner, yang merupakan cara yang semakin populer untuk menyusun proyek Rust. Jelas, ini adalah sketsa yang sangat kasar dari sebuah ide yang saya rasa merupakan perpanjangan dari ide yang diajukan dalam edisi ini. Saya dapat membuka masalah lain, jika diinginkan, atau mungkin sudah ada satu untuk ini, tetapi saya tidak melihatnya.

@coder543 :

Pada rsync dan perkakas standar untuk perancah proyek

Windows memiliki robocopy . Seseorang juga dapat menggunakan cp pada OS mirip Unix. Poin saya yang lebih besar adalah bahwa memulai proyek dari beberapa perancah tidak memerlukan fitur Kargo. Saya tidak terlalu menentangnya tetapi jika fitur seperti itu ditambahkan, saya merasa sangat bahwa itu harus dirancang dan dipelihara secara intensif, tidak ditambahkan sebagai CLI baru atau perilaku default secara sembarangan.

README s

Anda memiliki poin bagus bahwa file README adalah konsep dengan riwayat yang lebih panjang daripada hanya GitHub. Poin yang ingin saya sampaikan di luar fakta ini adalah, bagaimana kita memutuskan bahasa (markup) apa yang harus digunakan dokumen ini? Saya tidak lebih suka itu menjadi Penurunan Harga atau sesuatu yang spesifik lainnya secara default. Dan Markdown paling populer di GitHub dan platform kolaborasi pengembangan perangkat lunak sentris open source lainnya. Dan poin lainnya adalah, tidak semua proyek Rust dimaksudkan untuk dikembangkan sebagai proyek open source yang khas. Karat juga seharusnya menarik untuk proyek perusahaan sumber tertutup yang besar. Minta Cargo membuat file README secara default, sementara pemrogram untuk proyek besar sebenarnya berencana menggunakan kerangka kerja dokumentasi teknis yang ekstensif seperti DocBook/Asciidoctor/Wiki/dll., menegaskan persepsi Rust sebagai 'hanya' ' bahasa mengkilap baru yang populer di dunia open source'. Saya tidak berpikir ini adalah masalah besar, tetapi pikirkan tentang bagaimana membuat semua jenis barang secara default memaksakan gaya/budaya pengembangan tertentu.

Solusi praktis

• Mode interaktif untuk Kargo (ide dari @coder543). Ini akan membantu pemrogram Rust pemula untuk membuat proyek tipikal (gaya open source) dari awal. Meskipun CLI sudah cukup, pengalaman dan intuisi saya bekerja dengan pemula (dan menjadi pemula untuk banyak hal sendiri) adalah bahwa mode interaktif benar-benar mengurangi gesekan dan membuat segalanya lebih menyenangkan.
• Mengizinkan Cargo mengubah proyek yang ada. Programmer menyalin template, dan Cargo kemudian dapat mengubahnya (misalnya, semua opsi yang dapat diatur melalui mode interaktif saat pembuatan).

Oke jadi saya kembali, mode interaktif terdengar seperti ide yang bagus, tetapi kita juga harus memiliki jalan keluar untuk pengguna yang lebih berpengalaman. Pada titik ini, haruskah kita mempertimbangkan RFC untuk masalah ini, atau setidaknya semacam definisi ruang lingkup sehingga saya tahu apa yang harus dikerjakan?

Saran @ carols10cents tentang komentar dokumen terdengar seperti ide yang bagus, mungkin saya bisa memulainya sementara itu?

Pencalonan untuk diskusi pada pertemuan Kargo berikutnya: meskipun jelas bahwa kami ingin mendorong dan menyederhanakan dokumentasi peti Rust, tidak jelas apa cara terbaik untuk mencapai hal ini. Secara khusus, membuat Readme.md dummy dan/atau komentar tingkat atas bukanlah kemenangan yang pasti, karena:

1) Seringkali seseorang membuat peti sementara satu kali, atau peti internal pribadi, tidak dipublikasikan ke crates.io, dan dalam kasus ini benar-benar valid untuk tidak memiliki dokumen, dan dokumen default hanya akan menciptakan gesekan.
2) Kami perlu entah bagaimana melindungi dari mengunggah peti dengan dokumen/readme default.

Pendekatan alternatif adalah menambahkan "cek preflight" pada cargo publish . Misalnya, kita dapat memperingatkan selama publish jika kolom Cargo.toml tidak diisi, jika Readme tidak ada dan jika tidak ada dokumentasi.

Seperti yang disarankan oleh @matklad , kami dapat memiliki peringatan tentang dokumentasi yang hilang yang dijalankan sebagai pemeriksaan sebelum publikasi awal. Mungkin kami juga dapat menjalankan pemeriksaan ini selanjutnya jika gagal pada awalnya sampai mereka diselesaikan atau tanpa batas waktu.

Pemeriksaan yang terlintas dalam pikiran bahwa kami dapat menjalankan meliputi:

• Komentar dokumentasi tingkat atas
• Tidak ada bidang README di Cargo.toml jika ada
• Komentar untuk semua fungsi publik

Saya sebenarnya tidak melihat banyak manfaat dalam menghabiskan banyak upaya untuk mencegah penerbitan peti dengan dokumen/readme default ... jika Anda bermaksud agar orang lain mengkonsumsi peti Anda, Anda akan mengubahnya, dan jika Anda belum siap atau pernah berniat orang lain ingin menggunakan peti Anda, kemungkinan besar mereka tidak akan siap jika Anda menerbitkan dengan dokumen default :)

Saya awalnya berbagi sentimen @ carols10cents , tetapi ketika saya memikirkannya lebih lanjut, saya menyadari bahwa setidaknya di node, saya cukup sering dengan cepat membuat paket template dan segera mempublikasikannya.

Saya pikir itu masih merupakan hal yang diinginkan untuk dapat dilakukan, dan saya benci cara Rubygems memaksa saya untuk memperbaiki banyak templat TODO yang tidak berguna dalam spesifikasi permata default, jadi saya berpikir mungkin jalan tengah adalah mendeteksi templat dan tidak merender isinya?

Dengan begitu, orang yang menerbitkan template tidak lebih buruk dari hari ini, tetapi kami juga memberikan titik awal yang bagus untuk dokumentasi.

@matklad : Saya dengan hormat mengingatkan semua orang bahwa README.md bukan satu-satunya nama file README yang mungkin, ada juga bahasa markup lainnya. Hanya untuk memastikan ini jelas ...

Saya mendukung cargo publish memancarkan peringatan (minimal) jika beberapa masalah QA ditemukan. Satu lagi masalah penting IMO daripada README adalah kurangnya status pemeliharaan eksplisit. di Cargo.toml .

# Maintenance: `status` is required Available options are `actively-developed`,
# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
# and `deprecated`.
maintenance = { status = "..." }

Ini membantu pemrogram menyaring banyak peti saat menjelajahi crates.io tergantung pada kebutuhan mereka. Setelah itu, dokumen API relevan, hanya jika tidak apa-apa README akan diperiksa berikutnya, IMO.

@sanmai-NL Kita bisa default ke README.md bahkan saat masih mendukung opsi lain untuk README. Apakah ada gaya markup lain yang menurut Anda akan menjadi default yang lebih baik?

Saya mendukung penerbitan kargo yang mengeluarkan peringatan (minimal) jika beberapa masalah QA ditemukan.

Saya biasanya menentang peringatan tanpa gigi, karena pengalaman saya di ekosistem lain adalah bahwa orang biasanya mengabaikannya, dan mereka hanya menambah tingkat kebisingan dari pengalaman umum. Ketika tingkat kebisingan semakin buruk, ada "inflasi kebisingan" ketika orang mencoba membuat "hal-hal yang sangat penting" cukup keras untuk dilihat, yang menciptakan lingkaran setan.

Jika kita ingin menghentikan orang dari menerbitkan peti dengan masalah QA, kita harus menghentikan mereka. Jika kita ingin melakukan ini, kita mungkin juga harus memikirkan untuk mengotomatisasi proses perbaikan masalah QA.

@wycats :
Sejauh ini saya menggunakan Asciidoctor untuk dokumentasi perangkat lunak. Maksud saya bukanlah bahwa preferensi pribadi saya harus menjadi default, tetapi bahasa markup 'default' dan template README dengan nama file yang sesuai mungkin salah arah. Jika kita menempuh jalan ini, kita tidak hanya akan memaksakan keberadaan README (di tempat tertentu dalam struktur proyek), tetapi bahkan sintaks tertentu untuk itu. Itu tidak dramatis tetapi tidak boleh dilakukan dengan santai.

Setuju tentang peringatan vs. kesalahan, tetapi saya menemukan banyak orang menentang keras untuk dipaksa mematuhi praktik terbaik.

@sanmai-NL

Saya tidak akan keberatan dengan upaya lanjutan untuk memungkinkan konfigurasi template "peti baru", yang memungkinkan orang untuk mengonfigurasi jenis default ini.

Yang mengatakan, saya tidak berpikir default ke README.md adalah hal yang sama dengan memaksakan satu. Itu hanya mengakui bahwa cukup banyak orang, secara agregat, menginginkan README di root repositori mereka dan ingin diformat dalam penurunan harga untuk membenarkan pengurangan overhead bagi pengguna tersebut. Biayanya adalah pengguna lain harus mengganti nama file, dan saya pribadi percaya bahwa keseimbangan biaya mendukung kelancaran jalur untuk penggunaan dominan.

(tetapi sekali lagi, saya sangat mendukung untuk membuat Cargo lebih dapat dikonfigurasi untuk orang-orang yang memiliki alur kerja non-dominan, dan secara pribadi saya termotivasi untuk mendukung pekerjaan semacam itu).

Saya tidak akan keberatan dengan upaya lanjutan untuk memungkinkan konfigurasi template "peti baru", yang memungkinkan orang untuk mengonfigurasi jenis default ini.

Ada upaya untuk melakukan ini yang dikembalikan sambil menunggu RFC:

• https://github.com/rust-lang/cargo/issues/396
• https://github.com/rust-lang/cargo/pull/3004
• https://github.com/rust-lang/cargo/pull/3878

Kami membahas ini selama pertemuan kargo hari ini dan sampai pada keputusan berikut:

Untuk memberikan dorongan halus kepada pengguna Kargo baru terhadap praktik terbaik untuk peti yang baik, kita harus membuat beberapa dokumentasi placeholder yang terdiri dari:

Untuk peti biner:

• README.md yang berisi teks TODO: add a description of this crate's purpose dan merekomendasikan menggunakan cargo install [cratename] untuk menginstal peti

Untuk peti perpustakaan:

• File README.md yang berisi teks TODO: add a description of this crate's purpose dan merekomendasikan menambahkan peti ke Cargo.toml seseorang untuk menggunakan peti sebagai ketergantungan
• Dokumentasi tingkat modul di src/lib.rs yang berisi teks TODO: add a description of this crate's purpose

Untuk peti ruang kerja (ketika Anda menjalankan cargo new dalam ruang kerja`):

• Jangan buat README.md
• Dokumentasi tingkat modul di src/lib.rs yang berisi teks TODO: add a description of this crate's purpose

Tidak ada peringatan baru yang harus dikeluarkan pada publikasi; dokumentasi kosong atau default di crates.io akan menjadi tanda bahwa peti belum siap digunakan. Penulis peti yang memang bermaksud agar orang menggunakan peti mereka akan menyesuaikan dokumentasi ini.

Perilaku ini dimaksudkan untuk membantu pengguna kargo baru mempelajari praktik terbaik dan mulai menggunakannya dengan sedikit gesekan. Pengguna kargo yang berpengalaman akan tahu cara menghapus/mengganti nama/memodifikasi file-file ini agar sesuai dengan tujuannya.

Kami dapat mengulangi perilaku default ini saat praktik terbaik berkembang, dan RFC untuk fitur template (yang merupakan perubahan yang jauh lebih besar) diterima. Demikian pula, mode interaktif akan menjadi perubahan yang lebih besar, dan membuat mode interaktif akan lebih baik jika diinformasikan oleh pengalaman yang dimiliki orang dengan tambahan kecil untuk fitur ini.

@carols10cents :
Maaf, saya tidak terbiasa dengan proses pengambilan keputusan di sini. Apa kewenangan keputusan yang dibuat dalam rapat ini?

README.md yang berisi teks

Ini tidak mengatasi kekhawatiran saya tentang default ke satu bahasa markup di atas yang lain. Hanya jika README.md tersebut dianggap/ditegaskan berada di CommonMark, maka itu akan dapat diterima (bagi saya) untuk default pada ekstensi nama file md , mengingat itu adalah bahasa markup yang sama seperti yang digunakan dengan rustdoc .

Tidak ada peringatan baru yang harus dikeluarkan pada publikasi; dokumentasi kosong atau default di crates.io akan menjadi tanda bahwa peti belum siap digunakan. Penulis peti yang memang bermaksud agar orang menggunakan peti mereka akan menyesuaikan dokumentasi ini.

Apa alasan di balik tidak memberi peringatan untuk ini? Mengapa dorongan harus halus? Mengapa seseorang harus _diizinkan_ untuk menerbitkan peti di crates.io jika belum siap digunakan? IMO, tidak perlu peti semua orang dibuang di crates.io, itu berbahaya sebenarnya karena kelangkaan nama, peti yang bagus dapat ditemukan, dan kesan kualitas ekosistem yang tidak terawat/peti yang belum matang dibiarkan. Ini adalah keputusan kebijakan yang sangat penting untuk dibuat.

Demikian pula, mode interaktif akan menjadi perubahan yang lebih besar, dan membuat mode interaktif akan lebih baik jika diinformasikan oleh pengalaman yang dimiliki orang dengan tambahan kecil untuk fitur ini.

Mode interaktif ortogonal untuk membuat dokumentasi fitur QA. Ada sangat sedikit hubungan IMO, khususnya. ketika README stub sudah dibuat secara otomatis secara default. Hanya saja, mungkin, fitur yang lebih penting untuk dikerjakan.

Maaf, saya tidak terbiasa dengan proses pengambilan keputusan di sini. Apa kewenangan keputusan yang dibuat dalam rapat ini?

Tim kargo memiliki wewenang untuk membuat keputusan seperti ini yang menambahkan fitur baru kecil, sebanyak tim libs dapat memutuskan untuk menambahkan API baru.

Ini tidak mengatasi kekhawatiran saya tentang default ke satu bahasa markup di atas yang lain. Hanya jika README.md tersebut dianggap/diberlakukan di CommonMark, maka dapat diterima (bagi saya) untuk default pada ekstensi nama file md, mengingat itu bahasa markup yang sama seperti yang digunakan dengan rustdoc.

Saya tidak yakin apa yang Anda maksud dengan "dipaksa berada di CommonMark". Penurunan harga di README.md akan ditafsirkan sebagai HTML oleh crates.io, GitHub, docs.rs, dan mungkin alat lainnya. Kami tidak memiliki kendali atas bagaimana GitHub menafsirkan penurunan harga. Crates.io menggunakan comrak , parser dan formatter GitHub Flavoured Markdown 100% yang kompatibel dengan CommonMark, untuk merender README. Saya tidak terbiasa dengan apa yang digunakan docs.rs. Jika seseorang memberikan penurunan harga yang tidak valid di README.md mereka, itu tidak akan ditampilkan dengan benar di crates.io-- Saya pikir hanya itu "penegakan" yang bisa kita lakukan di sini.

Apa alasan di balik tidak memberi peringatan untuk ini?

Peringatan kelelahan, lihat komentar wycat .

Mengapa ada orang yang diizinkan untuk menerbitkan peti di crates.io jika belum siap digunakan? IMO, tidak perlu peti semua orang dibuang di crates.io, itu berbahaya sebenarnya karena kelangkaan nama, peti yang bagus dapat ditemukan, dan kesan kualitas ekosistem yang tidak terawat/peti yang belum matang dibiarkan. Ini adalah keputusan kebijakan yang sangat penting untuk dibuat.

Dan ini adalah keputusan kebijakan yang kami buat sejak lama ketika crates.io dimulai: siapa pun dapat memublikasikan apa pun dengan kualitas apa pun ke crates.io. Alih-alih memiliki proses peninjauan/pemeriksaan, yang tidak dapat dilakukan oleh siapa pun dan yang menimbulkan hambatan untuk berkontribusi pada ekosistem, kami telah memilih untuk mengizinkan penerbitan apa pun dan berupaya memunculkan cara yang lebih baik untuk membantu orang menemukan peti berkualitas baik .

Mode interaktif ortogonal untuk membuat dokumentasi fitur QA.

Saya setuju, itulah yang saya coba katakan. Saya hanya ingin membahasnya karena diangkat di utas ini.

@carols10cents :

Tim kargo memiliki wewenang untuk membuat keputusan seperti ini yang menambahkan fitur baru kecil, sebanyak tim libs dapat memutuskan untuk menambahkan API baru.

Bisakah Anda memberi saya tautan tempat aturan didokumentasikan?

Saya tidak yakin apa yang Anda maksud dengan "dipaksa berada di CommonMark". Penurunan harga di README.md akan ditafsirkan sebagai HTML oleh crates.io, GitHub, docs.rs, dan mungkin alat lainnya. Kami tidak memiliki kendali atas bagaimana GitHub menafsirkan penurunan harga. Crates.io menggunakan comrak, parser dan formatter GitHub Flavoured Markdown 100% yang kompatibel dengan CommonMark, untuk merender README. Saya tidak terbiasa dengan apa yang digunakan docs.rs. Jika seseorang memberikan penurunan harga yang tidak valid di README.md mereka, itu tidak akan ditampilkan dengan benar di crates.io-- Saya pikir hanya itu "penegakan" yang bisa kita lakukan di sini.

Penegakan hanya satu kata dalam komentar saya, saya berasumsi Anda memahami sisanya . Jika antarmuka web crates.io tidak menerima non-CommonMark, itu cukup adil.

Peringatan kelelahan, lihat komentar wycat.

Bukan itu yang dikatakan @wycats . Dia lebih suka melakukan kesalahan ketika masalah QA ditemukan, sehubungan dengan kurangnya masalah dokumentasi. Saya juga lebih menyukai kesalahan keras daripada peringatan, itulah cara terbaik untuk mengakhiri semua kelelahan peringatan.

Dan ini adalah keputusan kebijakan yang kami buat sejak lama ketika crates.io dimulai: siapa pun dapat memublikasikan apa pun dengan kualitas apa pun ke crates.io. Alih-alih memiliki proses peninjauan/pemeriksaan, yang tidak seorang pun punya waktu untuk melakukannya dan yang menjadi penghalang untuk berkontribusi pada ekosistem, kami telah memilih untuk mengizinkan penerbitan apa pun dan berupaya memunculkan cara yang lebih baik untuk membantu orang menemukan peti berkualitas baik.

Bisakah Anda mengarahkan saya ke dokumentasi aturan itu?

Kau menulis:

dokumentasi kosong atau default di crates.io akan menjadi tanda bahwa peti belum siap digunakan. Penulis peti yang memang bermaksud agar orang menggunakan peti mereka akan menyesuaikan dokumentasi ini.

Dengan cara apa peti-peti menolak yang sebenarnya tidak siap digunakan oleh orang lain membuat 'penghalang untuk berkontribusi pada ekosistem'? Jika Anda tidak menulis dokumentasi atau gagal memenuhi kriteria QA dasar lainnya, seperti yang terdeteksi secara otomatis, lalu dengan cara apa Anda berkontribusi dengan menerbitkan hal seperti itu di crates.io (sebagai lawan menyimpannya lokal, menggunakan registri lain atau hanya meletakkan itu di platform berbagi kode)? Saya tidak pernah mengusulkan tinjauan manual/pemeriksaan peti.

Bukan itu yang dikatakan @wycats . Dia lebih suka melakukan kesalahan ketika masalah QA ditemukan, sehubungan dengan kurangnya masalah dokumentasi. Saya juga lebih menyukai kesalahan keras daripada peringatan, itulah cara terbaik untuk mengakhiri semua kelelahan peringatan.

Preferensi saya adalah untuk kesalahan ketika masalah yang ditemukan cenderung bersifat universal (atau mendekatinya). Dalam kasus lain, saya lebih suka diam daripada peringatan. Kami telah menemukan cara untuk membengkokkan kurva ini, seperti menunda kesalahan tertentu ke waktu publikasi, sehingga kami dapat membatasi kriteria universalitas menjadi "peti yang diterbitkan". Saya tidak akan menentang menemukan cara untuk memungkinkan orang memilih petunjuk bermanfaat tentang praktik yang baik melalui alat yang umum digunakan seperti Clippy.

Tetapi saya tidak mendukung memberi orang kesalahan keras dengan instruksi tentang cara membungkam mereka "setelah Anda mengetahui untuk apa kesalahan itu" atau saya mendukung menambahkan kebisingan melalui peringatan.

Saya tidak berpikir semua itu bertentangan dengan apa yang Anda katakan; Aku hanya ingin menjadi jelas.

Dengan cara apa peti-peti menolak yang sebenarnya tidak siap digunakan oleh orang lain membuat 'penghalang untuk berkontribusi pada ekosistem'? Jika Anda tidak menulis dokumentasi atau gagal memenuhi kriteria QA dasar lainnya, seperti yang terdeteksi secara otomatis, lalu dengan cara apa Anda berkontribusi dengan menerbitkan hal seperti itu di crates.io (sebagai lawan menyimpannya lokal, menggunakan registri lain atau hanya meletakkan itu di platform berbagi kode)? Saya tidak pernah mengusulkan tinjauan manual/pemeriksaan peti.

Masalah dengan pertanyaan ini adalah bahwa ia mengasumsikan bahwa "siap digunakan oleh orang lain" memiliki definisi yang disepakati secara universal dan itu pasti berlaku di sini. Kami sebenarnya setuju dengan sentimen umum Anda: misalnya kami melarang penggunaan dependensi * di peti yang diterbitkan serta dependensi ke peti di luar registri crates.io, karena kami telah memutuskan bahwa keduanya adalah praktik buruk yang cukup universal dan berbahaya untuk membenarkan blok keras.

Dalam hal ini, tim Kargo belum percaya bahwa mencegah pengguna menerbitkan dan menggunakan peti yang tidak memiliki dokumentasi cukup berbahaya untuk membenarkan pemblokiran.

Secara umum, saya juga percaya bahwa kemampuan kita untuk menegakkan kontrol kualitas melalui kesalahan keras sangat terbatas. Misalnya, jika kami bersikeras bahwa setiap permata yang diterbitkan berisi README yang unik, itu adalah cara bagi kami untuk mendorong orang ke arah yang benar. Tapi dorongan lebih baik cukup, atau orang akan menggunakan solusi pertama yang tersedia untuk membuat kesalahan hilang. (Stack Overflow penuh dengan orang yang mencari cara untuk menangani pesan kesalahan yang bermaksud baik semacam ini, dan juga penuh dengan orang yang menjelaskan peretasan cepat untuk mematikan kesalahan.)

Masalah dengan alat yang dalam praktiknya memaksa orang ke dalam mantra dan pola peretasan untuk memenuhi pesan kesalahan yang bermaksud baik tetapi terlalu luas adalah bahwa model mental untuk menggunakan alat tersebut diisi dengan peretasan ini ("rm -r berbahaya jadi mari kita beri orang peringatan" ... "semua orang menghafal rm -rf" ... "ya ampun, kita perlu peringatan untuk menghentikan orang agar tidak sengaja rm -rf'ing").

Semua ini tidak dimaksudkan untuk mengatakan bahwa ini bukan contoh di mana dorongan yang bermanfaat akan berguna. Ini hanya untuk mengatakan bahwa argumen yang kuat tentang membuat README wajib akan mempertimbangkan besarnya risiko ekosistem di seluruh paket yang tidak memiliki README.

Saya pikir poin Carol tentang peti yang diterbitkan tanpa dokumentasi adalah bahwa risikonya dikurangi secara signifikan oleh fakta bahwa sangat mudah untuk mengidentifikasi paket yang berkualitas rendah dengan cara ini. Kami bahkan dapat menandai paket di crates.io dengan karakteristik ini, tidak memprioritaskannya dalam hasil pencarian, dan memfilternya. Namun sebelum kami memperkenalkan kondisi kesalahan keras yang dimaksudkan untuk menegakkan standar kualitas, kami harus benar-benar yakin bahwa itu sepadan.

Bisakah Anda mengarahkan saya ke dokumentasi aturan itu?

Aturan tata kelola Rust adalah subjek dari RFC #1068 . RFC itu mendelegasikan tanggung jawab kepada subtim untuk memutuskan jenis masalah mana yang memerlukan RFC.

Dalam beberapa hal, keputusan tentang apakah suatu masalah cukup "besar" untuk memerlukan RFC adalah masalah selera, dan akan sangat sulit untuk menuliskan pedoman yang cukup untuk secara otomatis mengkategorikan keputusan sebagai "membutuhkan RFC" atau "tidak membutuhkan RFC". Tidaklah buruk untuk menuliskan semacam heuristik, selama itu tidak menjadi vektor untuk mengubah percakapan teknis menjadi prosedural/legalistik.

@wycats :
Terima kasih, kedua balasan Anda jelas bagi saya dan membahas poin yang saya angkat dalam pandangan saya sendiri. Masih banyak yang bisa dikatakan, tetapi setidaknya, pemikiran yang cukup telah diberikan untuk masalah-masalah tersebut dan masih ada sedikit kesepakatan dan perbedaan pendapat dalam berbagai aspek.

Juga, tampaknya saya salah memahami posisi Anda pada peringatan/kesalahan, terima kasih telah mengklarifikasi.

Saya masih ingin menunjukkan satu hal. @carols10cents , Anda memperkenalkan kualifikasi 'belum siap digunakan', namun @wycats sekarang mengakui tidak ada definisi yang jelas tentang gagasan 'siap digunakan'. Saya pribadi percaya mudah untuk membuat daftar beberapa aturan objektif cepat tentang apa yang pasti mengeja _insufficient_ quality wrt. mendapatkan publikasi dalam registri komponen perangkat lunak resmi. Proyek implementasi bahasa pemrograman besar lainnya tidak ragu-ragu untuk menetapkan aturan di sini (misalnya, CRAN untuk R ). Aturan-aturan ini sebagian besar tidak menghadirkan penghalang kontribusi untuk programmer, karena mereka sebagian besar dapat diperiksa secara otomatis dengan devtools::check() . Sebaliknya, mereka menginspirasi kontributor untuk mempelajari praktik terbaik, dan pada akhirnya membuat mereka bahagia.

Meskipun masalah GitHub khusus ini relatif kecil (meskipun cakupannya tidak jelas sejak awal), cara keputusan dibuat dalam model tata kelola Anda dan, khususnya, dimotivasi secara publik, agak mengkhawatirkan saya. Sebagai pengguna industri Rust, tampaknya keramahan terhadap pemrogram hobi mengesampingkan jaminan kualitas ekosistem OSS, dalam keputusan seperti ini. Dimensi ini tidak bertentangan, tetapi tergantung pada bagaimana Anda mendekati keduanya, saya pikir. Semoga orang-orang dengan kepentingan industri (non-Mozilla) akan memiliki suara yang lebih besar di masa depan.

Saya masih ingin menunjukkan satu hal. @carols10cents , Anda memperkenalkan kualifikasi 'belum siap digunakan', namun @wycats sekarang mengakui tidak ada definisi yang jelas tentang gagasan 'siap digunakan'. Saya pribadi percaya mudah untuk membuat daftar beberapa aturan objektif cepat tentang apa yang pasti mengeja wrt kualitas yang tidak memadai. mendapatkan publikasi dalam registri komponen perangkat lunak resmi.

Untuk apa nilainya, saya pikir kami memiliki definisi seperti itu sekarang, dikodekan (seperti yang Anda sarankan) melalui kesalahan waktu publikasi. Mereka termasuk pembatasan penggunaan * dan dependensi di luar crates.io. Saya bisa membayangkan menambahkan lebih banyak aturan ke set itu, tetapi ketika saya mencoba menguraikannya, standarnya tinggi

Sebagai pengguna industri Rust, tampaknya keramahan terhadap pemrogram hobi mengesampingkan jaminan kualitas ekosistem OSS, dalam keputusan seperti ini. Dimensi ini tidak bertentangan, tetapi tergantung pada bagaimana Anda mendekati keduanya, saya pikir. Semoga orang-orang dengan kepentingan industri (non-Mozilla) akan memiliki suara yang lebih besar di masa depan.

Saya di tim Cargo, tidak bekerja untuk Mozilla, dan minat utama saya, seperti Anda, adalah penggunaan Rust dalam produksi. Kami bahkan mengiklankan fakta bahwa kami menggunakan Rust sebagai fitur penting dalam produk kami:

Saya tidak setuju bahwa mungkin sulit bagi pengguna produksi untuk memberikan masukan yang baik ke dalam proses, karena menjadi pengguna produksi menurut definisi berarti Anda tidak punya waktu untuk meninjau masalah dan merespons sebanyak yang Anda sebut "hobi pengguna".

Saya juga percaya bahwa prosesnya, untuk alasan ini, agak terlalu condong ke orang-orang yang punya waktu untuk menulis banyak komentar tentang masalah, dan itu adalah sesuatu yang menurut saya ada banyak keinginan untuk diperbaiki. Saya akan sangat senang untuk berbicara dengan Anda (secara publik atau pribadi) tentang masalah ini dan cara kami dapat meningkatkan proses kami untuk mengatasinya.

(Saya juga tidak percaya bahwa pengguna produksi dilayani dengan baik dengan mengubah banyak keputusan kecil menjadi RFC, karena proses RFC saat ini didominasi oleh apa yang Anda sebut "pengguna hobi", hanya karena mereka memiliki lebih banyak waktu untuk merespons berkali-kali per hari ke utas RFC)

Karena tidak ada aktivitas apa pun di sini selama lebih dari 6 bulan, saya telah menandai ini sebagai basi dan jika tidak ada aktivitas lebih lanjut yang terjadi selama 7 hari, saya akan menutupnya.

Saya bot jadi ini mungkin salah! Jika masalah ini harus tetap terbuka, dapatkah seseorang (penulis, anggota tim, atau pihak yang berkepentingan) memberi komentar tentang hal itu?

Tim akan sangat berterima kasih jika komentar tersebut menyertakan detail seperti:

• Apakah ini masih relevan?
• Jika demikian, apa yang menghalanginya?
• Apakah diketahui apa yang bisa dilakukan untuk membantu memajukan ini?

Terima kasih telah berkontribusi!

(Tim kargo saat ini sedang mengevaluasi penggunaan bot Stale, dan menggunakan #6035 sebagai masalah pelacakan untuk mengumpulkan umpan balik.)

Jika Anda membaca komentar ini dari masa depan yang jauh, jangan takut jika ini ditutup secara otomatis. Jika Anda yakin ini masih menjadi masalah, silakan tinggalkan komentar dan anggota tim dapat membuka kembali masalah ini. Membuka edisi baru juga dapat diterima!

Saya masih berpikir ini layak dilakukan, tetapi tampaknya telah terperosok dalam diskusi tangensial dan kemudian percakapan itu berhenti.

Saya pikir ini diblokir pada ukuran RFC #5151 yang lebih besar tentang templat kargo secara umum, yang menurut saya ada dalam agenda tetapi didorong untuk prioritas edisi lain.

@coder543 : diskusi tangensial, atau lebih tepatnya diskusi kritis apakah menambahkan fitur ini adalah yang benar-benar kita butuhkan.

Jika keputusan di https://github.com/rust-lang/rfcs/pull/2549#issuecomment -424868609 ditegakkan oleh tim maka ini juga harus ditutup.

@ Eh2406 Saya tidak mengerti mengapa. Editorconfig adalah teknologi khusus. README adalah hal yang agak mendasar. Karena README digunakan sebagai bagian dari crates.io, ini bisa dibilang merupakan file minimal yang diperlukan untuk membuat proyek Rust baru.

Belum lagi rustfmt sudah mengisi peran Editorconfig di dunia Rust. Masalah ini juga sudah diblokir di template, jadi mungkin saja menjadi bagian dari template.

Ada argumen (misalnya, seperti yang disajikan oleh @withoutboats di https://github.com/rust-lang/cargo/issues/2039#issuecomment-423517959) bahwa segala sesuatunya seharusnya, hmm, kurang "didikte" oleh crates.io .

Imo, argumen yang dibuat di https://github.com/rust-lang/rfcs/pull/2549 juga berlaku di sini, kargo harus tetap ringan dan hanya membangun sistem dan hal-hal terkait manajemen ketergantungan. Apa pun yang ekstra, seperti README, Editorconfig, CONTRIBUTING, dll. harus menjadi pilihan yang ergonomis dengan template kargo. Yang populer adalah template OSS, yang memiliki 3 file yang disebutkan di atas ditambah LISENSI.

Jika kita mulai membuat pengecualian untuk hal-hal seperti README, di mana kita menarik garis? Juga cerita template kargo mungkin kurang jelas, mengajarkan bahwa untuk apa pun yang tidak terkait dengan membangun perangkat lunak seperti file README Anda dapat menggunakan template kargo, itu sederhana. Sayangnya sudah ada pengecualian untuk ini, seperti vcs, jangan memperburuk situasi.

@steveklabnik Lihat https://github.com/ashleygwilliams/cargo-generate dan https://github.com/livioribeiro/cargo-readme. Sekarang solusi untuk masalah yang dibahas di sini telah muncul dari ekosistem OSS, saya pikir lebih baik untuk menutup masalah ini, karena mengusulkan pekerjaan baru, dan alih-alih fokus pada peningkatan dan/atau mengintegrasikannya ke dalam Cargo.

@steveklabnik ada pembaruan tentang ini? jika perlu kami dapat menandai ini sebagai e-mudah dan meminta beberapa sukarelawan untuk melakukannya :D

Saya tidak tahu apa-apa, ayo lakukan!

Pada 23 Desember 2019, pukul 12:47, Dylan DPC [email protected] menulis:

Lalai
@steveklabnik ada pembaruan tentang ini? jika perlu kami dapat menandai ini sebagai e-mudah dan meminta beberapa sukarelawan untuk melakukannya :D

—
Anda menerima ini karena Anda disebutkan.
Balas email ini secara langsung, lihat di GitHub, atau berhenti berlangganan.

@steveklabnik Saya tidak memiliki izin pada repo ini sehingga Anda (atau orang lain) harus melakukannya :)

Hai @Dylan-DPC dan @steveklabnik. Saya pengguna Cargo dan pemula dalam proyek open source. Saya ingin mencoba ini jika Anda dapat memberi saya beberapa panduan tentang rencana implementasi. Setelah membaca komentar di sini, sepertinya ada beberapa pendapat tentang pendekatan apa yang harus diambil.

Saya tidak berada di tim kargo, jadi saya tidak dapat benar-benar melakukan panggilan itu.

Berdasarkan beberapa diskusi dan panduan di #8029, saya akan mulai mengerjakan RFC.

Saya memposting Pra-RFC di internal. Berikut tautan jika ada yang ingin berpartisipasi dalam diskusi: