เอกสารที่สร้างขึ้นควรเก็บไว้ในที่เก็บ Git หรือไม่?

เมื่อคุณใช้เครื่องมือเช่นjsdocsมันจะสร้างไฟล์ HTML แบบคงที่และสไตล์ของมันใน codebase ของคุณตามความคิดเห็นในรหัสของคุณ

ควรตรวจสอบไฟล์เหล่านี้ในที่เก็บ Git หรือไม่หรือควรละเว้นด้วย. gitignore

ขาดความต้องการเฉพาะไฟล์ใด ๆ ที่สามารถสร้างขึ้นใหม่สร้างหรือสร้างขึ้นจากเครื่องมือสร้างโดยใช้ไฟล์อื่น ๆ ที่ตรวจสอบลงในการควบคุมเวอร์ชันไม่ควรทำการตรวจสอบในเมื่อจำเป็นต้องใช้ไฟล์มันสามารถสร้างใหม่ได้อีก แหล่งที่มา (และโดยปกติจะเป็นส่วนหนึ่งของกระบวนการสร้าง)

ดังนั้นไฟล์เหล่านั้นควรถูกละเว้นด้วย. gignignore

กฎของฉันคือเมื่อฉันโคลนที่เก็บและกดปุ่ม“ สร้าง” หลังจากนั้นทุกอย่างจะถูกสร้างขึ้น เพื่อให้บรรลุสิ่งนี้สำหรับเอกสารที่สร้างขึ้นของคุณคุณมีสองทางเลือก: ใครบางคนมีหน้าที่รับผิดชอบในการสร้างเอกสารเหล่านี้และใส่ไว้ในคอมไพล์หรือคุณทำเอกสารว่าซอฟต์แวร์ใดที่ฉันต้องการในเครื่องพัฒนาของฉัน ปุ่มสร้างเอกสารทั้งหมดในเครื่องของฉัน

ในกรณีของเอกสารประกอบที่สร้างขึ้นซึ่งการเปลี่ยนแปลงใด ๆ ที่ฉันทำกับไฟล์ส่วนหัวควรเปลี่ยนเอกสารประกอบการทำสิ่งนี้ในเครื่องของนักพัฒนาซอฟต์แวร์แต่ละคนนั้นดีกว่าเพราะฉันต้องการเอกสารที่ถูกต้องตลอดเวลาไม่ใช่เฉพาะเมื่อมีคนอัพเดต มีสถานการณ์อื่น ๆ ที่การสร้างบางสิ่งอาจใช้เวลานานซับซ้อนต้องใช้ซอฟต์แวร์ที่คุณมีใบอนุญาตเพียงใบเดียวเป็นต้นในกรณีนี้การให้บุคคลหนึ่งคนมีความรับผิดชอบในการนำสิ่งต่าง ๆ เข้ามาในระบบคอมไพล์จะดีกว่า

@Curt Simpson: การมีเอกสารข้อกำหนดซอฟต์แวร์ทั้งหมดนั้นดีกว่าที่ฉันเคยเห็นในหลาย ๆ ที่

ไม่ควรเช็คอินไฟล์เหล่านี้เนื่องจากข้อมูลที่สร้างขึ้นมีอยู่แล้ว คุณไม่ต้องการจัดเก็บข้อมูลสองครั้ง (DRY)

หากคุณมีระบบ CI คุณอาจสร้างที่สร้างเอกสารและเก็บไว้สำหรับการสร้าง / เผยแพร่ไปยังเว็บเซิร์ฟเวอร์

ข้อดีอย่างหนึ่งของการมีพวกมันไว้ในที่เก็บบางอัน (อันเดียวกันหรืออันอื่นที่สร้างขึ้นโดยอัตโนมัติ) คือคุณสามารถเห็นการเปลี่ยนแปลงทั้งหมดในเอกสาร บางครั้ง diffs เหล่านั้นจะอ่านง่ายกว่า diffs ไปยังซอร์สโค้ด (โดยเฉพาะถ้าคุณสนใจเฉพาะการเปลี่ยนแปลงข้อมูลจำเพาะไม่ใช่การนำไปใช้งานอย่างใดอย่างหนึ่ง)

แต่โดยส่วนใหญ่แล้วการมีพวกมันไว้ในแหล่งควบคุมนั้นไม่จำเป็นเช่นเดียวกับคำตอบอื่น ๆ ที่อธิบายไว้

ละเว้น คุณต้องการให้ผู้ใช้ repo สามารถสร้างพวกเขาใหม่ได้และจะลบความซับซ้อนของการตรวจสอบว่าเอกสารนั้นซิงค์อยู่เสมอ ไม่มีเหตุผลที่จะไม่รวมสิ่งประดิษฐ์ที่รวมอยู่ในที่เดียวหากคุณต้องการมีทุกอย่างในที่เดียวและไม่ต้องสร้างอะไรเลย อย่างไรก็ตามแหล่งที่มา repos ไม่ได้เป็นสถานที่ที่ดีในการทำเช่นนี้แม้ว่าความซับซ้อนมีความเจ็บปวดมากกว่าสถานที่ส่วนใหญ่

ขึ้นอยู่กับกระบวนการปรับใช้ของคุณ แต่การคอมมิตไฟล์ที่สร้างไปยังที่เก็บเป็นข้อยกเว้นและควรหลีกเลี่ยงหากเป็นไปได้ หากคุณสามารถตอบคำถามทั้งสองข้อต่อไปนี้ด้วยใช่การตรวจสอบเอกสารของคุณอาจเป็นตัวเลือกที่ถูกต้อง:

• เอกสารเป็นข้อกำหนดสำหรับการผลิตหรือไม่
• ระบบการปรับใช้ของคุณขาดเครื่องมือที่จำเป็นในการสร้างเอกสารหรือไม่?

หากเงื่อนไขเหล่านี้เป็นจริงคุณอาจกำลังปรับใช้กับระบบเดิมหรือระบบที่มีข้อ จำกัด ด้านความปลอดภัยเป็นพิเศษ คุณสามารถคอมมิทไฟล์ที่สร้างขึ้นให้เป็นรีลีสแบรนช์และทำให้สาขาหลักสะอาด

มันขึ้นอยู่กับ. หากเอกสารเหล่านั้น:

• จำเป็นต้องเป็นส่วนหนึ่งของพื้นที่เก็บข้อมูลเช่นreadme.mdนั้นจึงควรเก็บไว้ใน git repo เพราะมันอาจเป็นเรื่องยุ่งยากในการจัดการกับสถานการณ์เหล่านั้นด้วยวิธีอัตโนมัติ

• หากคุณไม่มีวิธีอัตโนมัติในการสร้างและอัปเดตพวกเขาเช่นระบบ CI และมีไว้สำหรับผู้ชมทั่วไปคุณควรเก็บไว้ใน git repo

• ใช้เวลามากมายในการสร้างพวกเขาจากนั้นเป็นเหตุผลที่จะทำให้พวกเขา

• มีไว้สำหรับผู้ชมทั่วไป (เช่นคู่มือผู้ใช้) และต้องใช้เวลาในการสร้างมากในขณะที่เอกสารก่อนหน้าของคุณไม่สามารถเข้าถึงได้ (ออฟไลน์) จากนั้นเป็นเหตุผลที่ควรเก็บไว้ใน repo คอมไพล์

• มีจุดประสงค์เพื่อให้ผู้ชมทั่วไปเห็นและต้องแสดงประวัติของการเปลี่ยนแปลง / วิวัฒนาการมันง่ายกว่าที่จะทำให้เอกสาร doc รุ่นก่อนหน้ามุ่งมั่นและสร้าง / คอมมิชชันใหม่ที่เชื่อมโยงกับหน้าที่แล้ว แก้ตัวได้

• มีเหตุผลที่เป็นที่ยอมรับโดยเฉพาะสำหรับทีมงานทุกคนที่จะได้รับการยอมรับ (เราไม่ทราบบริบทของคุณคุณและทีมของคุณทำ)

ในสถานการณ์อื่น ๆ ควรละเว้นอย่างปลอดภัย

อย่างไรก็ตามหากมีเหตุผลสมควรที่จะเก็บไว้ใน repo คอมไพล์อาจเป็นสัญญาณของปัญหาที่ใหญ่กว่าที่ทีมของคุณกำลังเผชิญอยู่ (ไม่มีระบบ CI หรือปัญหาประสิทธิภาพที่คล้ายคลึงกันที่น่ากลัวเผชิญกับการหยุดทำงานขณะสร้าง ฯลฯ )

ตามหลักการของการควบคุมเวอร์ชันควรเก็บเฉพาะ "วัตถุหลัก" ในที่เก็บไม่ใช่ "วัตถุที่ได้รับ"

มีข้อยกเว้นสำหรับกฎนี้คือเมื่อมีผู้บริโภคของที่เก็บที่ต้องการวัตถุที่ได้รับและคาดว่าจะไม่มีเครื่องมือที่จำเป็นในการสร้างพวกเขา ข้อควรพิจารณาอื่น ๆ มีน้ำหนักเช่นปริมาณของวัสดุที่เทอะทะหรือไม่ (มันจะดีกว่าสำหรับโครงการเพิ่งให้ผู้ใช้ทั้งหมดมีเครื่องมือหรือไม่)

ตัวอย่างสุดขั้วนี้เป็นโครงการที่ใช้ภาษาการเขียนโปรแกรมที่หายากซึ่งคอมไพเลอร์เขียนด้วยภาษานั้นเอง (ตัวอย่างที่รู้จักกันดี ได้แก่OcamlหรือHaskell) หากคอมไพเลอร์ซอร์สโค้ดอยู่ในที่เก็บไม่มีใครสามารถสร้างได้ พวกเขาไม่มีคอมไพเลอร์เวอร์ชันคอมไพล์ที่พวกเขาสามารถเรียกใช้บนเครื่องเสมือนเพื่อให้พวกเขาสามารถรวบรวมซอร์สโค้ดของคอมไพเลอร์นั้น ยิ่งไปกว่านั้นคุณสมบัติล่าสุดของภาษาจะถูกใช้ในแหล่งตัวแปลทันทีดังนั้นจึงจำเป็นต้องสร้างเวอร์ชั่นล่าสุดของคอมไพเลอร์เสมอ: คอมไพเลอร์ตัวเก่าที่ได้รับเดือนที่แยกต่างหากจะไม่รวบรวมรหัสปัจจุบันเพราะรหัส ใช้คุณสมบัติภาษาที่ไม่มีอยู่เมื่อเดือนที่แล้ว ในสถานการณ์นี้คอมไพเลอร์เวอร์ชันคอมไพล์เลอร์เกือบจะต้องถูกตรวจสอบในที่เก็บและทำให้ทันสมัย