Nhảy đến nội dung chính

TỔNG QUAN

I. Mục đích

Tài liệu này nhằm:

  • Thống nhất cách quản lý source code trong dự án
  • Giảm xung đột khi làm việc nhóm
  • Đảm bảo code dễ đọc, dễ review, dễ bảo trì
  • Làm căn cứ xử lý khi vi phạm quy trình kỹ thuật

Quy định này áp dụng cho toàn bộ thành viên tham gia phát triển và chỉnh sửa source code của dự án.

II. Nguyên tắc chung

1. Không làm việc trực tiếp trên nhánh chính

  • Không commit trực tiếp vào main
  • Không commit trực tiếp vào develop
  • Mọi thay đổi phải thông qua nhánh riêng và Pull Request

Vi phạm quy định này được xem là vi phạm quy trình kỹ thuật.

2. Mọi thay đổi đều phải trace được

  • Mỗi commit phải gắn với task hoặc issue cụ thể
  • Không commit không rõ mục đích
  • Không chỉnh sửa code mà không có liên quan đến task

Code không trace được nguồn gốc được xem là không hợp lệ.

3. Code phải ưu tiên tính rõ ràng

  • Viết code để người khác đọc được
  • Không tối ưu hóa sớm khi chưa cần thiết
  • Không viết logic phức tạp nếu có thể tách nhỏ

Code khó đọc, khó hiểu sẽ bị yêu cầu chỉnh sửa trong quá trình review.

PHẦN A – QUY ĐỊNH GIT WORKFLOW

III. Cấu trúc nhánh

Dự án sử dụng cấu trúc nhánh:

  • main: nhánh production
  • develop: nhánh tích hợp chung
  • feature/*: phát triển tính năng
  • bugfix/*: sửa lỗi
  • hotfix/*: sửa lỗi khẩn cấp production

Không tạo nhánh tự do ngoài quy ước trên nếu chưa được thống nhất.

IV. Quy trình thực hiện task

4. Tạo nhánh

Nhánh phải được tạo từ develop:

  • Luôn pull develop mới nhất trước khi tạo nhánh
  • Không tạo nhánh từ nhánh cá nhân khác

Quy ước đặt tên nhánh:

  • feature/TASKID-mo-ta-ngan
  • bugfix/TASKID-mo-ta-ngan
  • hotfix/TASKID-mo-ta-ngan

Yêu cầu:

  • Không dùng tiếng Việt có dấu
  • Không viết hoa tùy ý
  • Không đặt tên chung chung như: fix, test, abc

5. Commit

Mỗi commit phải:

  • Có nội dung rõ ràng
  • Gắn với mã task
  • Phản ánh đúng thay đổi thực tế

Cấu trúc commit message:

[TASK-ID] Loại thay đổi: Mô tả ngắn

Loại thay đổi bao gồm:

  • Add
  • Fix
  • Update
  • Refactor
  • Remove
  • Optimize
  • Docs

Không chấp nhận commit message không có ý nghĩa.

6. Pull Request

Khi hoàn thành task:

  • Push nhánh lên remote
  • Tạo Pull Request vào develop
  • Mô tả rõ:
    • Mục đích thay đổi
    • Phạm vi ảnh hưởng
    • Điểm cần lưu ý

Không tự ý merge khi chưa được review.

7. Review

Mỗi Pull Request phải:

  • Có ít nhất 1 người review
  • Được approve trước khi merge

Reviewer có trách nhiệm:

  • Đọc và hiểu logic
  • Kiểm tra ảnh hưởng hệ thống
  • Yêu cầu chỉnh sửa nếu cần

Approve hình thức hoặc không đọc kỹ được xem là không hoàn thành trách nhiệm review.

8. Merge và xử lý conflict

  • Người tạo PR chịu trách nhiệm xử lý conflict
  • Phải test lại sau khi resolve conflict
  • Không force push vào nhánh chung

Sau khi merge, người thực hiện task chịu trách nhiệm theo dõi lỗi phát sinh liên quan.

PHẦN B – QUY ƯỚC CODE

V. Quy ước đặt tên

9. Biến

  • Sử dụng camelCase
  • Tên phải có ý nghĩa
  • Không viết tắt khó hiểu

Không sử dụng tên như: a, data1, temp, test nếu không có ý nghĩa rõ ràng.

10. Class và Interface

  • Sử dụng PascalCase
  • Tên phản ánh đúng chức năng

Ví dụ:

  • UserSyncService
  • AuthController
  • DataMappingRepository

Không đặt tên chung chung như: Service1, TestClass.

11. Tên file

  • Tên file trùng với class chính
  • Không đặt tên file không rõ nghĩa

Không sử dụng các tên như: utils2, newfile, test.

VI. Cấu trúc và tổ chức code

12. Phân tầng rõ ràng

  • Controller không chứa business logic phức tạp
  • Service không truy cập database trực tiếp nếu đã có repository layer
  • Không viết toàn bộ logic trong một file duy nhất

Phải tuân thủ đúng kiến trúc đã thống nhất của dự án.

13. Hàm và logic

  • Một function chỉ nên thực hiện một nhiệm vụ
  • Không viết function quá dài và khó theo dõi
  • Logic phức tạp phải được tách nhỏ

Nếu một function vượt quá mức hợp lý và khó đọc, reviewer có quyền yêu cầu refactor.

14. Logging

  • Log phải có mục đích rõ ràng
  • Không log dữ liệu nhạy cảm
  • Không để log debug dư thừa trước khi merge

15. Xử lý lỗi

  • Không catch lỗi mà bỏ qua
  • Không throw lỗi chung chung
  • Message lỗi phải rõ ràng, có ngữ cảnh

Không để các khối catch rỗng hoặc bỏ qua exception.

16. Format và kiểm tra tự động

  • Bắt buộc sử dụng ESLint / Prettier theo cấu hình dự án
  • Không merge nếu format sai
  • Không thay đổi format toàn bộ file nếu không liên quan đến task

VII. Trách nhiệm kỹ thuật

  1. Code trước khi tạo PR phải:
    • Chạy được
    • Không lỗi compile
    • Không làm hỏng chức năng cũ
  2. Người thực hiện task chịu trách nhiệm:
    • Test lại trước khi merge
    • Theo dõi lỗi phát sinh sau khi merge
  3. Không đổ lỗi cho quá trình merge nếu chưa kiểm tra kỹ trước đó.

VIII. Xử lý vi phạm

17. Vi phạm mức độ 1 – Yêu cầu chỉnh sửa

Áp dụng khi:

  • Sai format
  • Sai naming
  • Commit message không đúng quy ước
  • PR thiếu mô tả

Hình thức xử lý:

  • Yêu cầu chỉnh sửa trước khi approve

18. Vi phạm mức độ 2 – Từ chối merge

Áp dụng khi:

  • Không tuân thủ workflow
  • Tự ý commit vào nhánh chính
  • Không xử lý conflict
  • Không test trước khi tạo PR

Hình thức xử lý:

  • Từ chối merge
  • Yêu cầu làm lại theo đúng quy trình

19. Vi phạm mức độ 3 – Đánh giá năng lực kỹ thuật

Áp dụng khi:

  • Lặp lại vi phạm nhiều lần
  • Không tuân thủ quy ước dù đã được nhắc
  • Gây ảnh hưởng nghiêm trọng đến hệ thống

Hình thức xử lý:

  • Trao đổi trực tiếp
  • Đánh giá lại mức độ phù hợp trong dự án

IX. Hiệu lực

Quy định này có hiệu lực kể từ ngày ban hành và áp dụng cho toàn bộ thành viên tham gia phát triển dự án.

Mọi thay đổi về workflow hoặc quy ước kỹ thuật phải được thống nhất trước khi áp dụng.

Lên đầu trang