Nếu dự định thêm, thay đổi hoặc xoá một tính năng mà người dùng nhìn thấy, hoặc thực hiện một thay đổi đáng kể về cấu trúc đối với Bazel, thì bạn phải viết một tài liệu thiết kế và được xem xét trước khi có thể gửi thay đổi.
Sau đây là một số ví dụ về những thay đổi đáng kể:
- Thêm hoặc xoá các quy tắc tạo gốc
- Các thay đổi có thể gây ra lỗi cho 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
- Các thay đổi đối với API mà Bazel 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 rộng đến hiệu suất hoặc mức sử dụng bộ nhớ của Bazel (theo hướng tích cực hoặc tiêu cực)
- 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 cần xem xét thiết kế
Khi viết tài liệu thiết kế, bạn có thể phối hợp với các nhà phát triển Bazel khác và tìm kiếm hướng dẫn từ nhóm nòng cốt 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 các tệp BUILD, MODULE.bazel 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ả nghiêm trọng trên toàn cầu.
- Nhóm nhận được nhiều yêu cầu về tính năng từ người dùng; những yêu cầu như vậy cần được đánh giá không chỉ về tính khả thi về mặt kỹ thuật mà còn về tầm quan trọng so với các yêu cầu khác về tính năng.
- Các tính năng của Bazel thường được những người bên ngoài nhóm nòng cốt triển khai; những người đóng góp này có trình độ chuyên môn về Bazel rất đa dạng.
- Bản thân nhóm Bazel có nhiều trình độ chuyên môn khác nhau; 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 làm gián đoạn.
Chính sách đánh giá thiết kế của Bazel giúp tối đa hoá 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 các thiết kế trước khi chúng tôi đầu tư vào một quy trình 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 Bazel. Thiết kế đang trong quá trình thực hiện, vì vậy, thông tin chi tiết về việc triển khai có thể thay đổi theo thời gian và dựa trên ý kiến phản hồi. Các 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 những thay đổi đang diễn ra khi thiết kế được triển khai. Luôn tham khảo tài liệu để biết 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 Contributor
Là một người đóng góp, 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ế đều phải có tiêu đề, trong đó có:
- author
- ngày thay đổi lớn gần đây nhất
- danh sách người đánh giá, trong đó có một (và chỉ một) người đánh giá chính
- trạng thái hiện tại (bản nháp, đang được xem xét, đã phê duyệt, đã 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 đều có thể đọc hoặc dùng Markdown. Đọc phần bên dưới để biết thông tin so sánh giữa Markdown và Google Tài liệu.
Các đề xuất có tác động mà người dùng có thể thấy 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ế của bạn bằng cách tạo một 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 kéo của bạn.
Nếu có thể, hãy chọn một người đánh giá chính và gửi bản sao cho những người đánh giá khác. Nếu bạn không chọn người đánh giá chính, thì người duy trì Bazel sẽ chỉ định một người cho yêu cầu kéo của bạn.
Sau khi bạn tạo yêu cầu kéo, người đánh giá có thể đưa ra nhận xét sơ bộ trong quá trình đánh giá 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 PR khi họ cho rằng quy trình đánh giá 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 đó có đủ 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 PR được gử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 các 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 một tệp Google Tài liệu, bạn có thể sử dụng nhận xét thay thế (Xin lưu ý rằng chúng tôi cho phép nhận xét ẩn danh).
Cập nhật trạng thái
Tạo một yêu cầu kéo 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 yêu cầu kéo đến cùng một người đánh giá chính và gửi bản sao 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 yêu cầu kéo sau khi đảm bảo rằng những 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 thông báo đầu tiên và việc 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 bằng chứng về khái niệm hoặc thử nghiệm. Tuy nhiên, bạn không thể gửi yêu cầu thay đổi trước khi quy 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 và:
- Có kiến thức về các hệ thống con 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ó thể tham gia trong toàn bộ thời gian đánh giá để dẫn dắt quy trình
Hãy cân nhắc việc kiểm tra thông tin liên hệ của nhiều nhãn nhóm.
Markdown so với Google Tài liệu
Hãy quyết định cách nào phù hợp nhất với bạn, vì cả hai cách đều được chấp nhận.
Lợi ích của việc sử dụng Google Tài liệu:
- Hiệu quả trong việc lên ý tưởng vì rất dễ bắt đầu.
- Chỉnh sửa cộng tác.
- Xoay vòng nhanh chóng.
- 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.
- Khô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ác công cụ tìm kiếm.
- Đảm bảo cho tương lai: 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 quy tắc này ngay cả khi tác giả không còn ở đó.
- Chúng 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.).
Bạn có thể chọn lặp lại trên Google Tài liệu trước, sau đó chuyển đổi thành Markdown để lưu giữ.
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. Nó 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 như vậy, 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ì bất kỳ ai cũng 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 (Quy cách).
Tạo một yêu cầu kéo để cập nhật tài liệu hiện có. Những thay đổi đáng kể cần được người đánh giá tài liệu xem xét. Bất kỳ ai cũng có thể phê duyệt những thay đổi không đáng kể (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, đánh giá 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 cung cấp 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 một đề xuất mới
- Xem nhanh tài liệu.
- 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 thêm người đánh giá.
- Phê duyệt yêu cầu kéo khi yêu cầu đó đã sẵn sàng để xem xét.
Trong quá trình xem xét
- Trao đổi với tác giả thiết kế về những vấn đề gây khó khăn hoặc cần được làm rõ.
- Nếu phù 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 xem tác giả cần giải quyết những bình luận nào trước khi được phê duyệt.
- Viết "LGTM" (Looks Good To Me) 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 có triển khai hay không đối với một 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 uỷ quyền phù hợp (chỉ định lại PR cho người uỷ quyền) hoặc chỉ định lại lỗi cho một người quản lý Bazel để có biện pháp xử lý tiếp theo.
Trong quá trình xem xét
- Đảm bảo rằng quy trình nhận xét và lặp lại thiết kế diễn ra một cách hiệu quả.
- Trước khi phê duyệt, hãy đảm bảo rằng bạn đã giải quyết các mối lo ngại của những người đánh giá khác.
Sau khi tất cả người đánh giá phê duyệt
- Đảm bảo rằng đã có ít nhất 1 tuần kể từ khi thông báo được gửi trên danh sách gửi thư.
- Đảm bảo rằng PR cập nhật trạng thái.
- Phê duyệt yêu cầu kéo do tác giả đề xuất gửi.
Đang từ chối thiết kế
- Đảm bảo tác giả PR gửi PR hoặc gửi cho họ một PR.
- PR cập nhật trạng thái của chứng từ.
- Thêm một 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 rõ 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").