Üretilen belgeler Git deposunda saklanmalı mı?

Jsdocs gibi araçlar kullandığınızda , kodunuzdaki yorumlara dayanarak statik HTML dosyaları ve kod üssünüzdeki stillerini oluşturur.

Bu dosyalar Git deposunda mı kontrol edilmeli yoksa .gitignore ile mi göz ardı edilmeli?

Herhangi bir özel gereksinim duyulmadığında, sürüm kontrolünde kontrol edilen diğer dosyaları kullanarak derleme araçlarından oluşturulabilen, yeniden oluşturulabilen, oluşturulabilen veya oluşturulabilen herhangi bir dosya kontrol edilmemelidir. Dosya gerektiğinde diğerinden oluşturulabilir kaynaklar (ve normalde inşa sürecinin bir yönü olabilir).

Bu yüzden bu dosyalar .gitignore ile göz ardı edilmelidir.

Benim kuralım, bir havuzu klonladığımda ve “yap” düğmesine bastığımda, bir süre sonra, her şeyin oluşturulmuş olmasıdır. Üretilen belgeleriniz için bunu başarmak için iki seçeneğiniz vardır: ya birileri bu dokümanları oluşturmaktan ve gitmesine koymaktan sorumludur ya da geliştirme makinemde tam olarak hangi yazılımı kullanmam gerektiğini belgeliyorsunuz ve “yapıya basmak” gerektiğinden emin oluyorsunuz düğmesi makinemdeki tüm belgeleri oluşturur.

Üretilen belgeler durumunda, bir başlık dosyasında yaptığım herhangi bir değişikliğin belgeleri değiştirmesi gerektiği durumlarda, bunu her geliştiricinin makinesinde yapmak daha iyidir, çünkü yalnızca biri güncellendiğinde değil, her zaman doğru belgeler istiyorum. Bir şey üretmenin zaman alıcı, karmaşık olabileceği, yalnızca bir lisansa sahip olduğunuz yazılımı gerektiren vb. Başka durumlar da olabilir. Bu durumda, bir kişiye işleri yerine koyma sorumluluğunu vermek daha iyidir.

@Curt Simpson: Tüm yazılım gereksinimlerinin belgelendirilmesi , birçok yerde gördüğümden çok daha iyi.

Bu dosyalar, onları üretecek veriler zaten mevcut olduğu için teslim edilmemelidir. Verileri iki kez (DRY) saklamak istemezsiniz.

Bir CI sisteminiz varsa, dokümanları oluşturup bunları bir web sunucusunda yayınlamak / yayınlamak için saklayabilirsiniz.

Bunları bazı havuzlarda bulundurmanın bir avantajı (aynı veya farklı, tercihen otomatik olarak oluşturulan), o zaman dokümantasyondaki tüm değişiklikleri görebilmenizdir. Bazen bu farkların okunması, kaynak kodundaki farklardan daha kolaydır (özellikle sadece uygulamadaki değişiklikleri değil, spesifikasyon değişikliklerini önemsiyorsanız).

Ancak çoğu durumda bunların kaynak kontrolünde olması, diğer cevaplarda açıklandığı gibi gerekli değildir.

Yok Sayılan. Repo kullanıcılarının onları yine de yeniden yapabilmelerini isteyeceksiniz ve bu, dokümanın her zaman senkronize olduğundan emin olmanın karmaşıklığını ortadan kaldırıyor. Eğer herşeyi tek bir yerde yapmak ve bir şey inşa etmek istemiyorsanız, yapılı yapıların bir yerde toplanmasının bir nedeni yoktur. Ancak kaynak repolar bunu yapmak için gerçekten iyi bir yer değil, ancak karmaşıklık çoğu yerden daha fazla acı veriyor.

Dağıtım işleminize bağlı. Ancak oluşturulan dosyaları bir depoya dahil etmek bir istisnadır ve mümkünse kaçınılması gerekir. Aşağıdaki soruların ikisine de Evet ile cevap verebilirseniz , dokümanlarınızı kontrol etmek geçerli bir seçenek olabilir:

• Dokümanlar üretim için bir gereklilik midir?
• Dağıtım sisteminiz dokümanları oluşturmak için gerekli araçlardan yok mu?

Bu koşullar doğruysa, muhtemelen eski bir sistemle veya özel güvenlik kısıtlamaları olan bir sistemle konuşlandırıyorsunuzdur. Alternatif olarak, oluşturulan dosyaları bir sürüm şubesine teslim edebilir ve ana şubeyi temiz tutabilirsiniz.

Değişir. Eğer bu dokümanlar:

• Deponun bir parçası olması gerekiyor, aynen olduğu gibi, readme.mdonları git deposunda tutmak tercih ediliyor. Çünkü bu durumları otomatik olarak ele almak zor olabilir.

• Bunları oluşturmak ve güncellemek için bir CI sistemi gibi otomatik bir yolunuz yoksa ve genel izleyici için görülmesi amaçlanıyorsa, bunları git deposunda tutmak tercih edilir.

• Onları oluşturmak için çok zaman alır, sonra onları tutmak haklı çıkar.

• Genel izleyici kitlesi için görülmesi amaçlanmıştır (kullanım kılavuzu gibi) ve önceki belgeleriniz erişilemez duruma geldiğinde (çevrimdışı), daha sonra bunları git deposunda tutmak doğrulanabilir.

• Genel izleyici için görülmesi amaçlanmıştır ve değişikliklerin / evriminin geçmişini göstermek zorundadır, önceki doküman sürümlerini tutmak ve yenisini önceki ile bağlantılı hale getirmek ve oluşturmak / yapmak daha kolay olabilir. Justifiable.

• Tüm takımın görevlendirilmesi için özel bir kabul sebebi var, sonra onları git deposunda tutmak haklı. (Bağlamınızı bilmiyoruz, siz ve takımınız biliyor)

Başka bir senaryoda, güvenle göz ardı edilmelidir.

Bununla birlikte, onları git deposunda tutmanın haklı olması durumunda, ekibinizin karşılaştığı daha büyük bir sorunun işareti olabilir. (Bir CI sistemine sahip olmamak ya da benzer, korkunç performans sorunlarına sahip olmak, bina sırasındaki aksaklıklarla karşılaşmak vb.)

Sürüm kontrol ilkesi olarak, yalnızca "birincil nesneler", "türetilmiş nesneler" yerine bir depoda depolanmalıdır.

Kural için istisnalar vardır: yani, türetilmiş nesnelere ihtiyaç duyan depo tüketicileri olduğunda ve bunları üretmek için gerekli araçlara sahip olmamaları beklenmemektedir. Tartışılan diğer konular, malzeme tutarsızlığı gibi mi? (Projenin tüm kullanıcıların araçları edinmesi daha iyi olur mu?)

Buna aşırı bir örnek, derleyicisi bu dilde yazılmış nadir bir programlama dili uygulayan bir projedir (iyi bilinen örnekler Ocaml veya Haskell'i içerir).). Yalnızca derleyici kaynak kodu depodaysa, kimse oluşturamaz; Derleyicinin sanal makinede çalıştırabilecekleri derlenmiş bir sürümleri yoktur, böylece derleyicinin kaynak kodunu derleyebilirler. Dahası, dilin en yeni özellikleri derleyici kaynağında derhal kullanılır, böylece derleyicinin en son sürümüne yakın olması her zaman için gereklidir: ayrı ayrı elde edilen bir aylık derleyici geçerli kodu derlemeyecektir çünkü kod Bir ay önce bulunmayan dil özelliklerini kullanır. Bu durumda, derleyicinin derlenmiş sürümü neredeyse kesinlikle depoya kontrol edilmeli ve güncel tutulmalıdır.