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 thay đổi cấu trúc đáng kể đối với Bazel, 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 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 đối với 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 được triển khai bởi những người bên ngoài nhóm cốt lõi; những người đóng góp như vậy có nhiều cấp độ chuyên môn về Bazel.
- Bản thân đội 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 đánh giá thiết kế của Bazel 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 các tài liệu thiết kế trong Kho lưu trữ đề xuất về Bazel. Thiết kế đang trong quá trình hoàn thiện, 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ế đượ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 làm việc của người đóng góp
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ế đều 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)
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 trên thế giới đều đọc đượ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 trong 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õ ảnh hưởng đến khả năng tương thích ngược (và lập kế hoạch ra mắt 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 thay đổi.
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ì một người duy trì Bazel sẽ chỉ định người đánh giá cho yêu cầu phát hành của bạn.
Sau khi bạn tạo yêu cầu xem xét, 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á 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 yêu cầu xem xét khi họ cho 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; điều đó 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ụ: 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 đánh giá
Bất kỳ ai quan tâm đều có thể nhận xét 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 mối lo ngại.
Cuộc thảo luận phải diễn ra trên chuỗi thông báo. Nếu đề xuất ở trong một Google Tài liệu, thì có thể dùng nhận xét (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 quá trình lặp lại hoàn tất. Gửi thông cáo báo chí cho cùng một người đánh giá chính và 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 nội dung quảng bá sau khi đảm bảo rằng các 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 lần thông báo đầu tiên và lần 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 quan ngại của mình.
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 minh chứng về khái niệm hoặc 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 con 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ó 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 danh bạ để biết các 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 động não vì dễ bắt đầu.
- Chỉnh sửa 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.
- 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.
- 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.
- Bạn có thể cập nhật các bài viết đó ngay cả khi tác giả không còn hoạt động 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 Google Tài liệu, sau đó chuyển đổi tài liệu đó sang Markdown để lưu trữ.
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. Tệp này 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 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 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... 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, thì mọi người đều 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 (Thông số kỹ thuật).
Tạo một yêu cầu thay đổi để 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. Bất kỳ ai cũng có thể phê duyệt các thay đổi nhỏ (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á
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 tài liệu thiết kế, yêu cầu 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 đề xuất mới
- Xem nhanh tài liệu.
- Hãy 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 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
- Trò chuyện với tác giả thiết kế về các vấn đề cần giải thích hoặc có vấn đề.
- Nếu thích 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 những bình luận mà tác giả phải giải quyết trước khi được 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á chính
Bạn chịu trách nhiệm đưa ra quyết định triển khai/không 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 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 bạn đã giải quyết xong các mối lo ngại của các người đánh giá khác.
Sau khi 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 trên danh sách gửi thư.
- Đảm bảo thông tin cập nhật trạng thái trong bản phát hành công khai.
- 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ọ.
- Thông cáo báo chí sẽ 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 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").