Thiết kế tài liệu

Nếu bạn định thêm, thay đổi hoặc xóa một tính năng mà người dùng nhìn thấy, hoặcthay đổi kiến trúc quan trọng tới Bazel, bạnphải hãy ghi lại tài liệu thiết kế và yêu cầu xem xét trước khi bạn có thể gửi thay đổi.

Dưới đây là một số ví dụ về những thay đổi quan trọng:

  • Thêm hoặc xóa quy tắc bản dựng gốc
  • Thay đổi vi phạm quy tắc gốc
  • Các thay đổi đối với ngữ nghĩa quy tắc của bản dựng ảnh hưởng đến nhiều hành động hơn so với một quy tắc duy nhất
  • Những thay đổi đối với API định nghĩa quy tắc của Bazel
  • Những thay đổi đối với 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 Starlark
  • Các thay đổi có thể ảnh hưởng lan tỏa đến hiệu suất của bộ nhớ Bazel hoặc bộ nhớ (để cải thiện hoặc kém hơn)
  • Những thay đổi đối với 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à nhận hướng dẫn từ nhóm cốt lõi của Bazel. Ví dụ: khi một đề xuất thêm, xóa hoặc sửa đổi bất kỳ chức năng 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 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 dường như vô hại ở địa phương có thể gây ra hậu quả đáng kể trên toàn cầu.
  • Nhóm sẽ 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ần đượ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 do những người bên ngoài nhóm cốt lõi triển khai. Các cộng tác viên đó có nhiều mức độ chuyên môn về Bazel.
  • Bản thân nhóm Bazel có nhiều cấp độ chuyên môn khác nhau; chưa có thành viên nào trong nhóm hiểu rõ 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 phá vỡ các thay đổi.

Chính sách đánh giá thiết kế của Bazel giúp tối đa hóa khả năng:

  • tất cả yêu cầu về tính năng đều được xem xét kỹ lưỡng hơn ở mức cơ bản.
  • những người phù hợp sẽ tập trung vào các thiết kế trước khi chúng tôi đầu tư vào một biện pháp triển khai có thể sẽ không mang lại 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 Brazil. Thiết kế đang hoàn thiện, vì vậy, chi tiết triển khai có thể thay đổi theo thời gian và có phản hồi. Các 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 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 Người đóng góp

Là một 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à người đánh giá yêu cầu đề xuất.

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 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, đã triển khai)
  • đường liên kết đến chuỗi thảo luận (sẽ thêm vào sau thông báo)

Bạn có thể viết tài liệu này dưới dạng một tệp Google Tài liệu dễ đọc trên toàn thế giới hoặc bằng cách sử dụng Markdown. Hãy đọc phần bên dưới để biết cách so sánh thẻ Đánh dấu / Google Tài liệu.

Các đề xuất có tác động hiển thị cho 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à kế hoạch phát hành nếu cần).

Tạo yêu cầu Lấy dữ liệu

Hãy 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 Markdown hoặc đường liên kết đến tài liệu vào PR của bạn.

Nếu có thể, hãy chọn người đánh giá chính. và cc người đánh giá khác. Nếu bạn không chọn người đánh giá là khách hàng tiềm năng, trình duy trì Bazel sẽ chỉ định một người đánh giá cho bộ phận 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 đánh giá mã. Ví dụ: người đánh giá tiềm năng có thể đề xuất thêm người đánh giá hoặc chỉ ra thông tin bị thiếu. Người đánh giá tiềm năng phê duyệt PR khi họ tin 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; điều đó 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 cho bazel-dev khi bạn gửi PR.

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 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. 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 quan 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, 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 quy trình lặp hoàn tất. Hãy gửi PR cho cùng 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á trưởng sẽ phê duyệt PR sau khi đảm bảo rằng những người đánh giá khác sẽ đồng ý với quyết định của họ.

Phải ít nhất 1 tuần giữa lần thông báo đầu tiên và 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ư thử nghiệm 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:

  • Kiến thức về 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ó sẵn trong toàn bộ khoảng thời gian xem xét để dẫn đầu quy trình

Hãy cân nhắc kiểm tra các liên hệ để biết các nhãn nhóm khác nhau.

Markdown so với Google Tài liệu

Quyết định điều gì là tốt 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:

  • Hiệu quả cho việc động não, vì bạn có thể dễ dàng bắt đầu sử dụng.
  • Cộng tác và chỉnh sửa.
  • 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:

  • Xóa các URL để liên kết.
  • Bản ghi sửa đổi rõ ràng.
  • 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 với các công cụ tìm kiếm.
  • Chống lại trong tương lai: Văn bản thuần túy không sử dụng 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 tệp này ngay cả khi tác giả không còn nữa.
  • Chúng có thể được xử lý tự động (cập nhật/phát hiện 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 quy trình trên Google Tài liệu và sau đó chuyển đổi sang Đánh dấu để 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ế Brazil. Phần này bao gồm tiêu đề cần thiết và tạo sự nhất quán về hình ảnh cho 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 tài liệu của bạn dễ đọc với mọi người, 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 trên 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 một PR để cập nhật một tài liệu hiện có. Những thay đổi đáng kể cần được người đánh giá tài liệu xem xét. Những thay đổi không cần thiết (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á

Người đánh giá nhận xét, đánh giá 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 quá trình xem xét.

Khi bạn nhận được một đề xuất mới

  1. Xem nhanh tài liệu.
  2. 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.
  3. Đề xuất người đánh giá khác.
  4. Phê duyệt PR khi PR sẵn sàng để xem xét.

Trong quá trình xem xét

  1. Thảo luận với tác giả thiết kế về các vấn đề gặp vấn đề hoặc yêu cầu làm rõ.
  2. Nếu thích hợp, hãy mời nhận xét từ những người không phải là người đánh giá, những người sẽ biết thiết kế.
  3. Quyết định xem tác giả phải đề cập đến nhận xét nào là điều kiện tiên quyết để phê duyệt.
  4. Viết "LGTM" (Có vẻ ổn) 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.

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 chịu trách nhiệm về việc đưa ra quyết định di chuyển / không thực hiện đối với việc triển khai thiết kế đang chờ xử lý. Nếu không thể làm việc này, bạn nên xác định người được ủy quyền phù hợp (ấn đị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ý Brazil để điều chỉnh thêm.

Trong quá trình xem xét

  1. Đảm bảo rằng quy trình lặp lại nhận xét và thiết kế mang tính xây dựng về trước.
  2. Trước khi phê duyệt, bạn hãy giải quyết 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

  1. Hãy đảm bảo ít nhất 1 tuần kể từ khi có thông báo về danh sách gửi thư.
  2. Đảm bảo PR cập nhật trạng thái.
  3. Chấp thuận PR do tác giả đề xuất gửi.

Từ chối thiết kế

  1. Đảm bảo tác giả của bộ phận Quan hệ công chúng gửi một PR; hoặc gửi cho họ quan hệ công chúng.
  2. PR cập nhật trạng thái của chứng từ.
  3. Thêm một 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ư "truy cập lại các giả định không hợp lệ và gửi lại").