Hướng dẫn cho nhà bảo trì sản phẩm Bazel

Bản dựng chạy vào ban đêm · 9.0 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Đây là hướng dẫn dành cho người duy trì dự án nguồn mở Bazel.

Nếu bạn muốn đóng góp cho Bazel, hãy đọc bài viết Đóng góp cho Bazel.

Mục tiêu của trang này là:

  1. Đóng vai trò là nguồn thông tin đáng tin cậy của người duy trì cho quy trình đóng góp của dự án.
  2. Đặt ra kỳ vọng giữa người đóng góp trong cộng đồng và người duy trì dự án.

Nhóm cộng tác viên cốt lõi của Bazel có các nhóm nhỏ chuyên trách để quản lý các khía cạnh của dự án nguồn mở. Đó là:

  • Quy trình phát hành: Quản lý quy trình phát hành của Bazel.
  • Nhóm Green: Giám sát tình trạng CI của Bazel và báo cáo sự cố.
  • Developer Experience Gardeners (Người chăm sóc trải nghiệm nhà phát triển): Khuyến khích các đóng góp bên ngoài, xem xét các vấn đề và yêu cầu kéo, đồng thời giúp quy trình phát triển của chúng tôi trở nên cởi mở hơn.

Bản phát hành

Tích hợp liên tục

Đọc hướng dẫn của nhóm Green về cơ sở hạ tầng CI của Bazel trên kho lưu trữ bazelbuild/continuous-integration.

Vòng đời của một vấn đề

  1. Người dùng tạo một vấn đề bằng cách chọn một trong các mẫu vấn đề và vấn đề đó sẽ được thêm vào nhóm vấn đề mở chưa được xem xét.
  2. Một thành viên trong nhóm luân phiên của nhóm phụ trách Trải nghiệm cho nhà phát triển (DevEx) sẽ xem xét vấn đề này.
    1. Nếu vấn đề không phải là lỗi hoặc yêu cầu về tính năng, thì thành viên DevEx thường sẽ đóng vấn đề đó và chuyển hướng người dùng đến StackOverflow và bazel-discuss để câu hỏi được chú ý hơn.
    2. Nếu vấn đề thuộc một trong các kho quy tắc do cộng đồng sở hữu, chẳng hạn như rules_apple, thành viên DevEx sẽ chuyển vấn đề này sang kho lưu trữ chính xác.
    3. Nếu vấn đề không rõ ràng hoặc thiếu thông tin, thành viên DevEx sẽ chỉ định lại vấn đề cho người dùng để yêu cầu thêm thông tin trước khi tiếp tục. Điều này thường xảy ra khi người dùng không chọn mẫu vấn đề phù hợp {: .external} hoặc cung cấp thông tin không đầy đủ.
  3. Sau khi xem xét vấn đề, nhân viên DevEx sẽ quyết định xem vấn đề đó có cần được chú ý ngay lập tức hay không. Nếu có, họ sẽ chỉ định nhãn P0 và một chủ sở hữu trong danh sách trưởng nhóm.
  4. Thành viên DevEx chỉ định nhãn untriaged và đúng một nhãn nhóm để định tuyến.
  5. Thành viên DevEx cũng chỉ định chính xác một nhãn type:, chẳng hạn như type: bug hoặc type: feature request, tuỳ theo loại vấn đề.
  6. Đối với các vấn đề dành riêng cho nền tảng, thành viên DevEx sẽ chỉ định một nhãn platform:, chẳng hạn như platform:apple cho các vấn đề dành riêng cho máy Mac.
  7. Nếu vấn đề có mức độ ưu tiên thấp và có thể được giải quyết bởi một thành viên mới của cộng đồng, thì thành viên DevEx sẽ chỉ định nhãn good first issue. Ở giai đoạn này, vấn đề sẽ được đưa vào nhóm vấn đề mở chưa được phân loại.

Mỗi nhóm nhỏ của Bazel sẽ phân loại tất cả các vấn đề theo nhãn mà họ sở hữu, tốt nhất là hằng tuần. Nhóm nhỏ này sẽ xem xét và đánh giá vấn đề, đồng thời đưa ra giải pháp (nếu có thể). Nếu bạn là chủ sở hữu của một nhãn nhóm, hãy xem phần này để biết thêm thông tin.

Khi một vấn đề được giải quyết, bạn có thể đóng vấn đề đó.

Vòng đời của một yêu cầu kéo

  1. Người dùng tạo một yêu cầu kéo.
  2. Nếu là thành viên của nhóm Bazel và gửi một PR cho khu vực của riêng bạn, bạn có trách nhiệm chỉ định nhãn nhóm và tìm người đánh giá phù hợp nhất.
  3. Nếu không, trong quá trình phân loại hằng ngày, một thành viên DevEx sẽ chỉ định một nhãn nhóm và trưởng nhóm kỹ thuật (TL) của nhóm để định tuyến.
    1. TL có thể chỉ định người khác xem xét PR (không bắt buộc).
  4. Người đánh giá được chỉ định sẽ xem xét yêu cầu kéo và làm việc với tác giả cho đến khi yêu cầu đó được phê duyệt hoặc bị loại bỏ.
  5. Nếu được phê duyệt, người xem xét sẽ nhập(các) cam kết của PR vào hệ thống kiểm soát phiên bản nội bộ của Google để kiểm thử thêm. Vì Bazel là hệ thống bản dựng giống với hệ thống được dùng nội bộ tại Google, nên chúng ta cần kiểm thử tất cả các cam kết PR dựa trên bộ kiểm thử nội bộ. Đây là lý do khiến chúng tôi không hợp nhất các yêu cầu kéo trực tiếp.
  6. Nếu cam kết được nhập vượt qua tất cả các kiểm thử nội bộ, thì cam kết đó sẽ được nén và xuất trở lại GitHub.
  7. Khi cam kết hợp nhất vào nhánh chính, GitHub sẽ tự động đóng yêu cầu kéo.

Nhóm của tôi sở hữu một nhãn. Tôi nên làm gì?

Các nhóm nhỏ cần phân loại tất cả các vấn đề trong những nhãn mà họ sở hữu, tốt nhất là hằng tuần.

Vấn đề

  1. Lọc danh sách vấn đề theo nhãn nhóm và nhãn untriaged.
  2. Xem xét vấn đề.
  3. Xác định mức độ ưu tiên và chỉ định nhãn.
    1. Vấn đề này có thể đã được nhóm DevEx ưu tiên nếu đó là vấn đề P0. Sắp xếp lại thứ tự ưu tiên nếu cần.
    2. Mỗi vấn đề cần có đúng một nhãn mức độ ưu tiên. Nếu một vấn đề là P0 hoặc P1, chúng tôi giả định rằng vấn đề đó đang được xử lý.
  4. Xoá nhãn untriaged.

Xin lưu ý rằng bạn cần phải thuộc tổ chức bazelbuild để có thể thêm hoặc xoá nhãn.

Yêu cầu kéo

Yêu cầu kéo (PR) là cách chính để cộng tác viên bên ngoài tăng thêm giá trị cho Bazel. Là một dự án nguồn mở, điều quan trọng là phải đảm bảo rằng các yêu cầu kéo được xem xét và xử lý kịp thời cũng như hiệu quả.

  • Phân loại

    Thường xuyên xem xét các yêu cầu kéo đến có nhãn awaiting-review và nhãn nhóm của bạn. Bạn có thể thực hiện việc này bằng cách luân phiên hoặc tổ chức cuộc họp phân loại thường xuyên. Chúng tôi dự kiến mỗi yêu cầu hỗ trợ sẽ nhận được phản hồi ban đầu trong vòng 7 ngày làm việc.

  • Đáp

    • Nếu PR có vẻ ổn, hãy phê duyệt và áp dụng nhãn awaiting-PR-merge. Nhóm gTech sẽ nhập PR dưới dạng CL.
    • Nếu không, hãy gửi ý kiến phản hồi và thay thế nhãn awaiting-review bằng nhãn awaiting-user-response. Nhóm DevEx sẽ thường xuyên cập nhật nhãn nếu tác giả PR phản hồi.
    • Đối với các yêu cầu kéo có thay đổi lớn, hãy cân nhắc yêu cầu một tài liệu thiết kế hoặc một cuộc thảo luận trước đó trong một vấn đề.

  • Đóng

    Do nguồn lực có hạn, nên bạn cần đóng những yêu cầu kéo không đáp ứng các tiêu chuẩn của Bazel hoặc những yêu cầu mà chúng tôi không có khả năng xem xét hoặc duy trì.

    • Nếu PR không phù hợp với mục tiêu của Bazel, hãy đóng PR đó kèm theo lời giải thích.
    • Nếu PR quá lớn và phức tạp, hãy đóng PR đó và yêu cầu chia nhỏ thành các phần nhỏ hơn.
    • Nếu chất lượng mã PR không đáp ứng các tiêu chuẩn của chúng tôi, hãy đóng mã đó kèm theo lời giải thích.
    • Nếu chi phí bảo trì mã trong tương lai quá cao, hãy đóng mã đó kèm theo lời giải thích.
    • Nếu PR đã chờ phản hồi của người dùng trong một thời gian dài và người đóng góp chưa phản hồi, thì PR sẽ tự động được đánh dấu là cũ sau 30 ngày và đóng sau 30 ngày nữa.

    Khi đóng một yêu cầu kéo, hãy lịch sự và giải thích lý do đóng.

Mức độ ưu tiên

Người duy trì sẽ sử dụng các định nghĩa sau đây về mức độ ưu tiên để phân loại vấn đề.

  • P0 – Chức năng chính bị hỏng khiến bản phát hành Bazel (trừ bản phát hành ứng cử viên) không sử dụng được hoặc dịch vụ ngừng hoạt động ảnh hưởng nghiêm trọng đến quá trình phát triển dự án Bazel. Điều này bao gồm cả những lỗi hồi quy xuất hiện trong một bản phát hành mới, khiến một số lượng lớn người dùng không thể sử dụng hoặc một thay đổi lớn không tương thích và không tuân thủ chính sách về Thay đổi lớn. Không có giải pháp thay thế nào hiệu quả.
  • P1 – Lỗi nghiêm trọng hoặc tính năng cần được giải quyết trong bản phát hành tiếp theo, hoặc một vấn đề nghiêm trọng ảnh hưởng đến nhiều người dùng (bao gồm cả việc phát triển dự án Bazel), nhưng có giải pháp thay thế thiết thực. Thường không yêu cầu hành động ngay lập tức. Có nhu cầu cao và được lên kế hoạch trong lộ trình của quý hiện tại.
  • P2 – Lỗi hoặc tính năng cần được giải quyết nhưng hiện tại chúng tôi chưa thực hiện. Vấn đề ở mức độ trung bình trong phiên bản Bazel đã phát hành gây bất tiện cho người dùng cần được giải quyết trong bản phát hành sau này và/hoặc có giải pháp dễ dàng.
  • P3 – Bản sửa lỗi nhỏ hoặc bản cải tiến mong muốn có tác động nhỏ. Không được ưu tiên trong lộ trình của Bazel hoặc bất kỳ bản phát hành sắp tới nào, tuy nhiên, chúng tôi khuyến khích các đóng góp của cộng đồng.
  • P4 – Lỗi có mức độ ưu tiên thấp hoặc yêu cầu về tính năng khó có thể được giải quyết. Cũng có thể vẫn mở để có thể sắp xếp lại mức độ ưu tiên nếu có nhiều người dùng bị ảnh hưởng hơn.

Nhãn nhóm

  • team-Android: Vấn đề đối với nhóm Android
  • team-Bazel: Các vấn đề chung về sản phẩm/chiến lược của Bazel
  • team-CLI: Giao diện người dùng của bảng điều khiển
  • team-Configurability: Vấn đề dành cho nhóm Configurability. Bao gồm: Cấu hình bản dựng cốt lõi và hệ thống chuyển đổi. Không bao gồm: Thay đổi đối với cờ mới hoặc cờ hiện có
  • team-Core: Skyframe, truy vấn bazel, BEP, phân tích cú pháp lựa chọn, bazelrc
  • team-Documentation: Vấn đề dành cho nhóm Tài liệu
  • team-ExternalDeps: Xử lý phần phụ thuộc bên ngoài, Bzlmod, kho lưu trữ từ xa, tệp WORKSPACE
  • team-Loading-API: Tệp BUILD và quy trình xử lý macro: nhãn, package(), visibility, glob
  • team-Local-Exec: Vấn đề đối với nhóm Thực thi (Tại địa phương)
  • team-OSS: Vấn đề đối với nhóm Bazel OSS: quy trình cài đặt, phát hành, đóng gói Bazel, trang web, cơ sở hạ tầng tài liệu
  • team-Performance: Vấn đề đối với nhóm Hiệu suất của Bazel
  • team-Remote-Exec: Vấn đề đối với nhóm Thực thi (Từ xa)
  • team-Rules-API: API để viết các quy tắc/khía cạnh: nhà cung cấp, tệp chạy, thao tác, cấu phần phần mềm
  • team-Rules-CPP / team-Rules-ObjC: Các vấn đề đối với quy tắc C++/Objective-C, bao gồm cả logic quy tắc gốc của Apple
  • team-Rules-Java: Vấn đề đối với các quy tắc Java
  • team-Rules-Python: Các vấn đề đối với quy tắc Python gốc
  • team-Rules-Server: Các vấn đề đối với quy tắc phía máy chủ có trong Bazel
  • team-Starlark-Integration: Tích hợp Bazel và Starlark không dùng API. Bao gồm: cách Bazel kích hoạt trình thông dịch Starlark, Stardoc, tính năng chèn sẵn, mã hoá ký tự. Không bao gồm: Vấn đề về ngôn ngữ BUILD hoặc .bzl.
  • team-Starlark-Interpreter: Các vấn đề về trình thông dịch Starlark (mọi thứ trong java.net.starlark). Các vấn đề về API BUILD và .bzl (đại diện cho hoạt động tích hợp của Bazel với Starlark) sẽ nằm trong team-Build-Language.

Đối với các vấn đề mới, chúng tôi đã ngừng sử dụng nhãn category: * để thay bằng nhãn nhóm.

Xem danh sách đầy đủ các nhãn tại đây.