Posted inGit

Tự động hóa Versioning & CHANGELOG: Rảnh tay với Semantic-release

Git tutorial - IT technology blog
Git tutorial - IT technology blog

Nỗi ám ảnh mang tên “Đánh số phiên bản thủ công”

Bạn đã bao giờ mất cả tiếng đồng hồ chỉ để soi lại Git log và viết file CHANGELOG chưa? Mình từng rơi vào vòng lặp mệt mỏi này: kiểm tra xem bản này là feature hay fix, sửa số version trong package.json, rồi hì hục gõ tay từng dòng thay đổi. Chỉ cần một phút lơ đễnh là quên update version hoặc bỏ sót một commit quan trọng ngay.

Có lần mình quên cập nhật phiên bản nhưng vẫn đẩy code lên production. Hệ thống monitoring báo lỗi version cũ, khiến đồng nghiệp hoang mang không biết tính năng mới đã online chưa. Sau sai lầm đó, mình quyết định tự động hóa toàn bộ. Semantic-release chính là giải pháp giúp mình tiết kiệm ít nhất 15-20 phút cho mỗi lần release.

Semantic-release hoạt động như thế nào?

Công cụ này hoạt động dựa trên Conventional Commits để tự quyết định số phiên bản tiếp theo. Nó không cần bạn phải can thiệp thủ công vào việc chọn Major, Minor hay Patch.

Quy tắc cực kỳ đơn giản. Nếu bạn dùng fix: ..., nó tăng Patch version. Nếu dùng feat: ..., nó tăng Minor version. Đặc biệt, khi có từ khóa BREAKING CHANGE, hệ thống sẽ tự động nhảy vọt lên Major version. Mọi thứ diễn ra chuẩn xác theo logic máy tính.

Cài đặt các gói cần thiết

Để bắt đầu, hãy cài đặt các plugin vào devDependencies. Dưới đây là bộ công cụ mình thường dùng cho môi trường Node.js:

npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github @semantic-release/npm

Mỗi plugin đảm nhận một nhiệm vụ riêng biệt:

  • commit-analyzer: Phân tích lịch sử commit để xác định version mới.
  • release-notes-generator: Tự động tổng hợp nội dung cho CHANGELOG.
  • changelog: Ghi các thay đổi vào file CHANGELOG.md.
  • git: Tự động commit các file đã cập nhật ngược lại repository.
  • github: Tạo GitHub Release kèm theo tag và ghi chú phiên bản.

Cấu hình file .releaserc “thực chiến”

Mình thường dùng file .releaserc để quản lý cấu hình tập trung. Đây là mẫu cấu hình mình đang áp dụng cho các dự án thực tế:

{
  "branches": ["main", "master"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ],
    "@semantic-release/github"
  ]
}

Lưu ý quan trọng: Cụm từ [skip ci] trong message giúp tránh vòng lặp CI/CD vô tận. Nếu thiếu dòng này, bot commit sẽ kích hoạt Pipeline chạy lại liên tục, gây lãng phí tài nguyên và làm treo hệ thống.

Tích hợp vào GitHub Actions

Sức mạnh thực sự của Semantic-release nằm ở Pipeline tự động. Bạn hãy tạo file .github/workflows/release.yml với nội dung sau:

name: Release
on:
  push:
    branches:
      - main
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 'lts/*'
      - run: npm ci
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Biến GITHUB_TOKEN đã có sẵn. Tuy nhiên, bạn cần thêm NPM_TOKEN vào phần Secrets nếu muốn đẩy package lên npm. Với dự án nội bộ, hãy đặt "npmPublish": false trong cấu hình plugin.

Kiểm tra trước khi triển khai

Trước khi merge code, bạn nên chạy thử ở chế độ dry-run để kiểm tra log:

npx semantic-release --dry-run

Lệnh này giúp bạn biết chính xác version tiếp theo là gì mà không làm thay đổi file hay tạo tag thật. Khi mọi thứ đã ổn, chỉ cần git push và để Pipeline lo phần còn lại.

Kết quả nhận được là một trang Releases trên GitHub chuyên nghiệp. Đồng nghiệp chỉ cần nhìn qua là nắm bắt được mọi thay đổi mà không cần hỏi bạn một câu nào.

Kinh nghiệm rút ra từ thực tế

Một là, hãy bỏ thói quen commit kiểu fix: update code hay feat: xong việc. Những câu vô nghĩa này sẽ xuất hiện trên CHANGELOG và làm giảm uy tín của dự án trước khách hàng.

Hai là, hãy ưu tiên dùng Squash and Merge khi làm việc nhóm. Cách này cho phép bạn chỉnh sửa commit message lần cuối cho chuẩn chỉnh trước khi nó đi vào lịch sử nhánh chính.

Cuối cùng, hãy cài đặt commitlint và husky. Bộ đôi này sẽ chặn đứng những commit sai chuẩn ngay từ máy của lập trình viên, đảm bảo quy trình luôn vận hành trơn tru.

Áp dụng Semantic-release không chỉ giúp bạn rảnh tay mà còn xây dựng quy trình làm việc chuyên nghiệp. Máy móc làm việc lặp đi lặp lại tốt hơn con người, vậy tại sao chúng ta không tận dụng?

Share:
Tags: