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 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à yêu cầu xem xét tài liệu đó 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á quy tắc xây dựng gốc
- Các thay đổi có thể gây ra lỗi cho quy tắc gốc
- Thay đổi đối với ngữ nghĩa của quy tắc xây dựng gốc ảnh hưởng đến hành vi của nhiều quy tắ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 của Starlark
- Thay đổi có thể có tác độ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ốt hơn hoặc tệ 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ể 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 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, 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 những hậu quả đáng kể 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 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 những người không thuộc nhóm cốt lõi triển khai; những người đóng góp như vậy có trình độ chuyên môn về Bazel rất khác nhau.
- Bản thân nhóm Bazel cũng có 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 có thể gây ra lỗi.
Chính sách về bài đá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 về thiết kế trước khi chúng tôi đầu tư vào một cách triển khai có thể không hoạt động.
Để giúp bạn bắt đầu, hãy xem tài liệu thiết kế trong Kho lưu trữ đề xuất Bazel. Thiết kế là công việc đang được tiến hành, 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, không phải những 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 để 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 người đóng góp
Là 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ế phải có tiêu đề bao gồm:
- author
- date of last major change
- list of reviewers, including one (and only one) lead reviewer
- current status (draft, in review, approved, rejected, being implemented, implemented)
- link to discussion thread (to be added after the announcement)
Bạn có thể viết tài liệu dưới dạng Google Tài liệu có thể đọc được trên toàn cầu hoặc sử dụng Markdown. Đọc 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 đến 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 kéo.
Khi có thể, hãy chọn một người đánh giá chính. và sao chép 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 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 bị thiếu. Người đánh giá chính phê duyệt yêu cầu kéo khi họ tin 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; điều này 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 yêu cầu kéo đượ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. Hãy cố gắng trả lời câu hỏi, làm rõ đề xuất và giải quyết các mối lo ngại.
Cuộc thảo luận nên diễn ra trên chuỗi thông báo. Nếu đề xuất ở dạng Google Tài liệu, bạn có thể sử dụng nhận xét (Lưu ý rằng bạn có thể bình luận ẩn danh).
Cập nhật trạng thái
Tạo yêu cầu kéo mới để cập nhật trạng thái của đề xuất khi quá trình thử nghiệm nhiều lần hoàn tất. Gửi yêu cầu kéo cho cùng một người đánh giá chính và sao chép 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, ví dụ: 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 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à chuyên gia về miền:
- 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ó 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 thông tin liên hệ cho nhiều nhãn nhóm.
Markdown so với Google Tài liệu
Hãy quyết định lựa chọn 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ả cho việc tìm ý tưởng, vì bạn có thể dễ dàng bắt đầu.
- Chỉnh sửa theo nhóm.
- Thử nghiệm nhiều lần nhanh chóng.
- Cách dễ dàng để đề xuất chỉnh sửa.
Lợi ích của việc sử dụng tệp Markdown:
- URL gọn gàng để 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ô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 tệp này ngay cả khi tác giả không còn ở đó.
- 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 bị hỏng, tìm nạp danh sách tác giả, v.v.).
Bạn có thể chọn thử nghiệm nhiều lần 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. Mẫu này bao gồm tiêu đề cần thiết và tạo tính nhất quán về mặt hình ảnh với các tài liệu liên quan khác của Bazel. Để thực hiện việc nà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ế.
Để giúp mọi người có thể đọc đượ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 bình luận trên tài liệu, thì bất kỳ ai cũng có thể bình luận ẩ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 yêu cầu kéo để 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 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á bình luận, 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 chịu 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 này đã sẵn sàng để xem xét.
Trong quá trình xem xét
- Tham gia đối thoại với tác giả thiết kế về những vấn đề có vấn đề hoặc cần 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ế này bình luận.
- Quyết định những nhận xét mà tác giả phải giải quyết như một điều kiện tiên quyết để 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 các thiết kế đó 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 việc triển khai một thiết kế đang chờ xử lý. Nếu không thể thực hiện việc này, bạn nên xác định một người đại diện phù hợp (giao lại yêu cầu kéo cho người đại diện) hoặc giao lại lỗi cho 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ế diễn ra một cách mang tính xây dựng.
- Trước khi phê duyệt, hãy đảm bảo rằng các mối lo ngại của những người đánh giá khác đã được giải quyết.
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 trên danh sách gửi thư.
- Đảm bảo rằng yêu cầu kéo 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.
Từ chối thiết kế
- Đảm bảo tác giả yêu cầu kéo gửi yêu cầu kéo; hoặc gửi cho họ một yêu cầu kéo.
- Yêu cầu kéo 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 ra 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").