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

Nightly · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

Đâ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ì về quy trình đóng góp cho dự án.
  2. Đặt ra kỳ vọng giữa những người đóng góp trong cộng đồng và người duy trì dự án.

Nhóm đóng góp cốt lõi của Bazel có các nhóm phụ 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 các sự cố.
  • Nhóm Developer Experience Gardeners: 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 xem xét, đồ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 đưa vào nhóm các vấn đề mở chưa được xem xét.
  2. Một thành viên trong nhóm phụ Trải nghiệm cho nhà phát triển (DevEx) sẽ xem xét vấn đề đó.
    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 để tăng khả năng hiển thị cho câu hỏi.
    2. Nếu vấn đề thuộc một trong các kho lưu trữ quy tắc do cộng đồng sở hữu, chẳng hạn như rules_apple, thì 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ì 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 đúng mẫu vấn đề {: .external} hoặc cung cấp thông tin không đầy đủ.
  3. Sau khi xem xét vấn đề, thành viên DevEx sẽ quyết định xem vấn đề đó có cần được giải quyết ngay hay không. Nếu có, họ sẽ chỉ định nhãn P0 ưu tiên 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 đúng một type: nhãn, chẳng hạn như type: bug hoặc type: feature request, theo loại vấn đề.
  6. Đối với các vấn đề cụ thể về 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 đề cụ thể về Mac.
  7. Nếu vấn đề có mức độ ưu tiên thấp và người đóng góp mới trong cộng đồng có thể giải quyết, 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 các vấn đề mở chưa được phân loại.

Mỗi nhóm phụ của Bazel sẽ phân loại tất cả các vấn đề có nhãn mà họ sở hữu, tốt nhất là hằng tuần. Nhóm phụ 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 xem xét

  1. Người dùng tạo một yêu cầu xem xét.
  2. Nếu bạn là thành viên của một nhóm Bazel và gửi yêu cầu xem xét đối với khu vực của riêng mình, thì bạn có trách nhiệm chỉ định nhãn nhóm và tìm người xem xét phù hợp nhất.
  3. Nếu không, trong quá trình phân loại hằng ngày, 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ể tuỳ ý chỉ định người khác xem xét yêu cầu xem xét.
  4. Người xem xét được chỉ định sẽ xem xét yêu cầu xem xét 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 yêu cầu xem xét 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 xây dựng giống nhau được sử dụng nội bộ tại Google, nên chúng tôi cần kiểm thử tất cả các cam kết của yêu cầu xem xét dựa trên bộ kiểm thử nội bộ. Đây là lý do chúng tôi không hợp nhất trực tiếp các yêu cầu xem xét.
  6. Nếu cam kết đã nhập vượt qua tất cả các bài 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 xem xét.

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

Các nhóm phụ cần phân loại tất cả các vấn đề có 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. Nhóm phụ DevEx có thể đã ưu tiên vấn đề đó nếu đó là vấn đề P0. Hãy ưu tiên lại nếu cần.
    2. Mỗi vấn đề cần có đúng một nhãn ư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 tích cực giải quyết.
  4. Xoá nhãn untriaged.

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

Yêu cầu xem xét

Yêu cầu xem xét (PR) là cách chính để những người đóng góp 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 xem xét được xem xét và xử lý một cách kịp thời và hiệu quả.

  • Phân loại

    Thường xuyên xem xét các yêu cầu xem xét đế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 hy vọng mỗi yêu cầu xem xét sẽ nhận được phản hồi ban đầu trong vòng 7 ngày làm việc.

  • Đáp

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

  • Đóng

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

    • Nếu yêu cầu xem xét không phù hợp với mục tiêu của Bazel, hãy đóng yêu cầu đó và giải thích lý do.
    • Nếu yêu cầu xem xét quá lớn và phức tạp, hãy đóng yêu cầu đó và yêu cầu chia thành các phần nhỏ hơn.
    • Nếu chất lượng mã của yêu cầu xem xét không đáp ứng các tiêu chuẩn của chúng tôi, hãy đóng yêu cầu đó và giải thích lý do.
    • Nếu chi phí bảo trì mã trong tương lai quá cao, hãy đóng yêu cầu đó và giải thích lý do.
    • Nếu yêu cầu xem xét đã 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 không phản hồi, thì yêu cầu xem xét sẽ tự động được đánh dấu là lỗi thời sau 30 ngày và đóng sau 30 ngày nữa.

    Khi đóng một yêu cầu xem xét, 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 về mức độ ưu tiên để phân loại vấn đề.

  • P0 – Chức năng bị hỏng nghiêm trọng khiến bản phát hành Bazel (trừ ứng viên phát hành) không sử dụng được hoặc dịch vụ bị ngừng hoạt động gây ả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ả các lỗi hồi quy được giới thiệu trong bản phát hành mới chặn một số lượng lớn người dùng hoặc thay đổi mang tính đột phá không tương thích và không tuân thủ Chính sách về thay đổi mang tính đột phá. Không có giải pháp tạm thời thực tế nào.
  • P1 – Lỗi hoặc tính năng quan trọng cần được giải quyết trong bản phát hành tiếp theo hoặc vấn đề nghiêm trọng ảnh hưởng đến nhiều người dùng (bao gồm cả quá trình phát triển dự án Bazel), nhưng có giải pháp tạm thời thực tế. 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 chúng tôi hiện không giải quyết. Vấn đề trực tiếp ở mức độ vừa phải 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 trong tương lai và/hoặc có giải pháp tạm thời dễ dàng.
  • P3 – Bản sửa lỗi nhỏ hoặc cải tiến đáng 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 Bạn cũng có thể giữ trạng thái mở để có thể ưu tiên lại nếu có nhiều người dùng bị ảnh hưởng hơn.

Nhãn nhóm

  • team-Android: Các vấn đề của 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 bảng điều khiển
  • team-Configurability: Các vấn đề của 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: Các 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 tuỳ chọn, bazelrc
  • team-Documentation: Các vấn đề của nhóm Documentation
  • 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à xử lý macro: nhãn, package(), khả năng hiển thị, glob
  • team-Local-Exec: Các vấn đề của nhóm Execution (Local)
  • team-OSS: Các vấn đề của nhóm Bazel OSS: cài đặt, quy trình phát hành, đóng gói Bazel, trang web, cơ sở hạ tầng tài liệu
  • team-Performance: Các vấn đề của nhóm Bazel Performance
  • team-Remote-Exec: Các vấn đề của nhóm Execution (Remote)
  • team-Rules-API: API để viết các quy tắc/khía cạnh: nhà cung cấp, runfiles, hành động, cấu phần phần mềm
  • team-Rules-CPP / team-Rules-ObjC: Các vấn đề của quy tắc C++/Objective-C, bao gồm cả logic quy tắc Apple gốc
  • team-Rules-Java: Các vấn đề của quy tắc Java
  • team-Rules-Python: Các vấn đề của quy tắc Python gốc
  • team-Rules-Server: Các vấn đề của quy tắc phía máy chủ có trong Bazel
  • team-Starlark-Integration: Tích hợp Bazel + Starlark không phải API. Bao gồm: cách Bazel kích hoạt trình thông dịch Starlark, Stardoc, chèn builtins, mã hoá ký tự. Không bao gồm: Các vấn đề về ngôn ngữ BUILD hoặc .bzl.
  • team-Starlark-Interpreter: Các vấn đề của 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 tích hợp của Bazel với Starlark) 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: * để chuyển sang nhãn nhóm.

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