Conventional Branch 1.1.0
บทสรุป
Conventional Branch หมายถึงธรรมเนียมปฏิบัติในการตั้งชื่อ Branch ของ Git ที่มีโครงสร้างและเป็นมาตรฐาน ซึ่งมีจุดมุ่งหมายเพื่อให้ชื่อ Branch อ่านเข้าใจง่ายและสามารถนําไปปฏิบัติงานต่อได้สะดวกขึ้น เราได้แนะนําคํานําหน้า (Prefix) ของ Branch บางส่วนที่คุณอาจต้องการใช้งาน แต่คุณก็สามารถกําหนดรูปแบบการตั้งชื่อของคุณเองได้เช่นกัน รูปแบบการตั้งชื่อที่สม่ําเสมอจะช่วยให้ระบุประเภทของ Branch ได้ง่ายยิ่งขึ้น
ประเด็นสําคัญ
- ชื่อ Branch ที่ขับเคลื่อนด้วยวัตถุประสงค์ (Purpose-driven Branch Names): ชื่อ Branch แต่ละชื่อจะระบุวัตถุประสงค์อย่างชัดเจน ทําให้ง่ายต่อนักพัฒนาทุกคนในการทําความเข้าใจว่า Branch นี้มีไว้เพื่ออะไร
- การทํางานร่วมกับ CI/CD: การใช้ชื่อ Branch ที่สม่ําเสมอสามารถช่วยให้ระบบอัตโนมัติ (เช่น Continuous Integration/Continuous Deployment pipelines) เรียกใช้การทํางานเฉพาะเจาะจงตามประเภทของ Branch ได้ (เช่น การดีพลอยอัตโนมัติจาก Branch สําหรับการปล่อยเวอร์ชัน หรือ Release)
- การทํางานร่วมกันในทีม: ส่งเสริมการทํางานร่วมกันภายในทีมโดยทําให้วัตถุประสงค์ของ Branch มีความชัดเจน ช่วยลดความเข้าใจผิด และทําให้สมาชิกในทีมสามารถสลับไปมาระหว่างงานต่างๆ ได้ง่ายขึ้นโดยไม่เกิดความสับสน
ข้อกําหนด
คำนำหน้าสำหรับการตั้งชื่อ Branch
ข้อกำหนดของ Branch รองรับคำนำหน้า (Prefixes) ดังต่อไปนี้ และควรจัดวางโครงสร้างเป็น:
<type>/<description>
คำนำหน้าตามวัตถุประสงค์ — อธิบายเจตนาของงาน:
feature/(หรือfeat/): สำหรับฟีเจอร์ใหม่ (เช่นfeature/add-login-page,feat/add-login-page)bugfix/(หรือfix/): สำหรับการแก้ไขข้อบกพร่อง หรือ บั๊ก (เช่นbugfix/fix-header-bug,fix/header-bug)hotfix/: สำหรับการแก้ไขเร่งด่วน (เช่นhotfix/security-patch)release/: สำหรับ Branch ที่กำลังเตรียมการปล่อยเวอร์ชัน หรือ รีลีส (เช่นrelease/v1.2.0)chore/: สำหรับงานที่ไม่เกี่ยวข้องกับโค้ดโดยตรง เช่น การอัปเดตการพึ่งพา (Dependency) หรือเอกสารอ้างอิง (Docs) (เช่นchore/update-dependencies)
คำนำหน้าแหล่งที่มาของเอเจนต์ AI — ระบุ Branch ที่สร้างโดยเอเจนต์การเขียนโค้ด AI:
| คำนำหน้า | เอเจนต์ | ผู้ให้บริการ | ตั้งแต่ |
|---|---|---|---|
ai/ |
เอเจนต์ AI ใดก็ได้ | — | v1.1.0 |
claude/ |
Claude Code | Anthropic | v1.1.0 |
codex/ |
OpenAI Codex | OpenAI | v1.1.0 |
copilot/ |
GitHub Copilot | GitHub | v1.1.0 |
cursor/ |
Cursor | Anysphere | v1.1.0 |
Trunk branches (main, master, develop) ไม่จำเป็นต้องใช้คำนำหน้า
กฎขั้นพื้นฐาน
- ใช้อักขระที่เป็นตัวอักษรและตัวเลขพิมพ์เล็ก เครื่องหมายขีดกลาง และจุด (Use Lowercase Alphanumerics, Hyphens, and Dots): ให้ใช้ตัวอักษรพิมพ์เล็ก (
a-z), ตัวเลข (0-9) และเครื่องหมายยัติภังค์หรือขีดกลาง (-) เพื่อแยกคําเสมอ หลีกเลี่ยงการใช้อักขระพิเศษ เครื่องหมายขีดล่าง (Underscores) หรือช่องว่าง สําหรับ Branch ที่เป็นรีลีส สามารถใช้จุด (.) ในคําอธิบายเพื่อแสดงถึงหมายเลขเวอร์ชันได้ (เช่นrelease/v1.2.0) - ห้ามใช้เครื่องหมายขีดกลางหรือจุดติดกัน หรือวางไว้ตําแหน่งหน้าสุดหรือหลังสุด (No Consecutive, Leading, or Trailing Hyphens or Dots): ตรวจสอบให้แน่ใจว่าเครื่องหมายขีดกลางและจุดไม่ได้ปรากฏเรียงติดกัน (เช่น
feature/new--login,release/v1.-2.0) และไม่ได้อยู่ตรงจุดเริ่มต้นหรือจุดสิ้นสุดของคําอธิบาย (เช่นfeature/-new-login,release/v1.2.0.) - รักษาความชัดเจนและกระชับ (Keep It Clear and Concise): ชื่อ Branch ควรอธิบายได้ดีแต่มีความกระชับ โดยระบุจุดประสงค์ของงานได้อย่างชัดเจน
- รวมหมายเลขทิกเก็ต (Include Ticket Numbers): หากเป็นไปได้ ให้ใส่หมายเลขทิกเก็ต (Ticket number) จากเครื่องมือบริหารจัดการโปรเจกต์ของคุณเข้าไปด้วยเพื่อให้ติดตามงานได้ง่ายขึ้น ตัวอย่างเช่น สําหรับทิกเก็ตหมายเลข
issue-123ชื่อ Branch อาจเป็นfeature/issue-123-new-login
รูปแบบไวยากรณ์
รูปแบบไวยากรณ์ Augmented Backus-Naur Form หรือ ABNF ต่อไปนี้ได้กําหนดโครงสร้างเชิงรูปแบบของชื่อ Branch ที่ถูกต้อง:
branch-name = trunk-branch / prefixed-branch
trunk-branch = "main" / "master" / "develop"
prefixed-branch = type "/" description
type = "feature" / "feat" / "bugfix" / "fix"
/ "hotfix" / "release" / "chore"
/ "ai" / "copilot" / "cursor"
/ "claude" / "codex"
description = desc-segment *("-" desc-segment)
desc-segment = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA = %x61-7A ; lowercase a-z
DIGIT = %x30-39 ; 0-9
หมายเหตุ: ไม่อนุญาตให้ใช้เครื่องหมายขีดกลางหรือจุดติดกัน และไม่อนุญาตให้ใช้เครื่องหมายขีดกลางหรือจุดในตําแหน่งเริ่มต้นหรือตําแหน่งสิ้นสุดของคําอธิบาย
ตัวอย่าง
| ชื่อ Branch | สถานะ | หมายเหตุ |
|---|---|---|
main |
✅ | Trunk branch |
master |
✅ | Trunk branch |
develop |
✅ | Trunk branch |
feature/add-login-page |
✅ | ฟีเจอร์ใหม่ |
feat/add-login-page |
✅ | ชื่อเรียกย่อสําหรับฟีเจอร์ |
bugfix/fix-header-bug |
✅ | การแก้ไขบั๊ก |
fix/header-bug |
✅ | ชื่อเรียกย่อของการแก้ไขบั๊ก |
hotfix/security-patch |
✅ | การแก้ไขเร่งด่วน |
release/v1.2.0 |
✅ | รีลีสพร้อมระบุเวอร์ชัน |
chore/update-dependencies |
✅ | งานที่ไม่เกี่ยวกับโค้ด |
feature/issue-123-new-login |
✅ | ฟีเจอร์พร้อมหมายเลขทิกเก็ต |
Feature/Add-Login |
❌ | ไม่อนุญาตให้ใช้ตัวอักษรพิมพ์ใหญ่ |
feature/new--login |
❌ | ไม่อนุญาตให้ใช้เครื่องหมายขีดกลางติดกัน |
feature/-new-login |
❌ | มีเครื่องหมายขีดกลางนําหน้าคําอธิบาย |
feature/new-login- |
❌ | มีเครื่องหมายขีดกลางต่อท้ายคําอธิบาย |
release/v1.-2.0 |
❌ | มีเครื่องหมายขีดกลางอยู่ติดกับจุด |
fix/header bug |
❌ | ไม่อนุญาตให้เว้นวรรค (มีช่องว่าง) |
fix/header_bug |
❌ | ไม่อนุญาตให้ใช้เครื่องหมายขีดล่าง (Underscores) |
ai/refactor-auth-flow |
✅ | คำนำหน้าทั่วไปสำหรับเอเจนต์ AI |
copilot/add-login-page |
✅ | GitHub Copilot |
cursor/fix-header-bug |
✅ | Cursor |
claude/security-patch |
✅ | Claude Code โดย Anthropic |
codex/optimize-query |
✅ | OpenAI Codex |
unknown/some-task |
❌ | ไม่รู้จักประเภทของคำนำหน้า |
สรุปท้าย
- การสื่อสารที่ชัดเจน: เพียงแค่เห็นชื่อ Branch ก็ช่วยให้เข้าใจถึงจุดประสงค์ของการเปลี่ยนแปลงโค้ดนั้นๆ ได้อย่างชัดเจน
- รองรับระบบอัตโนมัติ: เชื่อมต่อกับกระบวนการอัตโนมัติได้ง่าย (เช่น เวิร์กโฟลว์ (Workflows) ที่แตกต่างกันสําหรับ
feature,releaseและอื่นๆ) - การขยายขนาด: ทํางานได้ดีในทีมขนาดใหญ่ที่มีนักพัฒนาหลายคนกําลังปฏิบัติงานหลายส่วนที่แตกต่างกันไปพร้อมๆ กัน
โดยสรุปแล้ว Conventional Branch ถูกออกแบบมาเพื่อปรับปรุงการจัดระเบียบโปรเจกต์ การสื่อสาร และการทํางานแบบอัตโนมัติภายในเวิร์กโฟลว์ของ Git (Git workflows) ให้ดียิ่งขึ้น
เครื่องมือ
ใช้เครื่องมือเหล่านี้เพื่อปรับใช้และบังคับใช้ Conventional Branch ในโปรเจกต์ของคุณ:
- commit-check: ตรวจสอบชื่อ branch, ข้อความ commit และ metadata ที่เกี่ยวข้องของ Git ในเครื่อง
- commit-check-action: ตรวจสอบชื่อ branch โดยอัตโนมัติใน GitHub Actions
- VSCode Conventional Branch: สร้างชื่อ branch แบบ Conventional Branch จาก Visual Studio Code
- Conventional Branch Skill: สอนผู้ช่วยเขียนโค้ด AI ให้สร้างชื่อ branch แบบ Conventional Branch ที่ถูกต้อง
ติดตั้ง skill ด้วยคำสั่ง:
npx skills add conventional-branch/conventional-branch --skill conventional-branchคำถามที่พบบ่อย
Conventional Branch มีความเกี่ยวข้องกับ Conventional Commits อย่างไร?
Conventional Branch ได้รับแรงบันดาลใจมาจาก Conventional Commits และปฏิบัติตามปรัชญาที่คล้ายคลึงกัน นั่นคือ การนำโครงสร้างที่ทั้งมนุษย์และเครื่องจักรสามารถอ่านได้มาใช้กับข้อมูลเมตา (Metadata) ของ Git ในขณะที่ Conventional Commits เป็นการสร้างมาตรฐานให้กับข้อความการคอมมิต (Commit messages) ตัว Conventional Branch จะเป็นการสร้างมาตรฐานให้กับชื่อ Branch ซึ่งข้อกำหนดทั้งสองนี้ต่างช่วยเสริมซึ่งกันและกันได้อย่างลงตัว
ทำไมประเภทของ Branch ถึงไม่ละเอียดเท่า Conventional Commits (เช่น build, ci, docs, style, refactor)?
Branch มีความแตกต่างจากการคอมมิต (Commits) — Branch เป็นเพียงสิ่งชั่วคราวและส่วนใหญ่จะถูกใช้งานจนกว่าจะถูกนำไปรวม (Merged) เท่านั้น การแนะนำประเภทของ Branch ให้มีมากเกินไปนั้นถือเป็นสิ่งไม่จำเป็น และจะทำให้ยากต่อการจัดการและการจดจำ
ฉันสามารถกำหนดประเภทของ Branch ด้วยตัวเองนอกเหนือจากรายการที่ระบุไว้ได้หรือไม่?
ได้ ข้อกำหนดนี้เป็นเพียงการกำหนดชุดประเภทที่แนะนำไว้ แต่ละทีมสามารถกำหนดประเภทเพิ่มเติมที่ปรับแต่งเองเพื่อให้สอดคล้องกับเวิร์กโฟลว์ของตนได้ อย่างไรก็ตาม สิ่งสำคัญคือต้องจัดทำเอกสารสำหรับประเภทที่ปรับแต่งขึ้นมาใหม่อย่างชัดเจน เพื่อให้สมาชิกทุกคนในทีมและเครื่องมืออัตโนมัติต่างๆ รับทราบตรงกัน
ความแตกต่างหลักระหว่าง v1.1.0 และ v1.0.0 คืออะไร?
v1.1.0 เพิ่ม คำนำหน้าแหล่งที่มาของเอเจนต์ AI เป็นฟีเจอร์ใหม่หลัก (ดูคำถามถัดไปสำหรับสาเหตุที่นำมาใช้) นอกจากนี้ยังมาพร้อมกับเว็บไซต์แบบหลายเวอร์ชันพร้อมตัวสลับเวอร์ชัน เพื่อให้ผู้ใช้สามารถเรียกดูข้อกำหนดทั้งเวอร์ชัน v1.0.0 และ v1.1.0 ได้ ชื่อ Branch ที่มีอยู่แล้วทั้งหมดใน v1.0.0 ยังคงใช้ได้อย่างสมบูรณ์ — ไม่มีการเปลี่ยนแปลงที่ทำให้เสียความเข้ากันได้
ทำไมต้องเพิ่มคำนำหน้าแหล่งที่มาของเอเจนต์ AI?
เอเจนต์การเขียนโค้ด AI (GitHub Copilot, Cursor, Claude Code, OpenAI Codex ฯลฯ) ถูกใช้มากขึ้นในการสร้างโค้ดและสร้าง Pull Request แต่ละเอเจนต์ใช้คำนำหน้า Branch ของตัวเอง (เช่น copilot/, cursor/) การทำให้คำนำหน้าเหล่านี้เป็นมาตรฐานในข้อกำหนด Conventional Branch ช่วยให้:
- ระบุได้รวดเร็ว — ผู้ตรวจสอบและเครื่องมือสามารถจดจำ PR ที่สร้างโดย AI ได้ทันที
- การตรวจสอบด้วยเครื่องมือ — เครื่องมืออย่าง commit-check สามารถตรวจสอบ Branch ของเอเจนต์ AI ตามข้อกำหนดได้
- มาตรฐานการลงทะเบียน — เอเจนต์ AI ใหม่สามารถใช้คำนำหน้าที่ได้จัดทำเป็นเอกสารไว้แล้ว แทนการสร้างรูปแบบขึ้นมาเฉพาะกิจ
คำนำหน้าทั่วไป ai/ พร้อมใช้งานสำหรับเอเจนต์ AI ที่ไม่มีคำนำหน้าเฉพาะ หรือสำหรับทีมที่ต้องการตัวระบุที่ไม่ขึ้นกับผู้จำหน่าย นี่คือฟีเจอร์หลักที่ปล่อยใน v1.1.0 — สำหรับสรุปการเปลี่ยนแปลงทั้งหมดระหว่างเวอร์ชัน โปรดดูคำถามที่พบบ่อยด้านบน
ฉันควรจัดการกับ Branch ที่มีอายุยาวนานอย่าง develop หรือ staging อย่างไร?
Branch สำหรับการรวมโค้ดหรือสำหรับสภาพแวดล้อม (Environment branches) ที่มีอายุการใช้งานยาวนาน ซึ่งเป็นส่วนหนึ่งของข้อกำหนดหลัก (อ้างอิงถึงกฎ trunk-branch ในไวยากรณ์) เช่น main, master หรือ develop จะถูกจัดให้เป็น Branch หลัก (Trunk branches) และไม่จำเป็นต้องมีคำนำหน้า (Prefix) นอกจากนี้ แต่ละทีมยังอาจเลือกที่จะกำหนด Branch ที่มีอายุการใช้งานยาวนานอื่นๆ (ตัวอย่างเช่น staging หรือ production) ให้เป็น Branch ที่มีสถานะเสมือน Branch หลัก (“Trunk-like” branches) ตามธรรมเนียมปฏิบัติได้ แต่สิ่งเหล่านี้ถือเป็นส่วนขยายที่ขึ้นอยู่กับแต่ละทีมซึ่งอยู่นอกเหนือจากข้อกำหนดของรูปแบบไวยากรณ์ อย่างไรก็ตาม ในทุกกรณี Branch เหล่านี้ควรได้รับการตั้งชื่ออย่างสม่ำเสมอในทุกภาคส่วนของโปรเจกต์ของคุณ
มีเครื่องมือใดบ้างที่สามารถใช้ตรวจสอบได้โดยอัตโนมัติหากสมาชิกในทีมไม่ได้ทำตามข้อกำหนดนี้?
คุณสามารถใช้ commit-check เพื่อตรวจสอบข้อกำหนดของ Branch หรือใช้ commit-check-action หากโค้ดของคุณถูกฝากไว้บน GitHub