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