Chính sách đánh phiên bản, độ ổn định, ngừng dùng, và hỗ trợ

Tổng quan nhanh

Mỗi trang tài liệu NextPDF mang các trường vòng đời trong front matter của nó: stability, since, deprecated_since, replaced_by, version_lifecycle, và eol_date. Các trường đó đã mã hóa một hợp đồng hỗ trợ. Trang này nêu hợp đồng đó ở một chỗ để một nhóm sản xuất có thể đọc siêu dữ liệu của bất kỳ trang nào và đánh giá rủi ro của việc ghim một phiên bản.

NextPDF tuân theo Semantic Versioning 2.0.0 cho các số phát hành của nó và Conventional Commits 1.0.0 cho việc tạo changelog. Giao diện nhà cung cấp dịch vụ (các hợp đồng công khai trong NextPDF\Contracts và NextPDF\Event) được chi phối bởi cùng các quy tắc; xem Các quy tắc độ ổn định SPI để biết cơ chế thẻ @stability theo-từng-hợp-đồng. Trang này là chính sách rộng hơn mà các quy tắc SPI chuyên biệt hóa.

Đánh phiên bản ngữ nghĩa cho NextPDF

Một phiên bản phát hành là MAJOR.MINOR.PATCH. Vị trí thay đổi cho bạn biết điều gì có thể thay đổi trong mã của bạn:

Mức tăng	Nó nghĩa là gì	Điều gì có thể vỡ
Major (`3.x` → `4.0.0`)	Các thay đổi phá vỡ được phép.	Một hợp đồng `stable` có thể thay đổi chữ ký hoặc bị loại bỏ; một ký hiệu đã ngừng dùng được đánh dấu trong major trước có thể bị xóa; hành vi mặc định có thể thay đổi.
Minor (`6.0` → `6.1.0`)	Các bổ sung tương thích ngược.	Không gì với một hợp đồng `stable`. Một giao diện stable đã công bố nhận không phương thức bắt buộc mới nào; sự tăng trưởng đến từ các hợp đồng/giao diện mới, các phương thức tùy chọn trên các lớp cụ thể, và các tùy chọn constructor/config mới với mặc định. Một hợp đồng `experimental` có thể thay đổi ở đây, với một thông báo ngừng dùng trước.
Patch (`4.0.0` → `3.2.1`)	Các sửa lỗi tương thích ngược.	Không gì có chủ ý. Hành vi hội tụ về hợp đồng đã tài liệu hóa.

Quy tắc thực tế cho một bề mặt stable: một ràng buộc Composer như ^3.2 nhận mọi bản phát hành minor và patch trong dòng major của nó mà không có thay đổi phá vỡ nào. Các thay đổi phá vỡ chỉ đáp xuống tại một ranh giới major.

{
    "require": {
        "nextpdf/core": "^3.2"
    }
}

Hãy ghim chặt hơn (ví dụ ~3.2.0) khi bạn phụ thuộc vào một hợp đồng experimental, vì một hợp đồng experimental có thể thay đổi trong một bản phát hành minor.

Các nhãn độ ổn định

Trường stability của một trang, và thẻ @stability nguồn của một hợp đồng, rút từ cùng một từ vựng. Nhãn nêu sức mạnh của lời hứa tương thích.

Nhãn	Nó đảm bảo gì	Nơi nó thay đổi
`stable`	Sẵn sàng cho môi trường thực tế. An toàn để phụ thuộc vào. Không thay đổi phá vỡ nào trong một bản phát hành minor hoặc patch. Một giao diện stable (như SPI `NextPDF\Contracts`) nhận không phương thức bắt buộc mới nào trong một minor hoặc patch — sự tăng trưởng tương thích ngược đến trên một hợp đồng mới, như một phương thức tùy chọn trên một lớp cụ thể, hoặc qua các tùy chọn constructor/config với mặc định.	Chỉ bản phát hành major.
`beta`	Hoàn chỉnh tính năng và dùng được, nhưng bề mặt chưa được đóng băng. Hãy đối xử với nó như `experimental` cho việc ghim: bọc hoặc ghim chặt.	Có thể thay đổi trong một bản phát hành minor, với một thông báo ngừng dùng trước.
`experimental`	Dùng được, nhưng tường minh là chưa được đóng băng. NextPDF có thể gửi một hiện thực engine đã được kiểm thử trong khi hợp đồng công khai vẫn còn chuyển động.	Có thể thay đổi trong một bản phát hành minor, với một thông báo ngừng dùng trước.
`deprecated`	Đã lên lịch loại bỏ. Trang hoặc hợp đồng nêu bản thay thế của nó và major mà trong đó nó bị loại bỏ.	Bị loại bỏ trong major kế tiếp; không bao giờ trong một minor hoặc patch.

Các hợp đồng ghi luồng NextPDF\Contracts\CursorInterface và NextPDF\Contracts\StreamingWriterInterface là các ví dụ thực về các bề mặt experimental: NextPDF gửi các hiện thực cuối cùng, đã được kiểm thử, nhưng hợp đồng công khai vẫn có thể thay đổi trong một bản phát hành minor. Hãy ghim chặt hoặc bọc một hợp đồng như vậy đằng sau adapter của riêng bạn trước khi bạn phụ thuộc vào nó trong môi trường thực tế.

Vòng đời ngừng dùng

Ngừng dùng là một đường bốn bước đã được xác định. Nó luôn đặt tên bản thay thế, và việc loại bỏ luôn được hoãn tới một ranh giới major:

Đánh dấu. Chủ sở hữu đặt @stability deprecated trên một hợp đồng (hoặc deprecated_since trên một trang) và ghi lại bản thay thế cùng major loại bỏ. Trên một trang, deprecated_since là phiên bản đã đưa ra việc ngừng dùng và replaced_by là đường dẫn kế tục chính tắc.
Thông báo. Việc ngừng dùng được công bố trong changelog cho bản phát hành đánh dấu nó.
Chồng lấn. Bề mặt đã ngừng dùng và bản thay thế của nó cùng tồn tại trong ít nhất một bản phát hành minor, để bạn có thể di trú mà không cần một ngày cờ.
Loại bỏ. Bề mặt bị loại bỏ trong bản phát hành major đã nêu. Việc loại bỏ không bao giờ xảy ra trong một bản phát hành minor hoặc patch.

Một ví dụ ở mức trang đã đi trọn vòng đời: công thức cũ /docs/cookbook/php/sign-pades/ từng được đánh dấu deprecated_since: "3.0.0" kèm replaced_by: /docs/cookbook/php/sign-pades-b-b/, cùng tồn tại với bản kế tục suốt cửa sổ chồng lấn, và từ đó đã bị loại bỏ — URL cũ nay trả về một chuyển hướng vĩnh viễn tới công thức kế tục, nên các liên kết trỏ tới trang đã đánh dấu deprecated vẫn hoạt động sau khi trang bị gỡ bỏ.

Hãy lập kế hoạch di trú ngay khi một bề mặt được đánh dấu deprecated. Vì bản thay thế luôn được nêu và cả hai chồng lấn trong ít nhất một minor, bạn có thể chuyển trước khi major loại bỏ tới.

Vòng đời phiên bản và hỗ trợ bảo mật

Trường version_lifecycle phân loại cách một dòng phiên bản đã tài liệu hóa được duy trì. Các giá trị là:

`version_lifecycle`	Ý nghĩa	Nhận
`active`	Dòng hiện tại đang được phát triển tích cực.	Tính năng, sửa lỗi, và sửa lỗi bảo mật.
`lts`	Một dòng hỗ trợ dài hạn.	Sửa lỗi và sửa lỗi bảo mật trong khoảng thời gian hỗ trợ của nó.
`maintenance`	Đã qua phát triển tích cực, vẫn được duy trì.	Sửa lỗi bảo mật và sửa lỗi nghiêm trọng.
`frozen`	Không có thay đổi chức năng nào nữa được lập kế hoạch.	Chỉ sửa lỗi bảo mật, ở nơi áp dụng được.
`eol`	Kết thúc vòng đời.	Không gì. Bắt buộc phải nâng cấp.

Khi một dòng đạt đến kết thúc vòng đời, eol_date của nó ghi lại ngày (ISO 8601, YYYY-MM-DD). Một trang với version_lifecycle: eol và một eol_date đã qua là một tín hiệu để di trú khỏi dòng đó: nó không còn nhận các sửa lỗi, bao gồm các sửa lỗi bảo mật.

Đây là một tuyên bố chính sách, không phải một lời hứa theo lịch. Các trường cho bạn biết lớp hỗ trợ mà một dòng đang ở trong; hãy tham khảo changelog và ghi chú phát hành cho phiên bản cụ thể mang một sửa lỗi nhất định. Các sửa lỗi bảo mật được backport tới các dòng mà vòng đời của chúng vẫn bao gồm chúng (active, lts, và maintenance), không phải tới các dòng được đánh dấu frozen-không-áp-dụng-được hoặc eol.

Cửa sổ hỗ trợ phiên bản PHP

NextPDF Core yêu cầu PHP >=8.4 <9.0. Cửa sổ đó được khai báo trong composer.json của engine và là nguồn sự thật duy nhất; các gói premium (nextpdf/pro, nextpdf/enterprise) yêu cầu cùng dải.

Cận dưới (>=8.4) là runtime tối thiểu. Nâng nó là một thay đổi phá vỡ và chỉ đáp xuống tại một ranh giới major.
Cận trên (<9.0) loại trừ major PHP kế tiếp cho đến khi nó đã được xác thực. Hỗ trợ cho một major PHP mới được thêm trong một bản phát hành NextPDF, không phải được giả định.

Các trang tài liệu cũng mang một danh sách compatibility của các phiên bản minor PHP mà một công thức được xác minh đối với. Một trang có thể liệt kê các minor cũ hơn (ví dụ ["8.1", "8.2", "8.3", "8.4"]) ở nơi công thức khả chuyển, trong khi sàn cài đặt cứng của engine vẫn là >=8.4. Khi nghi ngờ, ràng buộc composer.json thắng gợi ý compatibility của một trang.

Cách đọc front matter vòng đời của một trang

Hãy dùng sáu trường này để đánh giá bất kỳ trang nào trước khi bạn xây dựng trên nó:

Trường	Kiểu	Cách đọc nó
`stability`	`stable` \| `beta` \| `experimental` \| `deprecated`	Lời hứa tương thích cho bề mặt mà trang tài liệu hóa.
`since`	SemVer (ví dụ `"3.1.0"`)	Phiên bản đã đưa ra bề mặt đã tài liệu hóa. Bản cài của bạn phải ít nhất là phiên bản này.
`deprecated_since`	SemVer hoặc rỗng	Nếu được đặt, bề mặt đã ngừng dùng; giá trị là phiên bản đã ngừng dùng nó. Rỗng nghĩa là không ngừng dùng.
`replaced_by`	Đường dẫn site hoặc rỗng	Khi đã ngừng dùng, trang kế tục chính tắc để di trú tới.
`version_lifecycle`	`active` \| `lts` \| `maintenance` \| `frozen` \| `eol`	Lớp bảo trì của dòng đã tài liệu hóa.
`eol_date`	Ngày ISO hoặc rỗng	Khi `version_lifecycle` là `eol`, ngày kết thúc vòng đời. Rỗng nếu không.

Một lần đọc thực tế: một trang với stability: stable, since: "3.0.0", deprecated_since: "", và version_lifecycle: active tài liệu hóa một bề mặt sẵn sàng cho môi trường thực tế đã tồn tại từ 3.0.0, không ngừng dùng, và nằm trên dòng được duy trì tích cực. Bạn có thể phụ thuộc vào nó dưới một ràng buộc major ^. Một trang với stability: deprecated và một replaced_by không-rỗng là một tín hiệu di trú: hãy đọc trang kế tục và lập kế hoạch chuyển trước major kế tiếp.

Tuân thủ

Chính sách này tuân theo Semantic Versioning 2.0.0 cho việc đánh số phiên bản và Conventional Commits 1.0.0 cho việc tạo changelog. Cửa sổ hỗ trợ PHP là ràng buộc >=8.4 <9.0 được khai báo trong composer.json của engine. Trang này không đưa ra tuyên bố tiêu chuẩn quy phạm nào của riêng nó; nó tài liệu hóa hợp đồng hỗ trợ mà các trường front-matter vòng đời đã mã hóa.

Xem thêm

Các quy tắc độ ổn định SPI — thẻ @stability theo-từng-hợp-đồng và bốn lớp lời hứa tương thích ngược (interface, enum, value-object đã đóng băng, experimental).
Ma trận hỗ trợ CSS — trạng thái hỗ trợ theo-từng-module đã được kiểm toán sự thật cho pipeline kết xuất HTML và CSS.
Chỉ mục tham chiếu — điểm vào cho tài liệu tham chiếu API, cấu hình, và tương thích.