Nếu dự định thêm, thay đổi hoặc xoá một tính năng dành cho người dùng hoặc thực hiện thay đổi cấu trúc đáng kể đối với Bazel, bạn phải viết một tài liệu thiết kế và yêu cầu xem xét tài liệu đó trước khi có thể gửi nội dung thay đổi.
Sau đây là một số ví dụ về những thay đổi đáng kể:
- Thêm hoặc xoá quy tắc bản dựng gốc
- Các thay đổi có thể gây lỗi đối với quy tắc gốc
- Các thay đổi đối với ngữ nghĩa của quy tắc bản dựng gốc ảnh hưởng đến hành vi của nhiều quy tắc
- Các thay đổi đối với API định nghĩa quy tắc của Bazel
- Thay đổi đối với các API mà Bazel sử dụng để kết nối với các hệ thống khác
- Thay đổi đối với ngôn ngữ, ngữ nghĩa hoặc API Starlark
- Những thay đổi có thể ảnh hưởng sâu sắc đến hiệu suất hoặc mức sử dụng bộ nhớ của Bazel (tốt hơn hoặc xấu hơn)
- Thay đổi đối với các API nội bộ được sử dụng rộng rãi
- Thay đổi đối với cờ và giao diện dòng lệnh.
Lý do xem xét thiết kế
Khi viết tài liệu thiết kế, bạn có thể điều phối với các nhà phát triển Bazel khác và tìm kiếm hướng dẫn từ nhóm cốt lõi của Bazel. Ví dụ: khi một đề xuất thêm, xoá hoặc sửa đổi bất kỳ hàm hoặc đối tượng nào có trong tệp BUILD, WORKSPACE hoặc bzl, hãy thêm nhóm Starlark làm người đánh giá. Tài liệu thiết kế được xem xét trước khi gửi vì:
- Bazel là một hệ thống rất phức tạp; những thay đổi cục bộ có vẻ vô hại có thể gây ra hậu quả toàn cầu đáng kể.
- Nhóm nhận được nhiều yêu cầu về tính năng từ người dùng; các yêu cầu như vậy cần được đánh giá không chỉ về khả năng kỹ thuật mà còn về tầm quan trọng liên quan đến các yêu cầu về tính năng khác.
- Các tính năng của Bazel thường được triển khai bởi những người bên ngoài nhóm cốt lõi; những người đóng góp như vậy có nhiều cấp độ chuyên môn về Bazel.
- Bản thân nhóm Bazel có nhiều cấp độ chuyên môn; không có thành viên nào trong nhóm hiểu biết đầy đủ về mọi khía cạnh của Bazel.
- Các thay đổi đối với Bazel phải tính đến khả năng tương thích ngược và tránh các thay đổi gây lỗi.
Chính sách xem xét thiết kế của Bazel giúp tăng tối đa khả năng:
- tất cả các yêu cầu về tính năng đều được xem xét ở mức cơ bản.
- những người phù hợp sẽ cân nhắc về thiết kế trước khi chúng ta đầu tư vào một phương thức triển khai có thể không hiệu quả.
Để giúp bạn bắt đầu, hãy xem các tài liệu thiết kế trong Kho lưu trữ đề xuất về Bazel. Thiết kế đang trong quá trình hoàn thiện, vì vậy, thông tin chi tiết về cách triển khai có thể thay đổi theo thời gian và theo ý kiến phản hồi. Tài liệu thiết kế đã xuất bản ghi lại thiết kế ban đầu và không ghi lại các thay đổi đang diễn ra khi thiết kế được triển khai. Luôn truy cập vào tài liệu để xem nội dung mô tả về chức năng hiện tại của Bazel.
Quy trình làm việc của người đóng góp
Là một cộng tác viên, bạn có thể viết tài liệu thiết kế, gửi yêu cầu kéo và yêu cầu người đánh giá cho đề xuất của mình.
Viết tài liệu thiết kế
Tất cả tài liệu thiết kế phải có tiêu đề bao gồm:
- author
- ngày thay đổi lớn gần đây nhất
- danh sách người đánh giá, bao gồm một (và chỉ một) người đánh giá chính
- trạng thái hiện tại (dự thảo, đang được xem xét, đã phê duyệt, bị từ chối, đang được triển khai, đã triển khai)
- đường liên kết đến chuỗi thảo luận (sẽ được thêm sau thông báo)
Bạn có thể viết tài liệu dưới dạng một tệp Google Tài liệu mà mọi người trên thế giới đều đọc được hoặc sử dụng Markdown. Hãy đọc phần bên dưới để biết nội dung so sánh Markdown / Google Tài liệu.
Đề xuất có tác động rõ ràng đến người dùng phải có một phần ghi lại tác động đối với khả năng tương thích ngược (và kế hoạch triển khai nếu cần).
Tạo yêu cầu kéo
Chia sẻ tài liệu thiết kế bằng cách tạo yêu cầu kéo (PR) để thêm tài liệu vào chỉ mục thiết kế. Thêm tệp markdown hoặc đường liên kết đến tài liệu vào yêu cầu thay đổi.
Khi có thể, hãy chọn một người xem xét chính và cc những người xem xét khác. Nếu bạn không chọn người đánh giá chính, thì một người duy trì Bazel sẽ chỉ định người đánh giá cho yêu cầu phát hành của bạn.
Sau khi bạn tạo yêu cầu xem xét, người đánh giá có thể đưa ra nhận xét sơ bộ trong quá trình xem xét mã. Ví dụ: người đánh giá chính có thể đề xuất thêm người đánh giá hoặc chỉ ra thông tin còn thiếu. Người đánh giá chính sẽ phê duyệt thông cáo báo chí khi họ cho rằng quy trình xem xét có thể bắt đầu. Điều này không có nghĩa là đề xuất hoàn hảo hoặc sẽ được phê duyệt; mà có nghĩa là đề xuất đó chứa đủ thông tin để bắt đầu thảo luận.
Thông báo về đề xuất mới
Gửi thông báo đến bazel-dev khi gửi yêu cầu thay đổi.
Bạn có thể sao chép các nhóm khác (ví dụ: bazel-discuss để nhận ý kiến phản hồi từ người dùng cuối Bazel).
Thử nghiệm nhiều lần với người đánh giá
Bất kỳ ai quan tâm đều có thể bình luận về đề xuất của bạn. Cố gắng trả lời các câu hỏi, làm rõ đề xuất và giải quyết mối lo ngại.
Bạn nên thảo luận trong chuỗi thông báo. Nếu đề xuất nằm trong Google Tài liệu, bạn có thể sử dụng nhận xét (Lưu ý rằng bạn được phép sử dụng nhận xét ẩn danh).
Cập nhật trạng thái
Tạo một PR mới để cập nhật trạng thái của đề xuất khi quá trình lặp lại hoàn tất. Gửi thông cáo báo chí cho cùng một người đánh giá chính và cc cho những người đánh giá khác.
Để chính thức chấp nhận đề xuất, người đánh giá chính sẽ phê duyệt nội dung quảng bá sau khi đảm bảo rằng các người đánh giá khác đồng ý với quyết định này.
Phải có ít nhất 1 tuần giữa lần thông báo đầu tiên và lần phê duyệt đề xuất. Điều này đảm bảo rằng người dùng có đủ thời gian để đọc tài liệu và chia sẻ mối lo ngại của họ.
Bạn có thể bắt đầu triển khai trước khi đề xuất được chấp nhận, chẳng hạn như dưới dạng minh chứng về khái niệm hoặc thử nghiệm. Tuy nhiên, bạn không thể gửi nội dung thay đổi trước khi quá trình xem xét hoàn tất.
Chọn người đánh giá chính
Người đánh giá chính phải là một chuyên gia trong lĩnh vực, đồng thời:
- Có kiến thức về các hệ thống con có liên quan
- Khách quan và có khả năng đưa ra ý kiến phản hồi mang tính xây dựng
- Có mặt trong toàn bộ thời gian xem xét để dẫn dắt quy trình
Hãy cân nhắc kiểm tra danh bạ để biết các nhãn nhóm.
Markdown so với Google Tài liệu
Hãy quyết định phương thức phù hợp nhất với bạn vì cả hai đều được chấp nhận.
Lợi ích của việc sử dụng Google Tài liệu:
- Hiệu quả để lên ý tưởng vì dễ bắt đầu.
- Chỉnh sửa cộng tác.
- Lặp lại nhanh.
- Cách dễ dàng để đề xuất nội dung chỉnh sửa.
Lợi ích của việc sử dụng tệp Markdown:
- URL hợp lệ để liên kết.
- Bản ghi rõ ràng về các bản sửa đổi.
- Đừng quên thiết lập quyền truy cập trước khi công khai đường liên kết.
- Dễ dàng tìm kiếm bằng công cụ tìm kiếm.
- Bền vững: Văn bản thuần tuý không phụ thuộc vào bất kỳ công cụ cụ thể nào và không yêu cầu kết nối Internet.
- Bạn có thể cập nhật các bài viết đó ngay cả khi tác giả không còn hoạt động nữa.
- Các tệp này có thể được xử lý tự động (cập nhật/phát hiện đường liên kết không hoạt động, tìm nạp danh sách tác giả, v.v.).
Trước tiên, bạn có thể chọn lặp lại trên Google Tài liệu, sau đó chuyển đổi tài liệu đó sang Markdown để lưu trữ.
Sử dụng Google Tài liệu
Để đảm bảo tính nhất quán, hãy sử dụng mẫu tài liệu thiết kế Bazel. Tệp này bao gồm tiêu đề cần thiết và tạo tính nhất quán về hình ảnh với các tài liệu khác liên quan đến Bazel. Để làm việc đó, hãy nhấp vào Tệp > Tạo bản sao hoặc nhấp vào đường liên kết này để tạo bản sao của mẫu tài liệu thiết kế.
Để mọi người có thể đọc tài liệu của bạn, hãy nhấp vào Chia sẻ > Nâng cao > Thay đổi… rồi chọn "Bật – Bất kỳ ai có đường liên kết". Nếu bạn cho phép nhận xét trên tài liệu, thì mọi người đều có thể nhận xét ẩn danh, ngay cả khi không có Tài khoản Google.
Sử dụng Markdown
Tài liệu được lưu trữ trên GitHub và sử dụng phiên bản Markdown của GitHub (Thông số kỹ thuật).
Tạo một yêu cầu thay đổi để cập nhật tài liệu hiện có. Những thay đổi đáng kể phải được người đánh giá tài liệu xem xét. Bất kỳ ai cũng có thể phê duyệt các thay đổi nhỏ (chẳng hạn như lỗi chính tả, định dạng).
Quy trình làm việc của người đánh giá
Người đánh giá nhận xét, xem xét và phê duyệt tài liệu thiết kế.
Trách nhiệm chung của người đánh giá
Bạn có trách nhiệm xem xét tài liệu thiết kế, yêu cầu thêm thông tin nếu cần và phê duyệt thiết kế đã vượt qua quy trình xem xét.
Khi bạn nhận được đề xuất mới
- Xem nhanh tài liệu.
- Hãy bình luận nếu thiếu thông tin quan trọng hoặc nếu thiết kế không phù hợp với mục tiêu của dự án.
- Đề xuất người đánh giá khác.
- Chấp thuận yêu cầu thay đổi khi yêu cầu đó đã sẵn sàng để xem xét.
Trong quá trình xem xét
- Trò chuyện với tác giả thiết kế về các vấn đề cần giải thích hoặc có vấn đề.
- Nếu thích hợp, hãy mời những người không phải là người đánh giá nhưng cần biết về thiết kế đưa ra ý kiến.
- Quyết định những bình luận mà tác giả phải giải quyết trước khi được phê duyệt.
- Viết "LGTM" (Looks Good To Me – Tôi thấy ổn) trong chuỗi thảo luận khi bạn hài lòng với trạng thái hiện tại của đề xuất.
Hãy làm theo quy trình này cho tất cả các yêu cầu xem xét thiết kế. Không phê duyệt các thiết kế ảnh hưởng đến Bazel nếu chúng không có trong chỉ mục thiết kế.
Trách nhiệm của người đánh giá chính
Bạn chịu trách nhiệm đưa ra quyết định triển khai / không triển khai thiết kế đang chờ xử lý. Nếu không thể làm việc này, bạn nên xác định một người được uỷ quyền phù hợp (chuyển lại yêu cầu thay đổi cho người được uỷ quyền) hoặc chuyển lại lỗi cho một người quản lý Bazel để xử lý thêm.
Trong quá trình xem xét
- Đảm bảo rằng quy trình lặp lại nhận xét và thiết kế sẽ tiến triển một cách tích cực.
- Trước khi phê duyệt, hãy đảm bảo rằng bạn đã giải quyết xong các mối lo ngại của các người đánh giá khác.
Sau khi tất cả người đánh giá phê duyệt
- Hãy đảm bảo đã có ít nhất 1 tuần kể từ khi thông báo trên danh sách gửi thư.
- Đảm bảo thông tin cập nhật trạng thái trong bản phát hành công khai.
- Phê duyệt thông cáo báo chí do tác giả đề xuất gửi.
Từ chối thiết kế
- Đảm bảo tác giả quan hệ công chúng gửi thông cáo báo chí hoặc bạn gửi thông cáo báo chí cho họ.
- Thông cáo báo chí sẽ cập nhật trạng thái của tài liệu.
- Thêm nhận xét vào tài liệu giải thích lý do không thể phê duyệt thiết kế ở trạng thái hiện tại và nêu các bước tiếp theo (nếu có) (chẳng hạn như "xem lại các giả định không hợp lệ và gửi lại").