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


49

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

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


3
อาจจะมีข้อโต้แย้งที่จะเก็บไว้ในที่เก็บ GitHub ที่คุณสามารถเผยแพร่ HTML คงใช้หน้า แม้ว่าแล้วชุดที่แยกจากกันอย่างสิ้นเชิงของการขัดแย้งเกิดขึ้นเป็นวิธีการที่คุณให้แน่ใจว่าพวกเขากำลังได้ถึงวัน ฯลฯ ...
บอริสไปเดอร์

21
หากไฟล์ถูกสร้างขึ้นแล้วโดยความหมายที่พวกเขาไม่ได้เป็นแหล่งที่มา
chrylis -on strike-

3
คุณเผยแพร่สิ่งที่คุณต้องการเผยแพร่ โดยเฉพาะกับ GitHub ถ้าคุณต้องการให้ทุกคนเห็น PDF หรือรูปภาพที่สร้างขึ้นคุณควรรวมไว้แทนที่จะคาดหวังให้ทุกคนติดตั้ง LaTeX และรวบรวมมันเอง ตัวอย่างเช่นนี้พื้นที่เก็บข้อมูลไม่ได้จะดีมากถ้ามันไม่ได้รวมถึงภาพการผลิตเฉพาะไฟล์โครงการ ...
Džuris


7
ในฐานะผู้บริโภคของห้องสมุดบุคคลที่สามจาก 10 เท่าที่ฉันเห็นห้องสมุดที่ไม่มีเอกสารออนไลน์ (ไม่ว่าจะเป็นโฟลเดอร์ย่อยของที่เก็บหรือเชื่อมโยงจาก readme) ฉันจะคลิกและข้ามห้องสมุดเหล่านั้นทั้งหมด 10 ครั้ง . ฉันจะไม่ไปยุ่งกับ Doxygen เพียงครึ่งชั่วโมงเพื่อดูว่าห้องสมุดตรงกับความต้องการของฉันหรือไม่
Alexander

คำตอบ:


131

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

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


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

27
@PeterMortensen หากคุณต้องการสิ่งประดิษฐ์ที่สร้างขึ้นด้วยเครื่องมือ buld รุ่นพิเศษคุณจะสร้างมันขึ้นมาด้วยเวอร์ชันของเครื่องมือสร้างที่คุณต้องการ ความต้องการดังกล่าวอาจเป็น) การค้นพบด้วยตัวเองซึ่งในกรณีนี้คุณต้องดำเนินการเอง b) เอกสารใน README ("คุณจะต้องมีสองรุ่นติดตั้ง Doxygen 2 รุ่นโดยเฉพาะ ... "); c) จัดการโดยสคริปต์สร้าง (ตรวจสอบรุ่นเครื่องมือสร้างที่มีอยู่และดำเนินการอย่างเหมาะสม) ไม่ว่าในกรณีใดการควบคุมแหล่งที่มามีไว้สำหรับแหล่งที่มาไม่ใช่เพื่อสร้างสิ่งประดิษฐ์
Joker_vD

2
ฉันคิดว่าคำตอบนี้ใช้ได้เฉพาะถ้าเซิร์ฟเวอร์การปรับใช้อย่างต่อเนื่องสร้างและเผยแพร่เอกสารในวิธีที่เข้าถึงได้ง่าย มิฉะนั้นจะมีค่ามากใน "แคช" เอกสารใน repo เพื่อปรับปรุงการเข้าถึง ผู้ใช้ไม่ควรโคลนสคริปต์สร้างของคุณเพียงเพื่อดูเอกสารประกอบซอฟต์แวร์ของคุณ
Alexander

4
@Alexander คุณจะใส่เลขฐานสองที่สร้างไว้ใน repo ด้วยหรือไม่ เอกสารประกอบถูกสร้างขึ้น คุณใช้เอกสารประกอบที่สร้างขึ้นและทำให้สามารถเข้าถึงได้จากที่อื่น
1201ProgramAlarm

5
@ 1201ProgramAlarm @ "คุณจะใส่ไบนารี่ที่สร้างไว้ใน repo ด้วยหรือไม่" ไม่เนื่องจากไบนารีในตัวมีค่าต่ำต่อผู้ที่เรียกดูทั่ว GitHub เมื่อเทียบกับเอกสาร "คุณใช้เอกสารประกอบที่สร้างขึ้น ตราบใดที่โฮสต์สาธารณะเชื่อมโยงอย่างเห็นได้ชัดแล้วก็ใช่ว่ายอดเยี่ยม มันอาจเป็นกรณีที่ดีที่สุด
Alexander

23

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

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

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


7
อย่าทำเอกสารว่าซอฟต์แวร์ที่ใครบางคนจำเป็นต้องมีต่อบิลด์ (หรืออย่างน้อยก็ไม่ใช่แค่เอกสาร): ให้สคริปต์สร้างบอกผู้ใช้ถึงสิ่งที่เขาขาดหายไปหรือติดตั้งด้วยตัวเองหากสมเหตุสมผล ใน repos ส่วนใหญ่ของฉันนักพัฒนาที่มีความสามารถครึ่งหนึ่งสามารถรัน./Testและรับบิลด์หรือรับข้อมูลที่ดีเกี่ยวกับสิ่งที่เขาต้องทำเพื่อรับบิลด์
Curt J. Sampson

5
ฉันไม่เห็นด้วยว่าการวางเอกสารที่สร้างไว้ใน git นั้นสามารถทำได้ในกรณีที่คุณระบุ นั่นคือเหตุผลที่เรามีสิ่งประดิษฐ์และจดหมายเหตุ
Sulthan

นั่นคือกฎของคุณและมันก็เป็นกฎที่ดีและฉันก็ชอบ แต่คนอื่นสามารถสร้างกฎของตัวเอง
emory

ฉันคิดว่าคุณหมายถึง "รันคำสั่ง build" เนื่องจากจะไม่มีปุ่มบิลด์บนเครื่องของคุณ ... ยกเว้นว่าคุณคาดหวังว่าการสร้างทั้งหมดจะรวมเข้ากับ IDE ซึ่งไม่มีเหตุผลทั้งหมด
jpmc26

@ jpmc26 ฉันคิดว่ามันสมเหตุสมผลอย่างยิ่งที่จะรวม build ทั้งหมดไว้ใน IDE ปุ่มสร้างบนเครื่องของฉันคือ Command-B
gnasher729

14

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

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


4

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

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


1
ที่ค่อนข้างจะต้องใช้ตะขอก่อนกระทำในแต่ละ repo ที่ใช้ในการสร้างความมุ่งมั่น เนื่องจากหากกระบวนการสร้างเอกสารไม่อัตโนมัติคุณจะได้รับข้อผูกพันที่มีเอกสารไม่ตรงกับรหัส และการกระทำที่ผิดพลาดเหล่านั้นจะสร้างความเสียหายให้กับความเข้าใจมากกว่าเอกสารที่ไม่ผูกมัด
cmaster

1
สิ่งนี้ไม่จำเป็นต้องอยู่ในขั้นตอนการกระทำ อาจเป็นงานดาวน์สตรีม / CI / Jenkins เพื่อเผยแพร่พวกเขาทุกครั้งที่พวกเขาเห็นว่ามีคุณค่าในการจัดเก็บ นี่อาจเป็นความมุ่งมั่นแต่ละอย่าง แต่การตัดสินใจควรถูกแยกออกในกรณีที่ไม่มีเหตุผลที่ดี หรืออย่างน้อยนั่นก็เป็นวิธีที่ฉันเห็น
ANone

3

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


2

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

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

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


1
การคอมมิชชันไฟล์ที่สร้างในสาขาการวางจำหน่ายนั้นไม่สามารถใช้ได้ในทุกสถานการณ์ แต่มีจำนวนมากโดยเฉพาะอย่างยิ่งกับเว็บไซต์แบบสแตติกที่สร้างขึ้นจาก markdown ซึ่งนี่เป็นทางออกที่ยอดเยี่ยม ฉันทำบ่อยครั้งพอที่ฉันสร้างเครื่องมือพิเศษเพื่อสร้างความมุ่งมั่นเช่นนี้เป็นส่วนหนึ่งของกระบวนการสร้าง
Curt J. Sampson

2

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

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

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

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

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

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

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

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

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


1

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

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

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

โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.