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 đáng kể về cấu trúc đối với Bazel, thì bạn phải viết tài liệu thiết kế và yêu cầu xem xét trước khi gửi nội dung thay đổi.
Dưới đâ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 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ể tác động lan toả đến hiệu suất hoặc mức sử dụng bộ nhớ của Bazel (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
- Các 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 khác của Bazel và nhờ nhóm nòng cốt 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 sẽ 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 hậu quả đáng kể trên toàn cầu.
- Nhóm này 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 đó không chỉ cần được đánh giá về tính khả thi về mặt kỹ thuật mà còn về mức độ 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 không thuộc nhóm nòng cốt triển khai; những người đóng góp này có kiến thức chuyên môn rất đa dạng.
- Bản thân nhóm Bazel có các trình độ chuyên môn khác nhau; không một thành viên nào trong nhóm có hiểu biết đầy đủ về mọi góc 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 cho các thay đổi.
Chính sách đá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 ở cấp độ cơ sở.
- những người phù hợp sẽ cân nhắc thiết kế trước khi chúng tôi đầu tư vào một triển khai 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ữ đề xuất của Bazel. Thiết kế đang trong quá trình thiết kế, vì vậy, thông tin chi tiết về cách triển khai có thể thay đổi theo thời gian và khi có ý kiến phản hồi. Các tài liệu thiết kế được xuất bản sẽ ghi lại thiết kế ban đầu chứ không phải những thay đổi đang diễn ra 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 làm việc của 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á 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:
- 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á chính
- trạng thái hiện tại (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 tới 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 tệp Google Tài liệu có thể đọc được trên toàn thế giới 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 / Google Tài liệu.
Các đề 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à kế hoạch triển khai nếu cần).
Tạo một yêu cầu lấy dữ liệu
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 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 đường liên kết đến tài liệu vào bài đánh giá 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á khách hàng tiềm năng, thì một công ty bảo trì Bazel sẽ chỉ định một người cho PR 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á chính 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ọ 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 phê duyệt; mà có nghĩa là đề xuất chứa đủ thông tin để bắt đầu cuộc thảo luận.
Công bố đề xuất mới
Gửi thông báo đến bazel-dev khi gửi 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.
Bạn nên thảo luận trong chuỗi thông báo. Nếu đề xuất nằm trong một Google Tài liệu, bạn có thể sử dụng nhận xét (Lưu ý rằng nhận xét ẩn danh được cho 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 vòng lặp hoàn tất. Gửi PR đến 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á 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 kể từ khi thông báo đầu tiên đến khi một đề xuất được phê duyệt. Điều này giúp đảm bảo 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, ví dụ: dưới dạng bằng chứng về ý tưởng 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:
- 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 phản hồi mang tính xây dựng
- Có sẵn trong toàn bộ giai đoạn xem xét để bắt đầu quy trình
Hãy cân nhắc kiểm tra danh bạ để biết nhiều nhãn nhóm khác nhau.
Markdown so với Google Tài liệu
Hãy quyết định cách phù hợp nhất với bạn vì cả hai hình thức này đề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ì bắt đầu dễ dàng.
- Chỉnh sửa mang tính cộng tác.
- Lặp lại nhanh.
- Cách dễ dàng để đề xuất chỉnh sửa.
Lợi ích của việc sử dụng tệp Markdown:
- Xoá các URL cần 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 với các công cụ tìm kiếm.
- Phù hợp với 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 dấu trang ngay cả khi tác giả không còn ở đây nữa.
- Hệ thống có thể tự động xử lý những báo cáo này (cập nhật/phát hiện đường liên kết bị hỏng, danh sách tìm nạp 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 thành Markdown để dùng sau.
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ài liệu 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 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... rồi 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ì 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 thẻ PR để cập nhật tài liệu hiện có. Những thay đổi đáng kể phải được người đánh giá tài liệu xem xét. 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 làm việc của người đánh giá
Nhân viên đánh giá 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 nhân viên đánh giá chung
Bạn có 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 mộ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.
- 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 PR đã sẵn sàng xem xét.
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 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 là người đánh giá đã nhận biết được thiết kế này.
- Quyết định nhận xét nào phải được tác giả giải quyết làm điều kiện tiên quyết để 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 làm theo quy trình này đối với mọi yêu cầu đánh giá 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 nhân viên đánh giá khách hàng tiềm năng
Bạn chịu trách nhiệm đưa ra quyết định chọn hoặc 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 (giao lại người được uỷ quyền) hoặc chỉ định lại lỗi cho người quản lý Bazel để có thể xử lý thêm.
Trong quá trình xem xét
- Hãy đảm bảo rằng quá trình lặp lại nhận xét và thiết kế tiến lên một cách 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 đánh giá khác đã được giải quyết.
Sau khi được tất cả người đánh giá phê duyệt
- Đảm bảo đã ít nhất 1 tuần kể từ khi có thông báo trong danh sách gửi thư.
- Đảm bảo rằng đối tác đó cập nhật trạng thái của đơn khiếu nạ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 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, cũng như 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ệ rồi gửi lại").