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 thay đổi đáng kể về kiến trúc đối với Bazel, bạn phải viết thiết kế tài liệu của bạn và được xem xét trước khi bạn có thể gửi nội dung thay đổi.
Sau đây là một số ví dụ về những thay đổi quan trọng:
- Thêm hoặc xoá quy tắc bản dựng gốc
- Các thay đổi có thể gây 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 so với một 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 những API mà Bazel sử dụng để kết nối với các hệ thống khác
- Các thay đổi đối với ngôn ngữ, ngữ nghĩa hoặc API của Starlark
- Những thay đổi có thể ảnh hưởng rộng rãi đến hiệu suất hoặc bộ nhớ của Bazel mức sử dụng (tốt hơn hoặc kém 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 cần xem xét thiết kế
Khi viết mộ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 khác của Bazel và nhờ nhóm nòng cốt của Bazel hướng dẫn. Ví dụ: khi đề xuất thêm, xoá hoặc sửa đổi bất kỳ hàm hoặc đối tượng nào có trong BUILD, WORKSPACE hoặc bzl, hãy thêm nhóm Starlark làm người đánh giá. Chúng tôi xem xét tài liệu thiết kế 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ộ dường như vô hại lại những hậu quả quan 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 phải không chỉ được đánh giá về tính khả thi về mặt kỹ thuật mà còn về tầm quan trọng đối 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 do những người không thuộc nhóm cốt lõi triển khai; những cộng tác viên như vậy có trình độ chuyên môn của Bazel rất khác nhau.
- Bản thân đội ngũ Bazel có nhiều trình độ chuyên môn; không có thành viên nào trong nhóm hiểu rõ mọi ngóc ngách 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 gây lỗi thay đổi.
Chính sách của Bazel về quy trình đánh giá thiết kế 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ó được cấp độ xem xét kỹ lưỡng cơ sở.
- 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ó thể không hiệu quả.
Để giúp bạn bắt đầu, hãy xem tài liệu thiết kế trong Kho lưu trữ các đề xuất Bazel. Thiết kế đang trong quá trình thiết kế nên thông tin chi tiết về việc triển khai có thể thay đổi theo thời gian và ý kiến phản hồi. Tài liệu thiết kế được xuất bản ghi lại thiết kế ban đầu, và không phải là những thay đổi liên tục khi thiết kế được triển khai. Luôn chuyển đến tài liệu về nội dung mô tả chức năng Bazel hiện tại.
Quy trình của cộng tác viên
Trong vai trò người đóng góp, bạn có thể viết tài liệu thiết kế, gửi yêu cầu lấy dữ liệu và yêu cầu người đánh giá cho đề xuất của bạn.
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á khách hàng tiềm năng
- trạng thái hiện tại (bản nháp, đang xem xét, đã phê duyệt, bị từ chối, đang được triển khai, được triển khai)
- đường liên kết đến chuỗi thảo luận (sẽ được thêm sau thông báo)
Giấy tờ này có thể được viết dưới dạng một tệp Google Tài liệu dễ đọc hoặc bằng Markdown. Hãy đọc phần giới thiệu dưới đây để biết So sánh đánh dấu với Google Tài liệu.
Đề xuất có tác động mà người dùng có thể nhận thấy phải có một phần nêu rõ mức tác động đến khả năng tương thích ngược (và lập kế hoạch triển khai nếu cần).
Tạo một 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 một đường liên kết đến tài liệu đến PR của bạn.
Khi có thể, hãy chọn một người đánh giá khách hàng tiềm năng. và cc cho những người đánh giá khác. Nếu bạn không chọn người đánh giá chính, Bazel người bảo trì sẽ chỉ định một mã cho PR của bạn.
Sau khi bạn tạo nội dung PR, nhân viên đánh giá có thể đưa ra nhận xét sơ bộ trong xem xét mã. Ví dụ: người đánh giá của khách hàng tiềm năng 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ọ 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 này hoàn hảo hoặc sẽ được phê duyệt; có nghĩa là đề xuất chứa đủ thông tin để hãy bắt đầu thảo luận.
Thông báo đề 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ụ: thảo luận về ứng dụng tự nhiên, để nhận phản hồi từ người dùng cuối của Bazel).
Lặp lại với người đánh giá
Bất kỳ ai quan tâm đều có thể nhận xét về đề xuất của bạn. Hãy 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.
Nội dung thảo luận nên diễn ra trong chuỗi thông báo. Nếu đề xuất ở trong một Google Tài liệu, nhận xét có thể được sử dụng thay thế (Xin lưu ý rằng nhận xét ẩn danh được phép).
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 lặp lại là đã hoàn tất. Gửi PR cho cùng một người đánh giá khách hàng tiềm năng rồi 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 quảng cáo đó sau đảm bảo rằng những người đánh giá khác đồng ý với quyết định.
Phải có ít nhất 1 tuần giữa lần thông báo đầu tiên và thời điểm phê duyệt mộ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 quan ngại của mình.
Việc triển khai có thể bắt đầu trước khi đề xuất được chấp nhận, chẳng hạn như khi bằng chứng về khái niệm hoặc một thử nghiệm. Tuy nhiên, bạn không thể gửi nội dung thay đổi này trước khi quá trình xem xét hoàn tất.
Chọn người đánh giá khách hàng tiềm năng
Người đánh giá khách hàng tiềm năng phải là một chuyên gia về miền và:
- Có kiến thức về các hệ thống phụ 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ó sẵn trong toàn bộ thời gian xem xét để 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óm nhãn.
Markdown so với Google Tài liệu
Hãy xác định phương án nào phù hợp nhất với bạn, vì cả hai phương thức đề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 lên ý tưởng vì dễ dàng bắt đầu.
- Chỉnh sửa mang tính 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:
- Không có URL để liên kết.
- Hồ sơ 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 được bằng các công cụ tìm kiếm.
- Chuẩn bị cho tương lai: Văn bản thuần tuý không lợi cho bất kỳ công cụ cụ thể nào và không yêu cầu kết nối Internet.
- Có thể cập nhật chúng ngay cả khi tác giả không có mặt nữa.
- Chúng 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.).
Trước tiên, bạn có thể chọn lặp lại trên một tệp Google Tài liệu rồi chuyển đổi thành Đánh dấu để sử dụng sau này.
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. Thẻ này bao gồm tiêu đề cần thiết và tạo hình ảnh nhất quán với các tài liệu khác có liên quan đến Bazel. Để thực hiện 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 tài liệu thiết kế mẫu.
Để 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... và chọn "Bật - Bất kỳ ai có liên kết". Nếu bạn cho phép nhận xét trên tài liệu, 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 GitHub của Markdown (Thông số kỹ thuật).
Tạo một PR để cập nhật tài liệu hiện có. Những thay đổi đáng kể sẽ được nhân viên đánh giá tài liệu xem xét. Những thay đổi không đáng kể (chẳng hạn như lỗi chính tả, định dạng) có thể được bất kỳ ai phê duyệt.
Quy trình của người đánh giá
Nhân viên đánh giá sẽ 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 các tài liệu thiết kế và yêu cầu các tài liệu bổ sung nếu cần và phê duyệt thiết kế vượt qua quy trình đánh giá.
Khi bạn nhận được một đề xuất mới
- Hãy xem nhanh tài liệu.
- Nhận xét nếu thiếu thông tin quan trọng hoặc nếu thiết kế không vừa với mục tiêu của dự án.
- Đề xuất người đánh giá khác.
- Phê duyệt PR khi PR đã sẵn sàng để đánh giá.
Trong quá trình xem xét
- Trao đổi với tác giả thiết kế về các vấn đề có vấn đề hoặc yêu cầu làm rõ.
- Nếu thích hợp, hãy mời những người không phải người đánh giá nhận xét, những người này cần được biết về thiết kế.
- Quyết định những nhận xét phải được tác giả giải quyết như một điều kiện tiên quyết để phê duyệt.
- Viết "LGTM" (Có vẻ tốt với tôi) 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 đối với tất cả các yêu cầu đánh giá thiết kế. Không phê duyệt thiết kế ảnh hưởng đến Bazel nếu họ không ở trong chỉ mục thiết kế.
Trách nhiệm của người đánh giá khách hàng tiềm năng
Bạn chịu trách nhiệm đưa ra quyết định đi / không sử dụng khi triển khai của 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 người được uỷ quyền phù hợp (chỉ định lại PR cho người được uỷ quyền) hoặc chỉ định lại lỗi cho Quản lý của Bazel để có định hướng phù hợp hơn.
Trong quá trình xem xét
- Đảm bảo rằng quá trình lặp lại nhận xét và thiết kế tiếp tục diễn ra mang tính xây dựng.
- Trước khi phê duyệt, hãy đảm bảo rằng những người đánh giá khác đã lo ngại đã được giải quyết.
Sau khi được tất cả người đánh giá phê duyệt
- Hãy đảm bảo bạn đã thông báo trên trang web được ít nhất 1 tuần danh sách gửi thư.
- Hãy đảm bảo PR cập nhật trạng thái.
- Phê duyệt PR do tác giả đề xuất gửi.
Từ chối thiết kế
- Đảm bảo rằng tác giả PR gửi một PR; hoặc tuyên truyền cho họ.
- PR 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ế trong trạng thái hiện tại của báo cáo và chỉ ra các bước tiếp theo, nếu có (chẳng hạn như "xem lại tài khoản không hợp lệ giả định và gửi lại").