Quy trình phát hành và đánh phiên bản module

Khi bạn phát triển module cho các lập trình viên khác dùng, bạn có thể theo một quy trình giúp bảo đảm trải nghiệm đáng tin cậy và nhất quán cho những người dùng module đó. Chủ đề này mô tả các bước ở mức tổng quan trong quy trình ấy.

Để có cái nhìn tổng quan về việc phát triển module, xem Phát triển và phát hành module.

Xem thêm

Nếu bạn chỉ muốn dùng các package bên ngoài trong mã của mình, hãy xem Quản lý phụ thuộc.
Với mỗi phiên bản mới, bạn báo hiệu các thay đổi của module thông qua số phiên bản của nó. Để biết thêm, xem Cách đánh số phiên bản module.

Các bước thường gặp trong quy trình

Trình tự sau minh hoạ các bước phát hành và đánh phiên bản cho một module mới làm ví dụ. Để biết thêm về từng bước, xem các mục trong chủ đề này.

Bắt đầu một module và tổ chức mã nguồn của nó sao cho lập trình viên dễ sử dụng còn bạn thì dễ bảo trì.

Nếu bạn hoàn toàn mới với việc phát triển module, hãy xem Hướng dẫn: Tạo một module Go.

Trong hệ thống phát hành module phi tập trung của Go, cách bạn tổ chức mã nguồn rất quan trọng. Để biết thêm, xem Quản lý mã nguồn module.
Chuẩn bị để viết mã client cục bộ gọi các hàm trong module chưa được phát hành.

Trước khi bạn phát hành một module, nó chưa sẵn có cho quy trình quản lý phụ thuộc thông thường dùng các lệnh như go get. Một cách tốt để thử nghiệm mã module của bạn ở giai đoạn này là dùng nó khi nó nằm trong một thư mục cục bộ cạnh mã đang gọi.

Xem Viết mã dựa trên module chưa phát hành để biết thêm về phát triển cục bộ.
Khi mã của module đã sẵn sàng để các lập trình viên khác dùng thử, bắt đầu phát hành các bản pre-release v0 như alpha và beta. Xem Phát hành các phiên bản pre-release để biết thêm.
Phát hành một bản v0, chưa bảo đảm ổn định nhưng người dùng có thể dùng thử. Để biết thêm, xem Phát hành phiên bản đầu tiên (chưa ổn định).
Sau khi phiên bản v0 được phát hành, bạn có thể (và nên!) tiếp tục phát hành các phiên bản mới của nó.

Những phiên bản mới này có thể gồm các bản sửa lỗi (patch release), bổ sung vào API công khai của module (minor release), và thậm chí cả các thay đổi phá vỡ tương thích. Vì bản phát hành v0 không bảo đảm gì về tính ổn định hay tương thích ngược, bạn có thể tạo ra các thay đổi phá vỡ tương thích trong các phiên bản của nó.

Để biết thêm, xem Phát hành bản sửa lỗi và Phát hành các thay đổi API không phá vỡ tương thích.
Khi bạn chuẩn bị một phiên bản ổn định để phát hành, bạn phát hành các bản pre-release dạng alpha và beta. Để biết thêm, xem Phát hành các phiên bản pre-release.
Phát hành v1 với vai trò là bản phát hành ổn định đầu tiên.

Đây là bản phát hành đầu tiên đưa ra cam kết về tính ổn định của module. Để biết thêm, xem Phát hành phiên bản ổn định đầu tiên.
Trong phiên bản v1, tiếp tục sửa lỗi và, khi cần thiết, bổ sung vào API công khai của module.

Để biết thêm, xem Phát hành bản sửa lỗi và Phát hành các thay đổi API không phá vỡ tương thích.
Khi không thể tránh được, hãy phát hành các thay đổi phá vỡ tương thích trong một major version mới.

Việc cập nhật major version – chẳng hạn từ v1.x.x lên v2.x.x – có thể là một nâng cấp rất xáo trộn đối với người dùng module của bạn. Nó nên là lựa chọn cuối cùng. Để biết thêm, xem Phát hành các thay đổi API phá vỡ tương thích.

Viết mã dựa trên module chưa phát hành

Khi bạn bắt đầu phát triển một module hoặc một phiên bản mới của module, bạn chưa phát hành nó. Trước khi bạn phát hành một module, bạn sẽ chưa thể dùng các lệnh Go để thêm module đó làm phụ thuộc. Thay vào đó, lúc đầu, khi viết mã client trong một module khác gọi các hàm trong module chưa phát hành, bạn sẽ cần tham chiếu tới một bản sao của module trên hệ thống tệp cục bộ.

Bạn có thể tham chiếu một module cục bộ từ tệp go.mod của module client bằng cách dùng directive replace trong tệp go.mod của module client đó. Để biết thêm thông tin, xem Yêu cầu mã module trong một thư mục cục bộ.

Phát hành các phiên bản pre-release

Bạn có thể phát hành các phiên bản pre-release để module sẵn có cho người khác dùng thử và gửi phản hồi cho bạn. Phiên bản pre-release không kèm bảo đảm nào về tính ổn định.

Số phiên bản pre-release được nối thêm một định danh pre-release. Để biết thêm về số phiên bản, xem Cách đánh số phiên bản module.

Đây là hai ví dụ:

v0.2.1-beta.1
v1.2.3-alpha

Khi cung cấp một bản pre-release, hãy nhớ rằng lập trình viên dùng bản pre-release đó sẽ phải chỉ định rõ nó theo phiên bản bằng lệnh go get. Đó là vì, mặc định, lệnh go ưu tiên các phiên bản chính thức hơn các phiên bản pre-release khi tìm module mà bạn yêu cầu. Vì vậy lập trình viên phải lấy bản pre-release bằng cách chỉ định nó một cách tường minh, như trong ví dụ sau:

go get example.com/[email protected]

Bạn phát hành một bản pre-release bằng cách gắn tag cho mã module trong repository của bạn, chỉ định định danh pre-release trong tag. Để biết thêm, xem Phát hành một module.

Phát hành phiên bản đầu tiên (chưa ổn định)

Cũng như khi phát hành một phiên bản pre-release, bạn có thể phát hành các phiên bản chính thức không bảo đảm tính ổn định hay tương thích ngược, nhưng cho người dùng cơ hội dùng thử module và gửi phản hồi cho bạn.

Các bản phát hành chưa ổn định là những bản có số phiên bản nằm trong khoảng v0.x.x. Phiên bản v0 không đưa ra bảo đảm nào về tính ổn định hay tương thích ngược. Nhưng nó cho bạn một cách để nhận phản hồi và tinh chỉnh API trước khi đưa ra các cam kết về tính ổn định với v1 và về sau. Để biết thêm, xem Cách đánh số phiên bản module.

Như với các phiên bản đã phát hành khác, bạn có thể tăng phần minor và patch của số phiên bản v0 khi bạn thực hiện các thay đổi hướng tới việc phát hành một phiên bản v1 ổn định. Ví dụ, sau khi phát hành v.0.0.0, bạn có thể phát hành v0.0.1 với nhóm sửa lỗi đầu tiên.

Đây là một ví dụ về số phiên bản:

v0.1.3

Bạn phát hành một bản chưa ổn định bằng cách gắn tag cho mã module trong repository của bạn, chỉ định số phiên bản v0 trong tag. Để biết thêm, xem Phát hành một module.

Phát hành phiên bản ổn định đầu tiên

Bản phát hành ổn định đầu tiên của bạn sẽ có số phiên bản v1.x.x. Bản phát hành ổn định đầu tiên đến sau các bản pre-release và v0, qua đó bạn đã nhận phản hồi, sửa lỗi và ổn định hoá module cho người dùng.

Với một bản phát hành v1, bạn đưa ra những cam kết sau với các lập trình viên dùng module của bạn:

Họ có thể nâng cấp lên các bản minor và patch tiếp theo của major version đó mà không làm hỏng mã của chính họ.
Bạn sẽ không thực hiện thêm các thay đổi đối với API công khai của module – bao gồm cả chữ ký hàm và method của nó – làm phá vỡ tương thích ngược.
Bạn sẽ không loại bỏ bất kỳ kiểu dữ liệu exported nào, vì việc đó sẽ phá vỡ tương thích ngược.
Các thay đổi trong tương lai đối với API của bạn (chẳng hạn thêm một trường mới vào một struct) sẽ tương thích ngược và sẽ nằm trong một bản minor release mới.
Các bản sửa lỗi (chẳng hạn một bản vá bảo mật) sẽ nằm trong một bản patch release hoặc là một phần của bản minor release.

Lưu ý: Dù major version đầu tiên của bạn có thể là một bản phát hành v0, phiên bản v0 không báo hiệu bất kỳ bảo đảm nào về tính ổn định hay tương thích ngược. Do đó, khi bạn tăng từ v0 lên v1, bạn không cần bận tâm tới việc phá vỡ tương thích ngược, bởi bản phát hành v0 vốn không được xem là ổn định.

Để biết thêm về số phiên bản, xem Cách đánh số phiên bản module.

Đây là một ví dụ về số phiên bản ổn định:

v1.0.0

Bạn phát hành bản ổn định đầu tiên bằng cách gắn tag cho mã module trong repository của bạn, chỉ định số phiên bản v1 trong tag. Để biết thêm, xem Phát hành một module.

Phát hành bản sửa lỗi

Bạn có thể phát hành một bản trong đó các thay đổi chỉ giới hạn ở việc sửa lỗi. Đó gọi là patch release.

Một patch release chỉ bao gồm các thay đổi nhỏ. Cụ thể, nó không bao gồm thay đổi nào đối với API công khai của module. Lập trình viên của 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ọ.

Lưu ý: Patch release của bạn nên cố gắng không nâng cấp bất kỳ phụ thuộc bắc cầu nào của chính module đó vượt quá mức một patch release. Nếu không, người nâng cấp lên bản patch của module bạn có thể vô tình kéo theo một thay đổi sâu hơn ở một phụ thuộc bắc cầu mà họ đang dùng.

Một patch release làm tăng phần patch trong số phiên bản của module. Để biết thêm, xem Cách đánh số phiên bản module.

Trong ví dụ sau, v1.0.1 là một patch release.

Phiên bản cũ: v1.0.0

Phiên bản mới: v1.0.1

Bạn phát hành một patch release bằng cách gắn tag cho mã module trong repository của bạn, tăng số phiên bản patch trong tag. Để biết thêm, xem Phát hành một module.

Phát hành các thay đổi API không phá vỡ tương thích

Bạn có thể thực hiện các thay đổi không phá vỡ tương thích đối với API công khai của module và phát hành các thay đổi đó trong một bản phát hành minor.

Phiên bản này thay đổi API, 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. Ngay cả với những thay đổi mà nó bao gồm, loại bản phát hành này vẫn bảo đảm tương thích ngược và tính ổn định cho mã hiện có đang gọi các hàm của module.

Một minor release làm tăng phần minor trong số phiên bản của module. Để biết thêm, xem Cách đánh số phiên bản module.

Trong ví dụ sau, v1.1.0 là một minor release.

Phiên bản cũ: v1.0.1

Phiên bản mới: v1.1.0

Bạn phát hành một minor release bằng cách gắn tag cho mã module trong repository của bạn, tăng số phiên bản minor trong tag. Để biết thêm, xem Phát hành một module.

Phát hành các thay đổi API phá vỡ tương thích

Bạn có thể phát hành một phiên bản phá vỡ tương thích ngược bằng cách phát hành một bản phát hành major.

Một bản phát hành major version không bảo đảm tương thích ngược, thường là vì nó bao gồm các thay đổi đối với API công khai của module làm hỏng mã đang dùng các phiên bản trước của module.

Xét tới tác động xáo trộn mà việc nâng cấp major version có thể gây ra cho mã phụ thuộc vào module, bạn nên tránh cập nhật major version nếu có thể. Để biết thêm về việc cập nhật major version, xem Phát triển bản cập nhật major version. Để biết các chiến lược tránh tạo ra thay đổi phá vỡ tương thích, xem bài blog Keeping your modules compatible.

Trong khi việc phát hành các loại phiên bản khác về cơ bản chỉ đòi hỏi gắn tag mã module với số phiên bản, việc phát hành bản cập nhật major version đòi hỏi nhiều bước hơn.

Trước khi bắt đầu phát triển major version mới, hãy tạo trong repository của bạn một chỗ cho mã nguồn của phiên bản mới.

Một cách để làm việc này là tạo một branch mới trong repository dành riêng cho major version mới cùng các phiên bản minor và patch tiếp theo của nó. Để biết thêm, xem Quản lý mã nguồn module.
Trong tệp go.mod của module, sửa module path để nối thêm số major version mới, như trong ví dụ sau:
```
example.com/mymodule/v2
```
Vì module path là định danh của module, thay đổi này thực chất tạo ra một module mới. Nó cũng làm thay đổi package path, bảo đảm rằng lập trình viên sẽ không vô tình import một phiên bản làm hỏng mã của họ. Thay vào đó, những ai muốn nâng cấp sẽ phải thay thế tường minh các chỗ xuất hiện đường dẫn cũ bằng đường dẫn mới.
Trong mã của bạn, hãy đổi mọi package path nơi bạn import các package trong module bạn đang cập nhật, bao gồm cả các package trong chính module đó. Bạn cần làm việc này vì bạn đã đổi module path của mình.
Như với bất kỳ bản phát hành mới nào, bạn nên phát hành các phiên bản pre-release để nhận phản hồi và báo cáo lỗi trước khi phát hành bản chính thức.
Phát hành major version mới bằng cách gắn tag cho mã module trong repository của bạn, tăng số major version trong tag – chẳng hạn từ v1.5.2 lên v2.0.0.

Để biết thêm, xem Phát hành một module.