Tài liệu được tạo nên được lưu trữ trong kho Git?

Khi bạn sử dụng các công cụ như jsdocs , nó sẽ tạo các tệp HTML tĩnh và các kiểu của nó trong cơ sở mã của bạn dựa trên các nhận xét trong mã của bạn.

Những tệp này nên được kiểm tra vào kho Git hay chúng nên được bỏ qua với .gitignore?

Không có bất kỳ nhu cầu cụ thể nào, bất kỳ tệp nào có thể được xây dựng, tái tạo, xây dựng hoặc tạo từ các công cụ xây dựng bằng các tệp khác được kiểm tra trong kiểm soát phiên bản không nên được kiểm tra. Khi cần tệp, nó có thể được xây dựng lại từ tệp kia nguồn (và thông thường sẽ là một số khía cạnh của quá trình xây dựng).

Vì vậy, những tập tin nên được bỏ qua với .gitignore.

Quy tắc của tôi là khi tôi sao chép một kho lưu trữ và nhấn nút xây dựng trên mạng, sau đó, sau một thời gian, mọi thứ sẽ được xây dựng. Để đạt được điều này cho tài liệu được tạo của bạn, bạn có hai lựa chọn: ai đó chịu trách nhiệm tạo các tài liệu này và đưa chúng vào git hoặc bạn ghi lại chính xác phần mềm nào tôi cần trên máy phát triển của mình và bạn chắc chắn rằng nhấn nút xây dựng nút xây dựng tất cả các tài liệu trên máy của tôi.

Trong trường hợp tài liệu được tạo, trong đó bất kỳ thay đổi nào tôi thực hiện đối với tệp tiêu đề sẽ thay đổi tài liệu, thực hiện việc này trên mỗi máy của nhà phát triển sẽ tốt hơn, vì tôi luôn muốn tài liệu chính xác, không chỉ khi ai đó đã cập nhật. Có những tình huống khác trong đó việc tạo ra một cái gì đó có thể tốn thời gian, phức tạp, yêu cầu phần mềm mà bạn chỉ có một giấy phép, v.v. Trong trường hợp đó, giao cho một người trách nhiệm đưa mọi thứ vào git là tốt hơn.

@Curt Simpson: Có tất cả các yêu cầu phần mềm được ghi lại là tốt hơn nhiều so với tôi đã thấy ở nhiều nơi.

Những tệp này không nên được kiểm tra vì dữ liệu để tạo chúng đã có sẵn. Bạn không muốn lưu trữ dữ liệu hai lần (DRY).

Nếu bạn có một hệ thống CI, có lẽ bạn có thể tạo bản dựng tài liệu đó và lưu trữ chúng cho bản dựng / xuất bản đó lên máy chủ web.

Một lợi thế của việc có chúng trong một số kho lưu trữ (giống nhau hoặc khác nhau, tốt nhất là được tạo tự động) là sau đó bạn có thể thấy tất cả các thay đổi đối với tài liệu. Đôi khi những khác biệt đó dễ đọc hơn các khác biệt đối với mã nguồn (cụ thể nếu bạn chỉ quan tâm đến các thay đổi đặc điểm kỹ thuật, không thực hiện một).

Nhưng trong hầu hết các trường hợp, việc kiểm soát nguồn là không cần thiết, như các câu trả lời khác đã giải thích.

Làm ngơ. Bạn sẽ muốn người dùng của repo có thể xây dựng lại chúng bằng mọi cách và điều này sẽ loại bỏ sự phức tạp của việc đảm bảo tài liệu luôn đồng bộ. Không có lý do gì để không có các cổ vật được xây dựng được đóng gói ở một nơi nếu bạn muốn có mọi thứ ở một nơi và không phải xây dựng bất cứ thứ gì. Tuy nhiên, repos nguồn không thực sự là một nơi tốt để làm điều này mặc dù sự phức tạp ở đó làm tổn thương nhiều hơn hầu hết các nơi.

Nó phụ thuộc vào quá trình triển khai của bạn. Nhưng cam kết các tệp được tạo vào một kho lưu trữ là một ngoại lệ và nên tránh, nếu có thể. Nếu bạn có thể trả lời cả hai câu hỏi sau bằng Có , kiểm tra tài liệu của bạn có thể là một tùy chọn hợp lệ:

• Các tài liệu là một yêu cầu cho sản xuất?
• Hệ thống triển khai của bạn có thiếu các công cụ cần thiết để xây dựng tài liệu không?

Nếu những điều kiện này là đúng, có lẽ bạn đang triển khai với một hệ thống cũ hoặc một hệ thống có các ràng buộc bảo mật đặc biệt. Thay vào đó, bạn có thể cam kết các tệp được tạo thành một nhánh phát hành và giữ cho nhánh chính sạch sẽ.

Nó phụ thuộc. Nếu những tài liệu đó:

• Cần phải là một phần của kho lưu trữ, như readme.md, sau đó, nên giữ chúng trong repo git. Bởi vì có thể khó để xử lý các tình huống đó một cách tự động.

• Nếu bạn không có cách tự động để xây dựng và cập nhật chúng, như hệ thống CI, và nó được dự kiến ​​sẽ được nhìn thấy cho khán giả nói chung, thì nên giữ chúng trong repo git.

• Mất rất nhiều thời gian để xây dựng chúng, sau đó chính đáng để giữ chúng.

• Được dự kiến ​​để xem đối tượng chung (như hướng dẫn sử dụng) và phải mất một thời gian đáng kể để xây dựng, trong khi các tài liệu trước đó của bạn không thể truy cập được (ngoại tuyến), sau đó có thể giữ chúng trong repit git.

• Được dự kiến ​​để xem cho khán giả nói chung và phải hiển thị lịch sử thay đổi / tiến hóa của nó, có thể dễ dàng hơn để giữ các phiên bản tài liệu trước được cam kết và xây dựng / cam kết cái mới được liên kết với trước đó. Chính đáng.

• Có một lý do được chấp nhận cụ thể cho tất cả các nhóm được cam kết, sau đó là chính đáng để giữ họ trong repo git. (Chúng tôi không biết bối cảnh của bạn, bạn và nhóm của bạn làm)

Trong bất kỳ kịch bản khác, nó nên được bỏ qua một cách an toàn.

Tuy nhiên, nếu việc giữ chúng trong git repo là điều chính đáng, có thể là dấu hiệu của một vấn đề lớn hơn mà nhóm của bạn đang phải đối mặt. (Không có hệ thống CI hoặc các vấn đề hiệu suất khủng khiếp tương tự, phải đối mặt với thời gian chết trong khi xây dựng, v.v.)

Theo nguyên tắc kiểm soát phiên bản, chỉ nên lưu trữ "đối tượng chính" trong kho lưu trữ, không phải "đối tượng dẫn xuất".

Có các trường hợp ngoại lệ cho quy tắc: cụ thể là khi có người tiêu dùng của kho lưu trữ yêu cầu các đối tượng dẫn xuất và dự kiến ​​hợp lý sẽ không có các công cụ cần thiết để tạo ra chúng. Các cân nhắc khác cân nhắc, như là số lượng vật liệu khó sử dụng? (Sẽ tốt hơn nếu dự án chỉ cần tất cả người dùng có công cụ?)

Một ví dụ cực đoan về điều này là một dự án thực hiện một ngôn ngữ lập trình hiếm có trình biên dịch được viết bằng chính ngôn ngữ đó (các ví dụ nổi tiếng bao gồm Ocaml hoặc Haskell). Nếu chỉ có mã nguồn trình biên dịch nằm trong kho lưu trữ, không ai có thể xây dựng nó; họ không có phiên bản biên dịch của trình biên dịch mà họ có thể chạy trên máy ảo, để họ có thể biên dịch mã nguồn của trình biên dịch đó. Hơn nữa, các tính năng mới nhất của ngôn ngữ ngay lập tức được sử dụng trong chính nguồn của trình biên dịch, do đó, gần với phiên bản mới nhất của trình biên dịch luôn được yêu cầu để xây dựng nó: một trình biên dịch cũ có thể thực hiện được một cách riêng biệt sẽ không biên dịch mã hiện tại vì mã sử dụng các tính năng ngôn ngữ không tồn tại một tháng trước. Trong tình huống này, phiên bản biên dịch của trình biên dịch gần như chắc chắn phải được kiểm tra vào kho lưu trữ và được cập nhật.