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 thay đổi đáng kể về kiến trúc đối với Bazel, 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 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 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
- Các thay đổi có thể ảnh hưởng sâu rộng đến hiệu suất Bazel hoặc mức sử dụng bộ nhớ (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 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à nhờ nhóm chính của Bazel hướng dẫn. 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, 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 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 đối với các yêu cầu khác về tính năng.
- Những người không thuộc nhóm chính thường xuyên triển khai các tính năng của Bazel; những người đóng góp như vậy có trình độ chuyên môn của Bazel rất đa dạng.
- Bản thân đội ngũ Bazel có nhiều cấp độ chuyên môn khác nhau; không một thành viên nào trong nhóm có thể 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 các thay đổi có thể gây lỗ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ẽ tham gia thiết kế trước khi chúng tôi đầu tư vào một phương án 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. Các thiết kế đang trong quá trình thiết kế, vì vậy, thông tin triển khai có thể thay đổi theo thời gian và kèm 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 phải thay đổi liên tục khi thiết kế được triển khai. Luôn chuyển đến tài liệu mô tả chức năng hiện tại của Bazel.
Quy trình của cộng tác viên
Với tư cách 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 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 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)
Tài liệu đó có thể được viết dưới dạng một tệp Google Tài liệu dễ đọc hoặc sử dụng Markdown. Hãy đọc phần bên dưới để biết cách 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 ghi lại tác động đối với khả năng tương thích ngược (và một kế hoạch phát hành 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 vào tài liệu quan hệ công chúng 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, thì người duy trì Bazel sẽ chỉ định một người cho bộ phận quan hệ công chúng của bạn.
Sau khi bạn tạo bài PR, nhân viên đá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á 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. Trưởng nhóm đánh giá sẽ phê duyệt nội dung 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à là đề xuất chứa đủ thông tin để bắt đầu cuộc thảo luận.
Thông báo đề xuất mới
Gửi thông báo cho bazel-dev khi gửi thông báo PR.
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 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 nằm trong Google Tài liệu, thì 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 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 PR sau khi đả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 đề xuất được phê duyệ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ọ.
Quá trình triển khai có thể bắt đầu trước khi đề xuất được chấp nhận, chẳng hạn như để chứng minh 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á 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 danh bạ để tìm nhiều nhãn nhóm.
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.
- Các yêu cầu 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.).
Trước tiên, bạn có thể chọn lặp lại trên 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. Công cụ này bao gồm tiêu đề cần thiết và tạo sự 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 đó, 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 mẫu tài liệu thiết kế.
Để 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 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 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 quan trọng sẽ được nhân viên đá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 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ế, yêu cầu cung cấp thêm thông tin nếu cần và phê duyệt một thiết kế vượt qua quá trình xem xét.
Khi bạn nhận được một đề xuất mới
- Hãy xem nhanh tài liệu.
- Hãy nhận xét nếu thiếu thông tin quan trọng hoặc 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.
- Phê duyệt PR khi PR đã sẵn sàng để đánh giá.
Trong quá trình xem xét
- Tham gia đối thoại với tác giả thiết kế về các vấn đề có vấn đề hoặc cần làm rõ.
- Nếu thích hợp, hãy mời nhận xét của những người không phải người đánh giá (những người này cần nắm được thiết kế này).
- Quyết định những nhận xét mà tác giả phải giải quyết là một điều kiện tiên quyết để phê duyệt.
- Viết "LGTM" (Có vẻ tốt cho tôi) vào 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 những 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á khách hàng tiềm năng
Bạn chịu trách nhiệm đưa ra quyết định di chuyển / không sử dụng đối với việc triển khai 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 được uỷ quyền phù hợp (chỉ định lại PR cho người được uỷ quyền) hoặc giao lại lỗi cho người quản lý Bazel để sắp xếp thêm.
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ế sẽ tiến triển một cách có tính xây dựng.
- Trước khi phê duyệt, hãy đảm bảo rằng bạn đã giải quyết xong mối lo ngại của những người đánh giá khác.
Sau khi được tất cả người đánh giá phê duyệt
- Hãy đảm bảo rằng đã có ít nhất 1 tuần kể từ khi thông báo xuất hiện trong 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ả quan hệ công chúng gửi một PR; hoặc gửi cho họ một PR.
- PR cập nhật trạng thái của giấy tờ.
- 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, đồng thời 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").