Haruskah dokumentasi yang dihasilkan disimpan dalam repositori Git?

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?

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.

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.

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.

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.

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.

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.

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

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.