Haruskah dokumentasi yang dihasilkan disimpan dalam repositori Git?

49

Ketika Anda menggunakan alat-alat seperti jsdocs , itu menghasilkan file HTML statis dan gayanya di basis kode Anda berdasarkan komentar dalam kode Anda.

Haruskah file-file ini diperiksa ke dalam repositori Git atau haruskah mereka diabaikan dengan .gitignore?

git documentation

— pengumpulan sampah
sumber

4

Mungkin ada argumen untuk menyimpannya di repositori GitHub karena Anda dapat menerbitkan halaman menggunakan HTML statis . Meskipun kemudian serangkaian argumen yang terpisah sepenuhnya muncul tentang bagaimana Anda memastikan mereka terbaru dll ...

— Boris the Spider

21

Jika file dibuat, maka menurut definisi mereka bukan sumber .

— chrylis -pada mogok-

3

Anda mempublikasikan apa yang ingin Anda publikasikan. Terutama di GitHub. Jika Anda ingin semua orang melihat PDF atau gambar yang dihasilkan, Anda harus memasukkannya daripada mengharapkan semua orang untuk menginstal LaTeX dan mengkompilasinya sendiri. Sebagai contoh, repositori ini tidak akan sangat baik jika tidak termasuk gambar yang dihasilkan, hanya file proyek ...

— Tanggal

5

duplikat agak mencolok dari Haruskah dokumentasi yang dihasilkan masuk dalam riwayat kontrol versi?

— nyamuk

7

Sebagai konsumen perpustakaan pihak ketiga, dari 10 kali saya melihat perpustakaan tanpa dokumentasi online (baik dalam subfolder dari repositori, atau ditautkan dari readme), saya akan mengklik dan melewati perpustakaan itu, semuanya 10 kali . Saya tidak akan main-main dengan Doxygen selama setengah jam hanya untuk melihat apakah perpustakaan memenuhi kebutuhan saya.

— Alexander

131

Tidak ada kebutuhan spesifik apa pun, file apa pun yang dapat dibuat, dibuat ulang, dibuat, atau dihasilkan dari alat bantu menggunakan file lain yang diperiksa ke dalam kontrol versi tidak boleh diperiksa. Ketika file diperlukan, file dapat dibuat (kembali) dari yang lain sumber (dan biasanya sebagai beberapa aspek dari proses pembangunan).

Jadi file-file itu harus diabaikan dengan .gitignore.

— 1201ProgramAlarm
sumber

4

Tetapi ini mungkin tergantung pada versi alat build atau bahkan ketersediaan alat build (misalnya untuk menghasilkan beberapa file beberapa versi lama alat build diperlukan). Bagaimana Anda mengatasinya? Bisakah Anda mengatasinya dalam jawaban Anda?

— Peter Mortensen

27

@PeterMortensen Jika Anda memerlukan artefak yang dibangun dengan versi khusus alat buld, Anda membangunnya dengan versi alat bangun yang Anda butuhkan. Kebutuhan semacam itu adalah a) ditemukan sendiri, dalam hal ini Anda sendirian; b) didokumentasikan dalam README ("Anda akan membutuhkan dua memiliki 2 versi spesifik yang diinstal oksigen ..."); c) ditangani oleh skrip build (mereka memeriksa versi build tools yang tersedia dan bertindak dengan tepat). Bagaimanapun, kontrol sumber adalah untuk sumber, bukan untuk membangun artefak.

— Joker_vD

2

Saya pikir jawaban ini hanya layak jika server penyebaran terus menerus membangun dan menerbitkan dokumentasi dengan cara yang mudah diakses. Kalau tidak, ada nilai besar dalam "caching" dokumen dalam repo, untuk meningkatkan aksesibilitas. Tidak ada pengguna yang harus muck dengan skrip build Anda hanya untuk melihat dokumentasi perangkat lunak Anda.

— Alexander

4

@Alexander Apakah Anda juga memasukkan biner yang dibangun ke dalam repo? Dokumentasi dibuat. Anda mengambil dokumentasi yang dibuat dan membuatnya dapat diakses di suatu tempat.

— 1201ProgramAlarm

5

@ 1201ProgramAlarm "Apakah Anda juga memasukkan biner binaan ke dalam repo?" Tidak, karena biner yang dibangun memiliki nilai muka yang rendah untuk orang yang menelusuri GitHub, dibandingkan dengan dokumentasi. "Anda mengambil dokumentasi yang dibuat dan membuatnya dapat diakses di suatu tempat." Selama itu dihosting secara publik, terhubung dengan jelas, maka itu bagus. Ini mungkin kasus terbaik.

— Alexander

23

Aturan saya adalah ketika saya mengkloning repositori dan menekan tombol "build", maka, setelah beberapa saat, semuanya dibangun. Untuk mencapai ini untuk dokumentasi yang Anda hasilkan, Anda memiliki dua pilihan: seseorang bertanggung jawab untuk membuat dokumen ini dan memasukkannya ke git, atau Anda mendokumentasikan dengan tepat perangkat lunak apa yang saya butuhkan pada mesin pengembangan saya, dan Anda memastikan bahwa menekan tombol "build" Tombol membangun semua dokumentasi di mesin saya.

Dalam kasus dokumentasi yang dihasilkan, di mana setiap perubahan yang saya buat pada file header harus mengubah dokumentasi, melakukan ini pada setiap mesin pengembang lebih baik, karena saya ingin dokumentasi yang benar setiap saat, tidak hanya ketika seseorang telah memperbaruinya. Ada situasi lain di mana menghasilkan sesuatu mungkin memakan waktu, rumit, memerlukan perangkat lunak yang Anda hanya memiliki satu lisensi, dll. Dalam hal itu, memberi satu orang tanggung jawab untuk memasukkan sesuatu ke git lebih baik.

@Curt Simpson: Memiliki semua persyaratan perangkat lunak didokumentasikan jauh lebih baik daripada yang saya lihat di banyak tempat.

— gnasher729
sumber

7

Jangan mendokumentasikan perangkat lunak apa yang dibutuhkan seseorang untuk membangun (atau setidaknya tidak hanya mendokumentasikan): buat skrip pembuatan untuk memberi tahu pengguna apa yang hilang atau bahkan instal sendiri jika itu wajar. Di sebagian besar repo saya, pengembang setengah jalan yang kompeten dapat menjalankan ./Testdan mendapatkan build atau mendapatkan informasi yang baik tentang apa yang perlu dia lakukan untuk mendapatkan build.

— Curt J. Sampson

5

Saya tidak benar-benar setuju bahwa menempatkan dokumentasi yang dihasilkan ke git bisa bagus jika Anda tentukan. Itulah alasan kami memiliki artefak dan arsip.

— Sulthan

Itu adalah aturanmu dan itu aturan yang bagus dan aku menyukainya. Tetapi yang lain bisa membuat aturan sendiri.

— emory

Saya pikir maksud Anda "jalankan perintah build," karena tidak akan ada tombol build pada mesin Anda. ... Kecuali Anda mengharapkan keseluruhan build terintegrasi dengan IDE, yang sepenuhnya tidak masuk akal.

— jpmc26

@ jpmc26 Saya merasa sangat masuk akal untuk memiliki seluruh build terintegrasi dalam IDE. Tombol build di mesin saya adalah Command-B.

— gnasher729

14

File-file ini tidak boleh diperiksa karena data untuk menghasilkannya sudah ada. Anda tidak ingin menyimpan data dua kali (KERING).

Jika Anda memiliki sistem CI, Anda mungkin bisa membuatnya yang membangun dokumen dan menyimpannya untuk itu membangun / mempublikasikannya ke server web.

— Tvde1
sumber

4

Satu keuntungan dari memilikinya dalam beberapa repositori (baik yang sama atau yang berbeda, lebih disukai secara otomatis) adalah bahwa Anda dapat melihat semua perubahan pada dokumentasi. Kadang-kadang diff itu lebih mudah dibaca daripada diff ke kode sumber (khususnya jika Anda hanya peduli dengan perubahan spesifikasi, bukan implementasi satu).

Tetapi dalam kebanyakan kasus memiliki mereka dalam kontrol sumber tidak diperlukan, seperti yang dijelaskan oleh jawaban lainnya.

— Paŭlo Ebermann
sumber

1

Itu cukup banyak membutuhkan kait pra-komit di masing-masing dan setiap repo yang digunakan untuk membuat komit. Karena jika proses pembuatan dokumentasi tidak sepenuhnya otomatis, Anda akan mendapatkan komitmen yang memiliki dokumentasi tidak sinkron dengan kode. Dan komitmen yang rusak tersebut akan lebih merusak pemahaman daripada dokumentasi yang tidak dikomit.

— cmaster

1

Ini tidak harus pada tahap komit. Ini bisa dengan mudah menjadi pekerjaan hilir / CI / Jenkins untuk menerbitkannya setiap kali mereka dianggap layak untuk disimpan. Ini mungkin merupakan komitmen masing-masing, tetapi keputusan harus dipisahkan dengan tidak adanya alasan yang baik. Atau setidaknya begitulah cara saya melihatnya.

— Sendiri

3

Diabaikan Anda ingin agar pengguna repo tetap dapat membangunnya kembali, dan ini menghilangkan kerumitan untuk memastikan dokumen selalu tersinkron. Tidak ada alasan untuk tidak memiliki artefak yang dibangun yang dibundel di satu tempat jika Anda ingin memiliki semuanya di satu tempat dan tidak harus membangun apa pun. Namun repo sumber tidak benar-benar tempat yang baik untuk melakukan ini karena kompleksitas di sana lebih menyakitkan daripada kebanyakan tempat.

— Sendirian
sumber

2

Itu tergantung pada proses penyebaran Anda. Tetapi melakukan file yang dihasilkan ke dalam repositori adalah pengecualian dan harus dihindari, jika memungkinkan. Jika Anda dapat menjawab kedua pertanyaan berikut dengan Ya , memeriksa dokumen Anda mungkin merupakan opsi yang valid:

Apakah dokumen merupakan persyaratan untuk produksi?
Apakah sistem penyebaran Anda kekurangan alat yang diperlukan untuk membangun dokumen?

Jika kondisi ini benar, Anda mungkin menggunakan dengan sistem lama atau sistem dengan kendala keamanan khusus. Sebagai alternatif, Anda bisa mengkomit file yang dihasilkan ke cabang rilis dan menjaga cabang master bersih.

— Trendfischer
sumber

1

Mengkomit file yang dihasilkan menjadi cabang rilis tidak berfungsi dalam setiap situasi, tetapi ada sejumlah, terutama dengan hal-hal seperti situs web statis yang dibangun dari penurunan harga, di mana ini adalah solusi yang sangat baik. Saya cukup sering melakukannya sehingga saya membangun alat khusus untuk dengan mudah menghasilkan komitmen seperti bagian dari proses pembangunan.

— Curt J. Sampson

2

Tergantung. Jika dokumen itu:

Perlu menjadi bagian dari repositori, seperti readme.md, maka lebih disukai menyimpannya di git repo. Karena itu bisa rumit untuk menangani situasi itu dengan cara otomatis.
Jika Anda tidak memiliki cara otomatis untuk membangun dan memperbaruinya, seperti sistem CI, dan ini dimaksudkan untuk dilihat oleh khalayak umum, maka lebih disukai menyimpannya di git repo.
Butuh BANYAK waktu untuk membangunnya, lalu dibenarkan untuk menyimpannya.
Dimaksudkan untuk dilihat oleh khalayak umum (seperti panduan pengguna), dan dibutuhkan waktu yang cukup lama untuk membangun, sementara dokumen Anda sebelumnya menjadi tidak dapat diakses (offline), maka dibenarkan untuk menyimpannya di git repo.
Dimaksudkan agar dilihat oleh khalayak umum dan harus menunjukkan riwayat perubahan / evolusinya, bisa lebih mudah untuk menjaga versi dokumen sebelumnya tetap berkomitmen dan membangun / membuat yang baru terhubung dengan yang sebelumnya. Dapat dibenarkan.
Memiliki alasan tertentu yang diterima untuk semua tim yang akan dikomit, maka dibenarkan untuk menyimpannya di git repo. (Kami tidak tahu konteks Anda, Anda & tim Anda tahu)

Dalam skenario lain, itu harus diabaikan dengan aman.

Namun, jika dibenarkan untuk menyimpannya di git repo, bisa menjadi pertanda masalah lain yang lebih besar yang dihadapi tim Anda. (Tidak memiliki sistem CI atau masalah kinerja mengerikan yang serupa, menghadapi downtime saat membangun, dll.)

— throawableAccount2892391
sumber

1

Sebagai prinsip kontrol versi, hanya "objek utama" yang harus disimpan dalam repositori, bukan "objek turunan".

Ada pengecualian untuk aturan: yaitu, ketika ada konsumen dari repositori yang membutuhkan objek yang diturunkan, dan diharapkan tidak memiliki alat yang diperlukan untuk menghasilkan mereka. Pertimbangan lain menimbang, seperti apakah jumlah materialnya berat? (Apakah lebih baik bagi proyek untuk mendapatkan semua pengguna untuk memiliki alat?)

Contoh ekstrem dari ini adalah proyek yang mengimplementasikan bahasa pemrograman langka yang kompilernya ditulis dalam bahasa itu sendiri (contoh terkenal termasuk Ocaml atau Haskell). Jika hanya kode sumber kompilator di repositori, tidak ada yang bisa membangunnya; mereka tidak memiliki versi kompilasi dari kompiler yang dapat mereka jalankan di mesin virtual, sehingga mereka dapat mengkompilasi kode sumber kompiler itu. Selain itu, fitur terbaru dari bahasa tersebut segera digunakan dalam sumber kompilator itu sendiri, sehingga dekat dengan versi terbaru dari kompiler selalu diperlukan untuk membangunnya: satu bulan kompiler yang dapat dieksekusi yang diperoleh secara terpisah tidak akan mengkompilasi kode saat ini karena kode menggunakan fitur bahasa yang tidak ada sebulan yang lalu. Dalam situasi ini, versi kompilasi dari kompiler hampir pasti harus diperiksa ke dalam repositori dan tetap diperbarui.

— Kaz
sumber