Cách đánh số phiên bản module

Người phát triển một module dùng từng phần trong số phiên bản của module để báo hiệu tính ổn định và tương thích ngược của phiên bản đó. Với mỗi bản phát hành mới, số phiên bản của module phản ánh cụ thể bản chất của những thay đổi trong module kể từ bản phát hành trước đó.

Khi bạn phát triển mã sử dụng các module bên ngoài, bạn có thể dùng số phiên bản để hiểu mức độ ổn định của một module bên ngoài lúc cân nhắc nâng cấp. Khi bạn phát triển module của riêng mình, số phiên bản của bạn sẽ báo hiệu tính ổn định và tương thích ngược của module tới các lập trình viên khác.

Chủ đề này mô tả ý nghĩa của các số phiên bản module.

Xem thêm

• Khi bạn dùng các package bên ngoài trong mã của mình, bạn có thể quản lý những phụ thuộc đó bằng các công cụ Go. Để biết thêm, xem Quản lý phụ thuộc.
• Nếu bạn phát triển module cho người khác dùng, bạn gán một số phiên bản khi phát hành module, bằng cách gắn tag cho module trong repository của nó. Để biết thêm, xem Phát hành một module.

Một module đã phát hành được công bố kèm số phiên bản theo mô hình semantic versioning, như minh hoạ sau:

Bảng sau mô tả cách các phần của số phiên bản thể hiện tính ổn định và tương thích ngược của một module.

Đang phát triển

Báo hiệu rằng module vẫn đang được phát triển và chưa ổn định. Bản phát hành này không kèm bảo đảm nào về tương thích ngược hay tính ổn định.

Số phiên bản có thể ở một trong các dạng sau:

Số pseudo-version

v0.0.0-20170915032832-14c0d48ead0c

Số v0

v0.x.x

Số pseudo-version

Khi một module chưa được gắn tag trong repository của nó, các công cụ Go sẽ sinh ra một số pseudo-version để dùng trong tệp go.mod của mã gọi các hàm trong module đó.

Lưu ý: Như một thực hành tốt, hãy luôn để các công cụ Go sinh ra số pseudo-version thay vì tự tạo số của riêng bạn.

Pseudo-version hữu ích khi người phát triển mã sử dụng các hàm của module cần làm việc dựa trên một commit chưa được gắn tag semantic version.

Một số pseudo-version có ba phần ngăn cách bằng dấu gạch nối, theo dạng sau:

Cú pháp

baseVersionPrefix-timestamp-revisionIdentifier

Các phần

• baseVersionPrefix (vX.0.0 hoặc vX.Y.Z-0) là giá trị được suy ra từ tag semantic version đứng trước revision, hoặc từ vX.0.0 nếu không có tag như vậy.

• timestamp (yymmddhhmmss) là thời điểm UTC mà revision được tạo. Trong Git, đây là thời gian commit, không phải thời gian tác giả.

• revisionIdentifier (abcdefabcdef) là tiền tố 12 ký tự của hash commit, hoặc trong Subversion là số revision được đệm bằng số 0.

Số v0

Một module được phát hành với số v0 sẽ có một số semantic version chính thức gồm phần major, minor và patch, cùng với một định danh pre-release tuỳ chọn.

Dù phiên bản v0 có thể được dùng trong môi trường production, nó không bảo đảm gì về tính ổn định hay tương thích ngược. Ngoài ra, các phiên bản v1 trở đi được phép phá vỡ tương thích ngược đối với mã dùng các phiên bản v0. Vì lý do này, người phát triển mã sử dụng các hàm trong một module v0 có trách nhiệm tự thích ứng với các thay đổi không tương thích cho tới khi v1 được phát hành.

Pre-release version

Báo hiệu rằng đây là một mốc pre-release, chẳng hạn alpha hoặc beta. Bản phát hành này không kèm bảo đảm nào về tính ổn định.

Ví dụ

vx.x.x-beta.2

Người phát triển module có thể dùng một định danh pre-release với bất kỳ tổ hợp major.minor.patch nào bằng cách nối thêm dấu gạch nối và định danh pre-release.

Minor version

Báo hiệu các thay đổi tương thích ngược đối với API công khai của module. Bản phát hành này bảo đảm tương thích ngược và tính ổn định.

Ví dụ

vx.4.x

Phiên bản này thay đổi API công khai của module, nhưng không theo cách làm hỏng mã đang gọi. Điều này có thể bao gồm các thay đổi đối với phụ thuộc của chính module, hoặc việc bổ sung các hàm, method, trường struct hay kiểu dữ liệu mới.

Nói cách khác, phiên bản này có thể bao gồm các cải tiến thông qua những hàm mới mà lập trình viên khác có thể muốn dùng. Tuy nhiên, người đang dùng các minor version trước đó không cần thay đổi mã của họ.

Patch version

Báo hiệu các thay đổi không ảnh hưởng tới API công khai của module hay các phụ thuộc của nó. Bản phát hành này bảo đảm tương thích ngược và tính ổn định.

Ví dụ

vx.x.1

Một bản cập nhật làm tăng số này chỉ dành cho các thay đổi nhỏ như sửa lỗi. Người phát triển mã sử dụng module có thể nâng cấp lên phiên bản này một cách an toàn mà không cần thay đổi mã của họ.

Major version

Báo hiệu các thay đổi không tương thích ngược trong API công khai của module. Bản phát hành này không bảo đảm rằng nó sẽ tương thích ngược với các major version trước đó.

Ví dụ

v1.x.x

Số phiên bản v1 trở lên báo hiệu rằng module đã ổn định để sử dụng (trừ các phiên bản pre-release của nó).

Lưu ý rằng vì phiên bản 0 không bảo đảm gì về tính ổn định hay tương thích ngược, người nâng cấp một module từ v0 lên v1 có trách nhiệm tự thích ứng với các thay đổi phá vỡ tương thích ngược.

Người phát triển module chỉ nên tăng số này vượt quá v1 khi thật sự cần thiết, bởi việc nâng cấp phiên bản đó gây xáo trộn đáng kể cho các lập trình viên có mã dùng hàm trong module được nâng cấp. Sự xáo trộn này bao gồm các thay đổi không tương thích ngược đối với API công khai, cũng như việc lập trình viên dùng module phải cập nhật package path ở mọi nơi họ import package từ module đó.

Một bản cập nhật major version lên số cao hơn v1 cũng sẽ có module path mới. Đó là vì module path sẽ được nối thêm số major version, như trong ví dụ sau:

module example.com/mymodule/v2 v2.0.0

Một bản cập nhật major version biến nó thành một module mới với lịch sử tách biệt khỏi phiên bản trước của module. Nếu bạn phát triển module để phát hành cho người khác, xem “Phát hành các thay đổi API phá vỡ tương thích” trong Quy trình phát hành và đánh phiên bản module.

Để biết thêm về directive module, xem Tài liệu tham chiếu go.mod.