คู่มือระบบ Uplift Pull Request ใน iBrowe (iBrowe Pull Request Uplift System Guide)

เอกสารนี้เป็น คู่มือสำหรับนักพัฒนา เพื่อจัดการกระบวนการ Uplift Pull Request ข้าม Release Channel ต่าง ๆ ของ iBrowe (Nightly → Beta → Release) โดยมีการเขียนใหม่และจัดโครงสร้างใหม่ พร้อมเทคนิคการใช้คำสั่งอัตโนมัติและรายละเอียดการใช้งานจริง

📌 สารบัญ (Table of Contents)

  • Uplifts คืออะไร?
  • การทำงานอัตโนมัติด้วย uplift.py
  • ใช้งานผ่าน Jenkins
  • การรัน Script บนเครื่อง (Local)
  • เริ่มต้นใช้งาน (Getting Started)
  • สรุปขั้นตอน Uplift Workflow
  • ตัวอย่างคำสั่ง (Example Commands)
  • การใช้งาน CLI ขั้นสูง (Advanced CLI Usage)
  • การขอความช่วยเหลือ (Getting Help)
  • อ้างอิงคำสั่ง CLI (Command-Line Reference)
  • หมายเหตุสำคัญ (Helpful Notes)
  • การทำงานภายในระบบ (Internal Implementation Notes)
  • ปัญหาที่ทราบและแนวทางปรับปรุง (Known Issues & Improvements)
  • เอกสารที่เกี่ยวข้อง (Related Docs)

🚀 Uplifts คืออะไร? (What Are Uplifts?)

ใน iBrowe การพัฒนาจะเกิดขึ้นบน branch main (Nightly) เมื่อตรวจสอบและ merge Pull Request (PR) แล้ว อาจจำเป็นต้อง พอร์ต (port) หรือ Uplift PR นั้นไปยัง channel อื่น เช่น beta หรือ release

  • ผู้เขียน PR มีหน้าที่ส่ง uplift เอง
  • ต้องให้ CI ผ่านก่อน merge
  • ผู้เขียน PR ต้องยืนยันว่าการแก้ไขใช้งานได้บน Nightly ก่อนจะ Uplift
  • หาก uplift ค้าง ต้องมีคนกระตุ้นให้ดำเนินการต่อ
  • ใครก็ merge ได้ แต่โดยปกติ uplift owner ต้องรับผิดชอบ

🤖 การทำ Uplift แบบอัตโนมัติด้วย uplift.py (Automating Uplifts with uplift.py)

ใช้ script ./script/uplift.py เพื่อสร้าง Uplift PR สำหรับ branch Beta หรือ Release ได้แบบอัตโนมัติ

หมายเหตุ: ใช้ได้เฉพาะกรณี cherry-pick ได้สะอาด (clean cherry-picks) ถ้ามี merge conflict ต้องแก้เอง

ต้องใช้ GitHub Token:

สร้างได้ที่: https://github.com/settings/tokens บันทึกใน ~/.npmrc แบบนี้:

IBROWE_GITHUB_TOKEN=your_token_here

หรือส่งค่าแบบ inline:

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

🛠️ การทำ Uplift ผ่าน Jenkins (Jenkins-Based Uplifts) — แนะนำให้ใช้ เข้าไปที่: https://ci.ibrowe.com/job/ibrowe-core-create-uplift-prs/

  • คลิก Build with Parameters
  • กรอกหมายเลข PR ที่ merge แล้ว
  • เลือก channel ที่ต้องการ (beta, release หรือทั้งสอง)
  • กด Build ✨ Jenkins จะสร้าง PR ให้เองโดยอัตโนมัติ ไม่ต้องใช้ CLI

💻 การรัน Script บนเครื่อง (Running Locally) หากไม่ต้องการใช้ Jenkins สามารถรัน Script เองได้:

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

สิ่งที่จะเกิดขึ้น:

  • cherry-pick commit
  • push branch ใหม่
  • สร้าง PR ใหม่ผ่าน GitHub API
  • เปิด PR ใน browser ให้ทันที

📋 สรุปขั้นตอน Uplift Workflow (Uplift Workflow Summary)

  • เปรียบเทียบ branch local กับ master
  • สร้าง uplift branches
  • cherry-pick commits
  • push ขึ้น remote
  • สร้าง GitHub PR สำหรับแต่ละ channel
  • เปิด PR บน browser

🧪 ตัวอย่างคำสั่ง (Example Commands)

Uplift พื้นฐานไป Release:

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

Dry run (จำลอง ไม่สร้าง PR จริง):

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

แสดงผลละเอียด (Verbose):

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

ระบุ owners:

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

ตั้ง custom title:

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

เพิ่ม labels:

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

🆘 การขอความช่วยเหลือ (Getting Help)

  • สอบถามได้ที่ Slack ช่อง #ibrowe-core, #ci-support
  • ติดต่อ @clifton ใน Slack

📌 อ้างอิงคำสั่ง CLI (Command-Line Reference)

รันเพื่อดู options ทั้งหมด:

./script/uplift.py --help

Flags สำคัญ:

–uplift-to: ระบุ branch ปลายทาง (beta, release)

–uplift-using-pr: หมายเลข PR ที่ต้องการ uplift

–owners: ระบุ GitHub username ของเจ้าของ PR

–labels: ระบุ labels (comma-separated)

–dry-run: จำลองโดยไม่สร้าง PR จริง

–verbose: แสดงผลลัพธ์ละเอียด (GitHub API)

–start-from: ระบุ base branch (เช่น beta)

–title: ตั้งชื่อ PR เอง

📝 หมายเหตุสำคัญ (Helpful Notes)

  • เวอร์ชันจะดึงจากไฟล์ package.json
  • การกำหนด milestone จะทำให้อัตโนมัติ
  • Labels และ title ปรับแต่งได้
  • ระบบตรวจ token GitHub ให้มั่นใจว่า username ถูกต้อง
  • ใช้ dry run เพื่อดูผลลัพธ์ก่อนสร้าง PR จริง

🔧 การทำงานภายใน (Internal Implementation) Script นี้ใช้งานมาตั้งแต่ iBrowe v0.63.x

PR สำคัญ:

⚠️ ปัญหาที่ทราบและแนวทางปรับปรุง (Known Issues & Enhancements)

  • ควรรองรับการ replicate “skip labels” จาก PR ต้นฉบับ
  • ควร support PR ต้นฉบับที่ยังไม่ merge
  • ควร restore branches ที่ถูกลบโดยอัตโนมัติ
  • การจัดการ Unicode ยังจำกัดอยู่

📚 เอกสารที่เกี่ยวข้อง (Related Documentation)

  • [Triage Guidelines]
  • [CI / PR Builder Overview]
  • [iBrowe Release Schedule]
  • [Protocol Schemes in iBrowe]
  • [Android Release Checklist]
  • [Components System]

ที่มา: ดัดแปลงและปรับโครงสร้างจากเอกสารของ Brave: https://github.com/brave/brave-browser.wiki.git Source: uplift.py