Nếu bạn 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.
Dưới đây là một số ví dụ về những thay đổi đáng kể:
- Thêm hoặc xoá các quy tắc xây dựng gốc
- Các thay đổi có thể gây ra lỗi cho các quy tắc gốc
- Thay đổ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
- Các 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ác 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, WORKSPACE hoặc bzl, hãy thêm nhóm Starlark làm người xem xét. 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ả đá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 triển khai bởi những người không thuộc nhóm cốt lõi; 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ó 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.
Để 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ế 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 chứ không phả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 để 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 xem xét 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 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 về Markdown / 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 xem xét chính. và sao chép những người xem xét khác. Nếu bạn không chọn người xem xét 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 xem xét có thể đưa ra nhận xét sơ bộ trong quá trình xem xét mã. Ví dụ: người xem xét chính có thể đề xuất thêm người xem xét hoặc chỉ ra thông tin bị thiếu. Người xem xét 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 đó 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).
Lặp lại với người xem xét
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â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 sẽ 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 lặp lại hoàn tất. Gửi yêu cầu kéo cho cùng một người xem xét chính và sao chép những người xem xét khác.
Để chính thức chấp nhận đề xuất, người xem xét chính sẽ phê duyệt yêu cầu kéo sau khi đảm bảo rằng những người xem xét 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ư 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 xem xét chính
Người xem xét 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ả trong việc tìm ý tưởng, vì bạn có thể dễ dàng bắt đầu.
- Chỉnh sửa theo nhóm.
- Lặp lại nhanh chóng.
- Dễ dàng đề xuất chỉnh sửa.
Lợi ích của việc sử dụng tệp Markdown:
- URL rõ rà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 các đườ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 lặp lại trước trên Google Tài liệu, 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 khác liên quan đến 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 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 xem xét 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 xem xét
Người xem xét 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 xem xét
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 xem xét.
- 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 thích hợp, hãy mời những người không phải là người xem xét 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 chúng không có trong chỉ mục thiết kế.
Trách nhiệm của người xem xét 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 uỷ quyền phù hợp (chỉ định lại yêu cầu kéo cho người uỷ quyền) hoặc chỉ định 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 xem xét khác đã được giải quyết.
Sau khi tất cả người xem xét 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").