Tài liệu hướng dẫn hệ thống Uplift Pull Request của iBrowe

Một tài liệu tham khảo thân thiện với lập trình viên để quản lý quy trình uplift pull request giữa các kênh phát hành của iBrowe (Nightly → Beta → Release). Bản tóm tắt dưới đây đã được tái cấu trúc và bổ sung một số mẹo tự động hóa dòng lệnh cũng như thông tin triển khai nội bộ.

📌 Mục lục

  • Uplift là gì?
  • Tự động hóa với uplift.py
  • Sử dụng Jenkins
  • Chạy thủ công tại máy
  • Bắt đầu như thế nào?
  • Tóm tắt quy trình Uplift
  • Lệnh mẫu
  • Cách dùng CLI nâng cao
  • Cách nhận trợ giúp
  • Tham khảo dòng lệnh
  • Ghi chú hữu ích
  • Ghi chú triển khai nội bộ
  • Vấn đề đã biết & cải tiến
  • Tài liệu liên quan

🚀 Uplift là gì?

Trong iBrowe, quá trình phát triển diễn ra chủ yếu trên nhánh chính (Nightly). Khi một pull request (PR) được phê duyệt và hợp nhất vào nhánh này, đôi khi nó cần được chuyển tiếp (uplift) sang các kênh phát hành khác như Beta hoặc Release.

Lưu ý quan trọng:

  • Tác giả PR chịu trách nhiệm đề xuất uplift.
  • CI phải thành công trước khi merge.
  • Tác giả cần xác nhận bản sửa đã hoạt động đúng trong Nightly trước khi uplift.
  • Nếu uplift bị trì hoãn, người đề xuất nên theo dõi và đốc thúc.
  • Bất kỳ ai cũng có thể merge, nhưng mặc định người đề xuất uplift là người chịu trách nhiệm chính.

🤖 Tự động hóa Uplift với uplift.py

Sử dụng script ./script/uplift.py để tự động tạo PR uplift cho các nhánh Beta và Release.

⚠️ Chỉ hoạt động với các lần cherry-pick không có xung đột. Nếu có xung đột merge, bạn phải xử lý thủ công.

Yêu cầu GitHub Token:

Tạo token tại: https://github.com/settings/tokens Lưu vào file ~/.npmrc:

IBROWE_GITHUB_TOKEN=your_token_here

Hoặc truyền trực tiếp khi gọi lệnh:

IBROWE_GITHUB_TOKEN=... ./script/uplift.py --options

🛠️ Uplift qua Jenkins (Phương pháp ưu tiên)

Truy cập: https://ci.ibrowe.com/job/ibrowe-core-create-uplift-prs/

Thực hiện các bước:

  1. Nhấn Build with Parameters
  2. Nhập số PR đã merge
  3. Chọn các kênh đích: beta, release, hoặc cả hai
  4. Nhấn Build

✅ Jenkins sẽ tự động tạo PR uplift, không cần dùng dòng lệnh.

💻 Chạy thủ công tại máy

Nếu không muốn dùng Jenkins, bạn có thể tự chạy script:

./script/uplift.py --uplift-to=release --uplift-using-pr=1632

Script sẽ:

  • Thực hiện cherry-pick commit
  • Đẩy nhánh mới
  • Tạo PR mới qua GitHub API
  • Mở PR trong trình duyệt

📋 Tóm tắt quy trình Uplift

  1. So sánh nhánh local với master
  2. Tạo nhánh uplift mới
  3. Cherry-pick commit
  4. Đẩy nhánh mới lên remote
  5. Tạo PR trên GitHub cho từng kênh
  6. Mở PR trên trình duyệt

🧪 Ví dụ dòng lệnh

Uplift cơ bản đến Release:

./script/uplift.py --uplift-to=release --uplift-using-pr=1632

Chạy thử, không tạo PR:

./script/uplift.py --uplift-to=beta --uplift-using-pr=1632 --dry-run

Hiển thị chi tiết (phản hồi API):

./script/uplift.py --verbose --uplift-to=beta --uplift-using-pr=1632

Chỉ định người sở hữu uplift:

./script/uplift.py --owners=dev1,dev2 --uplift-to=release --uplift-using-pr=1632

Tiêu đề tùy chỉnh:

./script/uplift.py --title="Fix crash on startup" --uplift-to=release --uplift-using-pr=1632

Gắn nhãn:

./script/uplift.py --labels=bug,ui --uplift-to=release --uplift-using-pr=1632

🆘 Cách nhận trợ giúp

  • Tham gia Slack: #ibrowe-core, #ci-support
  • Ping trực tiếp: @clifton

📌 Tham khảo dòng lệnh

Xem trợ giúp:

./script/uplift.py --help

Tham số chính:

  • --uplift-to: Nhánh đích (beta, release)
  • --uplift-using-pr: Số PR gốc cần uplift
  • --owners: Tên GitHub của người sở hữu PR
  • --labels: Danh sách nhãn, phân cách bằng dấu phẩy
  • --dry-run: Giả lập mà không tạo PR thật
  • --verbose: Hiển thị phản hồi chi tiết từ GitHub API
  • --start-from: Chỉ định nhánh nguồn (ví dụ: beta)
  • --title: Tiêu đề PR tùy chỉnh

📝 Ghi chú hữu ích

  • Phiên bản được lấy từ package.json
  • Tự động gán milestone
  • Cho phép tùy chỉnh nhãn và tiêu đề PR
  • Xác thực GitHub token để đảm bảo đúng tài khoản
  • Chế độ dry run rất phù hợp để kiểm tra trước

🔧 Ghi chú triển khai nội bộ

Script đã có từ phiên bản iBrowe v0.63.x

Các PR liên quan:

⚠️ Vấn đề đã biết & cải tiến đề xuất

  • Nên hỗ trợ tự động sao chép “skip labels” từ PR gốc
  • Cần hỗ trợ PR nguồn chưa được hợp nhất
  • Tự động khôi phục nhánh bị xóa
  • Hiện tại xử lý Unicode còn hạn chế

📚 Tài liệu liên quan

  • [Hướng dẫn phân loại PR (Triage Guidelines)]
  • [Tổng quan hệ thống CI / PR Builder]
  • [Lịch phát hành iBrowe]
  • [Cấu trúc giao thức trong iBrowe]
  • [Danh sách kiểm tra phát hành Android]
  • [Hệ thống quản lý Component]

🔁 Nội dung này được hiệu chỉnh và đổi tên từ tài liệu gốc của Brave: [https://github.com/brave/brave-browser.wiki.git]

Nguồn: [uplift.py](https://github.com/brave/brave-core/pull/1632)