Đóng dấu phiên bản: Tại sao mọi chương trình đều phải báo cáo chi tiết số build?

Gần đây, trong quá trình xử lý một sự cố (incident) nghiêm trọng trong môi trường sản xuất, tôi đã xác định được nguyên nhân gốc rễ trong chưa đầy một giờ. Tôi nhanh chóng triển khai bản sửa lỗi chỉ để loại trừ khả năng này, nhưng sau đó lại phải "mò mẫm trong bóng tối" nhiều giờ tiếp theo vì chúng tôi thiếu thông tin rõ ràng về số phiên bản và các lần triển khai… 😞

Trải nghiệm này khiến tôi suy nghĩ lại về quy trình quản lý phiên bản phần mềm, hay cụ thể hơn là về thông tin build (build versioning, version stamping). Tôi nhận ra rằng đối với trình quản lý cửa sổ i3, tôi đã giải quyết vấn đề này rất tốt từ hơn một thập kỷ trước, nên thật bất ngờ khi vấn đề này lại hoàn toàn chưa được giải quyết tại nơi làm việc.

Trong bài viết này, tôi sẽ giải thích cách 3 bước đơn giản (Đóng dấu! Kết nối! Báo cáo!) là đủ để giúp bạn tiết kiệm hàng giờ chậm trễ và căng thẳng khi xử lý sự cố.

Máy rửa bát có dải phiên bản chi tiết

Tại sao tiêu chuẩn phiên bản của chúng ta lại thấp thế?!

Mọi thiết bị gia dụng đều có thông tin phiên bản cực kỳ chi tiết! Hãy xem xét chiếc máy rửa bát này. Nếu một nhân viên sửa chữa không thể xác định được thiết bị, họ rất có thể sẽ từ chối touch vào nó.

Vậy tại sao tiêu chuẩn của chúng ta trong máy tính lại thấp hơn thế so với các thiết bị vật lý? Các sản phẩm tiêu dùng thường được đánh phiên bản theo một cách nào đó và điều đó thường là đủ tốt. Tuy nhiên, gần đây, tôi đã gặp quá nhiều bản build dành cho nhà phát triển không được đánh phiên bản đầy đủ.

Quản lý phiên bản phần mềm

Không giống như một thiết bị gia dụng vật lý có một tấm kim loại đóng dấu, phần mềm được cập nhật liên tục và chạy ở những nơi và cấu trúc mà chúng ta thường không thể nhìn thấy.

Thông thường, phần mềm có tên và số phiên bản với độ chi tiết khác nhau:

• Chrome
• Chrome 146
• Chrome 146.0.7680.80
• Chrome f08938029c887ea624da7a1717059788ed95034d-refs/branch-heads/7680_65@{#34}

Tất cả đều xác định trình duyệt Chrome trên máy tính của tôi, nhưng mỗi cái ở một mức độ chi tiết khác nhau. Tất cả đều đúng và hữu ích tùy thuộc vào ngữ cảnh.

Nghiên cứu tình huống: i3 --version và --moreversion

Khi tạo trình quản lý cửa sổ i3, tôi nhanh chóng học được rằng để hỗ trợ người dùng, việc chương trình tự xác định rõ ràng bản thân là rất quan trọng.

Khi chạy i3 --version, bạn sẽ thấy kết quả như sau:

i3 version 4.24 (2024-11-06) © 2009 Michael Stapelberg and contributors

Mỗi từ ngữ đều được cân nhắc kỹ lưỡng. 4.24 là phiên bản, ngày phát hành giúp bạn biết liệu nó có mới không, và thông tin bản quyền cho biết người đứng sau dự án.

Trong hỗ trợ người dùng, việc hỏi "Bạn đang dùng phiên bản i3 nào?" rất quan trọng. Nhưng i3 là một trình quản lý cửa sổ, không có menu Help -> About. Thay vào đó, tôi yêu cầu người dùng chạy lệnh i3 --version.

Sau đó, tôi giới thiệu thêm cờ --moreversion. Nó không chỉ báo cáo phiên bản của binary i3 mà còn kết nối với quy trình i3 đang chạy thông qua giao thức IPC để báo cáo phiên bản thực tế, cùng với các chi tiết quan trọng khác như tệp cấu hình đang được tải:

Binary i3 version:  4.24 (2024-11-06) © 2009 Michael Stapelberg and…
Running i3 version: 4.24 (2024-11-06) (pid 2521)
Loaded i3 config:
/home/michael/.config/i3/config (main)
(last modified: 2026-03-15T23:09:27 CET, 1101585 seconds ago)

Đây là một công cụ gỡ lỗi cực kỳ giá trị vì nó giúp xác nhận xem phiên bản bạn vừa build có thực sự đang chạy hay không, đồng thời hiển thị đường dẫn đầy đủ đến tệp cấu hình để tránh việc người dùng chỉnh sửa sai tệp.

Bản build cho nhà phát triển

Quản lý phiên bản tôi mô tả ở trên là đủ cho hầu hết người dùng. Nhưng đối với nhà phát triển, chúng ta cần độ chính xác cao hơn.

Khi xây dựng i3 từ git, nó báo cáo git revision mà nó được xây dựng từ đó (sử dụng git-describe):

i3 version 4.25-23-g98f23f54 © 2009 Michael Stapelberg and contributors

Việc báo cáo VCS revision (số hiệu sửa đổi của hệ thống kiểm soát phiên bản) là lựa chọn hữu ích nhất. Cách này giúp chúng ta bắt được các sai lầm phổ biến:

• Xây dựng từ sai revision.
• Build nhưng quên cài đặt (install).
• Cài đặt nhưng phiên làm việc không nhận diện được nó (sai vị trí?).

Hữu ích nhất: Đóng dấu VCS Revision

Như chúng ta đã thấy, mảnh thông tin phiên bản quan trọng nhất là VCS revision. Chúng ta có thể tìm nạp tất cả các chi tiết khác (số phiên bản, ngày tháng, tác giả...) từ kho lưu trữ VCS.

Hãy xem xét trường hợp tốt nhất bằng cách nhìn vào cách Go làm điều đó!

Go luôn đóng dấu! 🥳

Go đã trở thành ngôn ngữ lập trình yêu thích của tôi trong những năm qua, một phần lớn là nhờ gu thẩm mỹ và phong cách của các nhà phát triển Go, và tất nhiên là nhờ bộ công cụ chất lượng cao.

Go đã triển khai tiêu chuẩn vàng về quản lý phiên bản phần mềm: nó nhúng thông tin build của VCS theo mặc định! Tính này được giới thiệu trong Go 1.18 (Tháng 3 năm 2022).

Trong thực tế, điều này có nghĩa là khi bạn build từ git, thông tin VCS được tự động nhúng vào.

Quy trình build Go từ git

Điều này rất thú vị khi sử dụng các công cụ như gops để xác định chương trình đang chạy:

% go version -m /srv/man/bin/debiman
/srv/man/bin/debiman: go1.25.5
path    github.com/Debian/debiman/cmd/debiman
mod     github.com/Debian/debiman    v0.0.0-20251230101540-ac8f5391b43b+dirty
...
build   vcs=git
build   vcs.revision=ac8f5391b43bc1a9dbdc99f6179e2fb7d7414a04
build   vcs.time=2025-12-30T10:15:40Z
build   vcs.modified=true

VCS rev với NixOS

Khi đóng gói phần mềm Go với Nix, rất dễ mất thông tin đóng dấu VCS revision của Go. Các bộ nạp (fetchers) của Nix như fetchFromGitHub thường tải về các tệp lưu trữ (.tar.gz) thay vì toàn bộ thư mục .git để tối ưu hóa hiệu quả và khả năng tái tạo (reproducibility).

Điều này tạo ra sự căng thẳng giữa khả năng tái tạo và việc đóng dấu VCS.

May mắn thay, có một giải pháp hoạt động cho cả hai: tôi đã tạo mô-đun Nix overlay stapelberg/nix/go-vcs-stamping mà bạn có thể nhập để có được đóng dấu VCS revision hoạt động theo mặc định cho các biểu thức buildGoModule của mình!

Overlay này hoạt động như một bộ chuyển đổi giữa Nix và Go:

1. Nó tổng hợp một tệp .git/HEAD giả để Go phát hiện một kho git.
2. Nó tiêm một lệnh git giả vào PATH để thực hiện đúng 2 lệnh mà Go sử dụng.
3. Nó đặt -buildvcs=true trong biến môi trường GOFLAGS.

Sơ đồ VCS với Nix

Sau khi áp dụng overlay này, các binary Go của bạn sẽ được đóng dấu mới với thông tin build vcs:

build   vcs=git
build   vcs.revision=c0134ef21d37e4ca8346bdcb7ce492954516aed5
build   vcs.time=2026-03-22T08:32:55Z
build   vcs.modified=false

Kết luận: Đóng dấu! Kết nối! Báo cáo!

Lập luận của tôi rất đơn giản:

Việc đóng dấu VCS revision về mặt khái niệm thì dễ, nhưng rất quan trọng! Ví dụ, nếu hệ thống sản xuất trong sự cố tôi đã đề cập đã báo cáo phiên bản của nó, chúng tôi đã có thể tiết kiệm nhiều giờ thời gian khắc phục!

Kế hoạch hành động của bạn để khắc phục vấn đề này chỉ gồm 3 bước đơn giản:

1. Đóng dấu (Stamp it)! Bao gồm VCS revision của nguồn trong các chương trình của bạn.
2. Kết nối (Plumb it)! Khi xây dựng / đóng gói, hãy đảm bảo VCS revision không bị mất dọc theo đường đi.
3. Báo cáo (Report it)! Làm cho phần mềm của bạn in ra VCS revision trên mọi bề mặt phù hợp:
   • Các chương trình thực thi: Báo cáo khi chạy với --version.
   • Dịch vụ và batch job: Bao gồm trong nhật ký khởi động.
   • Các yêu cầu HTTP đi: Bao gồm trong User-Agent.
   • Giao diện người dùng: Hiển thị revision ở đâu đó hiển thị để gỡ lỗi.

Việc triển khai "quan sát phiên bản" (version observability) trong toàn bộ hệ thống của bạn là một dự án mang lại tỷ suất hoàn vốn (ROI) cao chỉ trong một ngày.

Hãy đi và đóng dấu các chương trình của bạn ngay bây giờ! 🚀