วิธีเขียน Pull Request ที่ดี: Title, Description, และ Reviewer

Categories

การเขียน Pull Request ที่ดีสำคัญสำหรับการ Code Review ของทีม และจะทำให้ทีมของคุณเข้าใจ PR ของคุณได้อย่างมีประสิทธิภาพ PR ที่มีคุณภาพจะช่วยให้กระบวนการ Review เร็วขึ้น ลดข้อผิดพลาด และเพิ่มการทำงานร่วมกันของทีมงาน เมื่อคุณจัดการบิ๊ก PR ที่ใช้เดิจ้อย Cloud VPS โดยมีทีมพัฒนาจำนวนมาก การสื่อสารผ่าน PR ที่ชัดเจนจึงเป็นสิ่งจำเป็น

ทำไม Pull Request ที่ดีจึงสำคัญ

Pull Request เป็นเครื่องมือการสื่อสารของนักพัฒนา มันบอกให้ทีมเข้าใจว่าคุณเปลี่ยนแปลงอะไร ทำไมจึงต้องเปลี่ยนแปลง และจะส่งผลต่อระบบอย่างไร PR ที่เขียนดีจะช่วยให้ Reviewer ตรวจสอบได้อย่างรวดเร็ว และหลีกเลี่ยงข้อผิดพลาดที่อาจเกิดขึ้นได้

PR Title Conventions: ชื่อเรื่องที่บอกทุกอย่าง

ชื่อเรื่องของ PR ต้องสื่อความหมายที่ชัดเจน และให้บอกได้ว่ากำลังแก้ปัญหา หรือเพิ่มฟีเจอร์อะไร โดยส่วนใหญ่มักใช้ Conventional Commits ซึ่งเป็นมาตรฐาน

Good PR Titles:
- feat: Add user authentication module
- fix: Resolve memory leak in cache service
- docs: Update API documentation for v2
- refactor: Simplify database query logic
- perf: Optimize image loading performance
- test: Add unit tests for payment module
- chore: Update dependencies to latest version

Bad PR Titles:
- Changes
- Fixed stuff
- Work in progress
- Updated files
- Emergency fix
- asdf
- WIP: Multiple things

โครงสร้างที่ดี คือ [type]: [description] โดย type สามารถเป็น feat (ฟีเจอร์ใหม่), fix (แก้บัก), docs (เอกสาร), refactor (ปรับปรุงโค้ด), perf (เพิ่มประสิทธิภาพ), test (ทดสอบ), หรือ chore (งานบ้านอื่นๆ)

PR Description Template: วิธีอธิบายรายละเอียด

ส่วน Description เป็นหัวใจของ PR นี่คือที่ที่คุณอธิบายว่า PR นี้ทำอะไร เพราะเหตุใด และจะทดสอบอย่างไร template ที่ดีจะช่วยให้ Reviewer เข้าใจอย่างรวดเร็ว

## What does this PR do?
Brief explanation of the main purpose and what problems it solves

## Changes Made
- Change 1 with brief explanation
- Change 2 with brief explanation
- Change 3 with brief explanation
- Changed X files: A.js, B.js, C.js

## How to Test
Step-by-step instructions to verify the changes:
1. Checkout this branch
2. Run `npm install` and `npm run dev`
3. Navigate to /dashboard and click the new button
4. Verify that the form submits successfully
5. Check the console for any warnings

## Expected Behavior
- Button should be disabled while loading
- Success message should appear after 2 seconds
- Form should reset after successful submission

## Edge Cases Tested
- What happens with empty input?
- What happens with very long text?
- What happens if user clicks button twice?
- Network timeout handling?

## Screenshots/Videos
[Add before and after screenshots if UI changes]

## Breaking Changes
None / Yes - this changes API endpoint from /api/v1 to /api/v2

## Related Issues
Closes #123
Relates to #456

## Checklist
- [x] Code follows project style guide
- [x] All tests pass locally
- [x] Added/updated relevant tests
- [x] Added/updated documentation
- [x] No console errors/warnings
- [x] Ready for review

ส่วนประกอบสำคัญของ PR Description ที่ดี

PR ที่ดีจะต้องมีส่วนประกอบหลายอย่างเพื่อให้ Reviewer สามารถตรวจสอบได้อย่างมีประสิทธิภาพ

  • Context ชัดเจน – อธิบายปัญหาที่ต้องแก้ไขหรือเป้าหมายของการเปลี่ยนแปลง
  • Solution ที่นำเสนอ – วิธีแก้ไขของคุณ และทำไมคุณเลือกวิธีนี้แทนวิธีอื่น
  • Testing Steps ที่ชัดเจน – คำแนะนำทีละขั้นตอนว่า Reviewer ควรทดสอบอย่างไร
  • Screenshots หรือ Videos – ถ้า PR เกี่ยวข้องกับ UI การแสดงภาพช่วยให้เข้าใจได้เร็ว
  • Breaking Changes – ระบุชัดเจนถ้า PR นี้ทำให้ API หรือ functionality เปลี่ยนแปลงไป
  • Related Issues หรือ References – ลิงก์ไปยัง issue ที่เกี่ยวข้องเพื่อให้ context ที่ดี

การเลือก Reviewers: ใครควรอ่าน PR นี้

การเลือก Reviewer ที่เหมาะสมสำคัญต่อคุณภาพของการ Review ไม่ควรปล่อยให้ GitHub เลือก reviewer เอง ต้องคิดว่าใครเข้าใจส่วนของโค้ด ที่มีการเปลี่ยนแปลง

  • Assign คนที่เข้าใจ Features – ไป assign ให้คนที่เขียน feature นั้นหรือเข้าใจโครงสร้างดี
  • Assign ประมาณ 2-3 คน – พอที่จะสามารถตรวจสอบแต่ไม่ถูกหน่วงตัวเอง
  • ตรวจสอบ CODEOWNERS File – บางทีมใช้ CODEOWNERS เพื่อกำหนดผู้รับผิดชอบ Review
  • Assign ตามหน้าที่ – Senior dev ควร Review architecture ส่วน QA ควร Review test
  • Rotate Reviewers – อย่าให้คนเดียวกันโหลดทั้งหมด

PR Size Guidelines: ขนาด PR ที่เหมาะสม

ขนาดของ PR มีผลต่อคุณภาพการ Review โดยทั่วไป PR ที่เล็กจะ Review ได้เร็วและมีข้อผิดพลาดน้อยกว่า

  • Small (< 100 lines) - ทำเสร็จสิ้นในเวลาสั้น Review ได้อย่างลึกซึ้ง อัตราการอนุมัติ 99%
  • Medium (100-400 lines) – ขนาดปกติ Review ระยะเวลาพอสมควร ประมาณ 60% อนุมัติแรก
  • Large (400-1000 lines) – ต้องแบ่งเป็น PR เล็กๆ หรือต้องใช้เวลา Review มากขึ้น
  • Huge (> 1000 lines) – ควรแบ่งออกเป็นหลาย PR แต่ละอันอาจมีปัญหาการอนุมัติ

หลักการคือ ยิ่ง PR เล็ก ยิ่ง Review เร็ว ยิ่งข้อผิดพลาดน้อย ถ้า feature ใหญ่ลองแบ่งเป็น subtasks ของเล็กไป

Draft PRs: บ่งบอกว่ายังไม่พร้อม

Draft PR เป็นฟีเจอร์ที่ดีใน GitHub หรือ GitLab ที่ช่วยให้คุณสามารถทำงานร่วมกัน แต่ยังไม่พร้อมสำหรับการ merge

  • ใช้ Draft PR เมื่อยังต้องการการทำงาน แต่ต้องการให้ทีมดู
  • ใช้ Draft PR เมื่อต้องการ feedback ก่อนสิ้นสุด
  • เปลี่ยนจาก Draft เป็น Ready when done
  • Draft PRs ไม่สามารถ merge ได้จนกว่าจะสำเร็จ

Pre-Merge Checklist: ตรวจสอบก่อน Merge

ก่อน submit PR ให้ checklist ต่อไปนี้เพื่อลดปัญหา

Before submitting PR:
- [ ] Branch is updated with latest main
- [ ] All tests pass locally: npm run test
- [ ] No console errors/warnings
- [ ] Code style is consistent: npm run lint
- [ ] Added necessary tests for new code
- [ ] Updated documentation/README
- [ ] No hardcoded values or debug code
- [ ] Environment variables are used correctly
- [ ] Performance impact assessed
- [ ] Accessibility checked (if UI)

Before merging:
- [ ] All CI/CD checks passed
- [ ] At least 1-2 approvals from reviewers
- [ ] No unresolved conversation threads
- [ ] No merge conflicts
- [ ] Ready to deploy
- [ ] Database migrations ready (if needed)
- [ ] Feature flags configured (if needed)

Tips สำหรับการเขียน PR ที่ยอดเยี่ยม

  • Commit History ที่ดี – แต่ละ commit ควรมีความหมาย มี squash เข้าด้วยกันหากจำเป็น
  • Add Comments บน Code ที่ซับซ้อน – ถ้า logic ต้องอธิบายเพิ่มเติม ให้ comments ในโค้ด
  • Respond ต่อ Feedback อย่างสร้างสรรค์ – อย่าถือสาย feedback เป็นการวิจารณ์ มันช่วยให้ PR ดีขึ้น
  • Test ให้ครอบคลุม – ไม่เพียงแต่ unit tests แต่ยัง integration tests และ manual testing
  • Documentation ชัดเจน – ถ้า feature ใหม่ ต้องมี docs และ examples
  • ติดตามความเป็นไป – ตอบ comments และคำถามของ Reviewer อย่างรวดเร็ว
  • ไม่ว่าจะเก้า Reviewers ไม่ว่า – ความเป็นไป PR ที่ดีไม่ได้ติดอยู่ที่การ merge ตัวเอง

ตัวอย่าง PR จริง: Pull Request ที่ดี

นี่คือตัวอย่างของ PR ที่มีคุณภาพ ที่บอกได้ว่าผู้พัฒนาเข้าใจหลักการเขียน PR ที่ดี ตัวอย่างนี้อาจมาจากโปรเจค de.co.th ที่ทำงาน Cloud VPS

Title: feat: Add email verification for signup

Description:

## What does this PR do?
Adds email verification step during user signup. Users will receive
verification email and must click link before account is activated.

## Why is this change needed?
- Prevents spam accounts
- Ensures valid email addresses
- Complies with new data protection requirements

## Changes Made
- Added EmailVerification model to database
- Created email template for verification link
- Added verification endpoint: POST /api/verify-email
- Updated signup flow to send verification email
- Added tests for verification flow
- Updated API documentation

## How to Test
1. Checkout branch and run: npm install && npm run dev
2. Go to signup page
3. Fill in form with valid email
4. Check email inbox for verification link
5. Click link - account should be activated
6. Try to login - should succeed
7. Try signup with same email - should show error

## Testing Edge Cases
- Invalid email format: rejected at validation
- Expired verification link: shows error message
- Multiple signup attempts: prevents duplicates
- User clicks link multiple times: works correctly
- Database issues: proper error handling

## Screenshots
[Screenshot of verification email]
[Screenshot of success message]

## Breaking Changes
None - backward compatible

## Related Issues
Closes #234
Relates to #235 (future SMS verification)

## Checklist
- [x] All tests pass
- [x] Code linter passes
- [x] No console errors
- [x] Documentation updated
- [x] Ready for review

สรุป: ทำไม PR ที่ดีจึงสำคัญ

การเขียน Pull Request ที่ดีไม่ใช่เรื่องเล็กน้อย มันเป็นส่วนของวัฒนมานะในการเป็น developer มืออาชีพ PR ที่มีคุณภาพจะช่วยให้ทีมงานทำงานร่วมกันได้อย่างมีประสิทธิภาพ ลดข้อผิดพลาด และเก็บ codebase ให้สะอาดและเข้าใจง่าย ไม่ว่าคุณกำลังพัฒนา application ที่ทำงานบน Cloud VPS หรืออื่นๆ หลักการนี้ยังคงใช้ได้