Conventional Commits

Lời mở đầu

Một ngày đẹp trời (thực ra đang cong đít viết blog cho đủ OKR 😂), mình mở lịch sử commit của dự án 1 và 2 năm trước của mình:

2 năm về trước:
Screenshot-2021-09-29-232548

1 năm về trước:
Screenshot-2021-09-29-215256

Có vẻ cải thiện nhưng vẫn khá chuối nhỉ 😂 Một số commit thì đọc còn hiểu, nhưng có những commit đọc xong chả nhớ mình làm cái gì ở commit đó.
Và rồi mình được biết đến Conventional Commits sau 1 lần thông não đến từ anh Nong Tạ.

Conventional Commits là cái chi?

Screenshot-2021-09-29-220243
Conventional Commits là một bộ quy tắc viết commit message sinh ra mục đích để cả người và máy đều có thể đọc được. Máy ở đây có thể là các công cụ tìm kiếm. Nó cung cấp các quy tắc để viết commit message một cách rõ ràng.

Bộ quy tắc này tương khớp với SemVer (Semantic Version) bởi cách nó mô tả các feature, fix bugs hay là refactor code.

Vì sao nên sử dụng Conventional Commits?

Nếu trong một project mà mỗi người viết commit message một kiểu thì khi nhìn vào lịch sử commit trông khá là .... không đẹp lắm nhỉ? 😂 Chưa kể khi cần chúng ta muốn xem lại hoặc tìm kiếm một commit trong đống commit của vài tuần/tháng trước đó thông qua các commit message mà không có bất cứ quy tắc nào....

Và dưới đây là những ưu điểm khi sử dụng Conventional Commits:

  1. Giúp người khác (đặc biệt là mình 😁) đọc lại commit sẽ biết commit đó sinh ra để làm gì.
  2. Tóm lược các thay đổi code sau khi release một thời gian dài.
  3. Lịch sử commit sẽ sạch đẹp và ngăn nắp mỗi khi bạn ghé thăm 😁.

P/s: Không có commit nào viết đúng và cũng không có commit nào viết sai, chỉ là viết đọc có hiểu hay không mà thôi 👌.

Cấu trúc của một commit message

<type>(optional-scope): <description>
[optional body]
[optional footer(s)]

Trong đó:

  1. <type>: từ khóa để phân biệt loại commit. Các loại <type> phổ biến:
    • feat: Thêm chức năng mới.
    • fix: Sửa bug.
    • perf: Thay đổi làm cải thiện hiệu năng.
    • chore: "dọn dẹp" không đáng kể tới code.
    • docs: Thêm/sửa đổi về documents.
    • refactor: "Làm sạch" code nhưng không phải sửa lỗi hoặc thêm tính năng mới. (VD: Loại bỏ code smells,... )
    • revert: Revert một/nhiều commit.
    • style: Thay đổi về UI mà không ảnh hưởng tới logic. (VD: Thêm khoảng trắng, sửa format,...)
    • vendor: cập nhật phiên bản cho các packages, dependencies.
  2. (optional-scope):
    • KHÔNG BẮT BUỘC
    • Dùng để phân loại commit, để chỉ phạm vi ảnh hưởng của commit đó.
      VD: feat(lang): add polish language
  3. <description>: mô tả ngắn nội dung sửa đổi trong commit.
    VD: fix: correct minor typos in code
  4. [optional body]:
    • KHÔNG BẮT BUỘC
    • NẾU CÓ, bắt buộc phải cách phần description 1 dòng trắng (blank line).
    • Mô tả dài, chi tiết hơn phần mô tả ngắn ở trên.
    • VD:
      fix: correct minor typos in code
      
      see the issue for details
      
      on typos fixed.
      
  5. [optional footer(s)]:
    • KHÔNG BẮT BUỘC
    • Nằm ở phía sau body (nếu có) và phân cách bằng một dòng trắng (blank line).
    • Chứa các thông tin mở rộng.
    • Để phân biệt với phần body thì các từ ghép dùng làm token (ngoại trừ BREAKING CHANGE) sẽ viết theo kiểu kebab-case (Reviewed by => Reviewed-by).
    • VD:
      fix: correct minor typos in code
      
      see the issue for details
      
      on typos fixed.
      
      Reviewed-by: Z
      Refs #133
      
  6. BREAKING CHANGE (quan trọng nên cần viết IN HOA và bôi đậm):
    • Nếu sự thay đổi code khiến cho app không còn tương thích với phiên bản trước nữa thì bạn sẽ phải đánh dấu là BREAKING CHANGE.
    • Có 2 cách để đánh dấu là BREAKING CHANGE: đó là đặt từ khóa BREAKING CHANGE: vào đầu footer hoặc là ! liền sau type/scope hoặc sử dụng cả 2.
    • VD:
    # sử dụng từ khóa `BREAKING CHANGE`
    feat: allow provided config object to extend other configs
    <blank line>
    BREAKING CHANGE:<space>`extends` key in config file is now used for extending other config files
    
    # sử dụng ! liền sau type trong commit
    refactor!: drop support for Node 6
    
    # sử dụng kết hợp cả 2 
    refactor!: drop support for Node 6
    <blank line>
    BREAKING CHANGE:<space>refactor to use JavaScript features not available in Node 6.
    

Túm cái váy lại

Trên đây là các quy tắc cơ bản của Conventinal Commit để viết một commit message một cách chuyên nghiệp, rõ ràng, dễ đọc và hiệu quả hơn. Chúc các bạn có thể áp dụng được vào dự án thực tế.

Các nguồn tham khảo:

https://www.conventionalcommits.org/en/v1.0.0/
https://viblo.asia/p/dat-ten-commit-message-sao-cho-tinh-nghia-anh-em-chac-chan-ben-lau-OeVKBM605kW