Kebijakan versioning, stabilitas, deprecation, dan dukungan

Sekilas pandang

Setiap halaman dokumentasi NextPDF membawa field lifecycle di front matter-nya: stability, since, deprecated_since, replaced_by, version_lifecycle, dan eol_date. Field-field tersebut sudah mengkodekan sebuah kontrak dukungan. Halaman ini menyatakan kontrak tersebut di satu tempat sehingga sebuah tim produksi dapat membaca metadata halaman mana pun dan menilai risiko mem-pin sebuah versi.

NextPDF mengikuti Semantic Versioning 2.0.0 untuk nomor rilisnya dan Conventional Commits 1.0.0 untuk generasi changelog. Service provider interface (kontrak publik di NextPDF\Contracts dan NextPDF\Event) diatur oleh aturan yang sama; lihat Aturan stabilitas SPI untuk mekanik tag @stability per-kontrak. Halaman ini adalah kebijakan yang lebih luas yang dispesialisasikan oleh aturan SPI.

Semantic versioning untuk NextPDF

Sebuah versi rilis adalah MAJOR.MINOR.PATCH. Posisi yang berubah memberi tahu Anda apa yang dapat berubah dalam kode Anda:

Increment	Apa artinya	Apa yang mungkin rusak
Major (3.x → 4.0.0)	Perubahan yang melanggar (breaking) diizinkan.	Sebuah kontrak stable mungkin mengubah signature atau dihapus; sebuah simbol deprecated yang ditandai pada major sebelumnya mungkin dihapus; perilaku default mungkin berubah.
Minor (6.0 → 6.1.0)	Penambahan yang kompatibel ke belakang.	Tidak ada untuk kontrak stable. Sebuah interface stable yang dipublikasikan tidak mendapat metode wajib baru; pertumbuhan datang dari kontrak/interface baru, metode opsional pada kelas konkret, dan opsi constructor/config baru dengan default. Sebuah kontrak experimental mungkin berubah di sini, dengan pemberitahuan deprecation terlebih dahulu.
Patch (4.0.0 → 3.2.1)	Perbaikan bug yang kompatibel ke belakang.	Tidak ada yang disengaja. Perilaku konvergen menuju kontrak yang terdokumentasi.

Aturan praktis untuk permukaan stable: sebuah constraint Composer seperti ^3.2 menerima setiap rilis minor dan patch dari lini major-nya tanpa perubahan yang melanggar. Perubahan yang melanggar hanya mendarat pada batas major.

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

Pin lebih ketat (misalnya ~3.2.0) ketika Anda bergantung pada kontrak experimental, karena sebuah kontrak experimental mungkin berubah dalam sebuah rilis minor.

Label stabilitas

Field stability sebuah halaman, dan tag sumber @stability sebuah kontrak, diambil dari kosakata yang sama. Label menyatakan kekuatan janji kompatibilitas.

Label	Apa yang dijaminnya	Di mana ia berubah
stable	Siap-produksi. Aman untuk diandalkan. Tidak ada perubahan yang melanggar dalam rilis minor atau patch. Sebuah interface stable (seperti SPI NextPDF\Contracts) tidak mendapat metode wajib baru dalam minor atau patch — pertumbuhan yang kompatibel ke belakang datang pada kontrak baru, sebagai metode opsional pada kelas konkret, atau melalui opsi constructor/config dengan default.	Hanya rilis major.
beta	Lengkap-fitur dan dapat digunakan, tetapi permukaannya belum dibekukan. Perlakukan seperti experimental untuk pinning: bungkus atau pin ketat.	Mungkin berubah dalam rilis minor, dengan pemberitahuan deprecation terlebih dahulu.
experimental	Dapat digunakan, tetapi secara eksplisit tidak dibekukan. NextPDF mungkin mengirim implementasi engine yang teruji sementara kontrak publik masih bergerak.	Mungkin berubah dalam rilis minor, dengan pemberitahuan deprecation terlebih dahulu.
deprecated	Dijadwalkan untuk penghapusan. Halaman atau kontrak menyatakan penggantinya dan major di mana ia dihapus.	Dihapus pada major berikutnya; tidak pernah dalam minor atau patch.

Kontrak streaming NextPDF\Contracts\CursorInterface dan NextPDF\Contracts\StreamingWriterInterface adalah contoh nyata permukaan experimental: NextPDF mengirim implementasi yang final dan teruji, tetapi kontrak publik mungkin masih berubah dalam rilis minor. Pin ketat atau bungkus kontrak semacam itu di balik adapter Anda sendiri sebelum Anda mengandalkannya di produksi.

Lifecycle deprecation

Deprecation adalah sebuah jalur empat-langkah yang terdefinisi. Ia selalu menamai penggantinya, dan penghapusan selalu ditunda ke batas major:

1. Mark. Pemilik menyetel @stability deprecated pada sebuah kontrak (atau deprecated_since pada sebuah halaman) dan mencatat pengganti serta major penghapusan. Pada sebuah halaman, deprecated_since adalah versi yang memperkenalkan deprecation dan replaced_by adalah path penerus kanonis.
2. Notice. Deprecation diumumkan dalam changelog untuk rilis yang menandainya.
3. Overlap. Permukaan yang di-deprecate dan penggantinya hidup berdampingan selama setidaknya satu rilis minor, sehingga Anda dapat bermigrasi tanpa flag day.
4. Remove. Permukaan dihapus dalam rilis major yang dinyatakan. Penghapusan tidak pernah terjadi dalam rilis minor atau patch.

Sebuah contoh tingkat-halaman yang telah menuntaskan seluruh alurnya: resep legasi /docs/cookbook/php/sign-pades/ ditandai deprecated_since: "3.0.0" dengan replaced_by: /docs/cookbook/php/sign-pades-b-b/, hidup berdampingan dengan penerusnya sepanjang jendela tumpang tindih, dan sejak itu telah dipensiunkan — URL lama kini menjawab dengan sebuah redirect permanen ke resep penerus, sehingga tautan yang ditulis terhadap halaman deprecated tetap berfungsi setelah penghapusan.

Rencanakan migrasi segera setelah sebuah permukaan ditandai deprecated. Karena penggantinya selalu dinyatakan dan keduanya tumpang tindih selama setidaknya satu minor, Anda dapat berpindah sebelum major penghapusan tiba.

Lifecycle versi dan dukungan keamanan

Field version_lifecycle mengklasifikasikan bagaimana sebuah jalur versi yang terdokumentasi dipelihara. Nilai-nilainya adalah:

version_lifecycle	Arti	Menerima
active	Jalur saat ini di bawah pengembangan aktif.	Fitur, perbaikan, dan perbaikan keamanan.
lts	Sebuah jalur long-term-support.	Perbaikan dan perbaikan keamanan untuk jendela dukungannya.
maintenance	Melewati pengembangan aktif, masih dipelihara.	Perbaikan keamanan dan perbaikan bug serius.
frozen	Tidak ada perubahan fungsional lebih lanjut yang direncanakan.	Hanya perbaikan keamanan, jika berlaku.
eol	End of life.	Tidak ada. Upgrade diperlukan.

Ketika sebuah jalur mencapai end of life, eol_date-nya mencatat tanggal (ISO 8601, YYYY-MM-DD). Sebuah halaman dengan version_lifecycle: eol dan eol_date yang sudah lampau adalah sinyal untuk bermigrasi keluar dari jalur itu: ia tidak lagi menerima perbaikan, termasuk perbaikan keamanan.

Ini adalah pernyataan kebijakan, bukan janji kalender. Field-field memberi tahu Anda kelas dukungan yang dimiliki sebuah jalur; konsultasikan changelog dan release notes untuk versi konkret yang membawa sebuah perbaikan tertentu. Perbaikan keamanan di-backport ke jalur yang lifecycle-nya masih mencakupnya (active, lts, dan maintenance), bukan ke jalur yang ditandai frozen-tanpa-keberlakuan atau eol.

Jendela dukungan versi PHP

NextPDF Core membutuhkan PHP >=8.4 <9.0. Jendela itu dideklarasikan dalam composer.json engine dan merupakan satu-satunya sumber kebenaran; paket premium (nextpdf/pro, nextpdf/enterprise) membutuhkan rentang yang sama.

• Batas bawah (>=8.4) adalah runtime minimum. Menaikkannya adalah perubahan yang melanggar dan hanya mendarat pada batas major.
• Batas atas (<9.0) mengecualikan PHP major berikutnya hingga ia divalidasi. Dukungan untuk PHP major baru ditambahkan dalam sebuah rilis NextPDF, bukan diasumsikan.

Halaman dokumentasi juga membawa sebuah list compatibility versi minor PHP yang sebuah resep diverifikasi terhadapnya. Sebuah halaman mungkin mencantumkan minor yang lebih lama (misalnya ["8.1", "8.2", "8.3", "8.4"]) di mana resep portabel, sementara lantai pemasangan keras engine tetap >=8.4. Jika ragu, constraint composer.json menang atas petunjuk compatibility sebuah halaman.

Cara membaca front matter lifecycle sebuah halaman

Gunakan enam field ini untuk menilai halaman mana pun sebelum Anda membangun di atasnya:

Field	Tipe	Cara membacanya
stability	stable | beta | experimental | deprecated	Janji kompatibilitas untuk permukaan yang didokumentasikan halaman.
since	SemVer (mis. "3.1.0")	Versi yang memperkenalkan permukaan yang terdokumentasi. Pemasangan Anda harus setidaknya versi ini.
deprecated_since	SemVer atau kosong	Jika disetel, permukaan di-deprecate; nilainya adalah versi yang men-deprecate-nya. Kosong berarti tidak di-deprecate.
replaced_by	Path situs atau kosong	Ketika di-deprecate, halaman penerus kanonis yang harus dimigrasi.
version_lifecycle	active | lts | maintenance | frozen | eol	Kelas pemeliharaan dari jalur yang terdokumentasi.
eol_date	Tanggal ISO atau kosong	Ketika version_lifecycle adalah eol, tanggal end-of-life. Kosong jika sebaliknya.

Sebuah pembacaan yang dikerjakan: sebuah halaman dengan stability: stable, since: "3.0.0", deprecated_since: "", dan version_lifecycle: active mendokumentasikan sebuah permukaan siap-produksi yang telah ada sejak 3.0.0, tidak di-deprecate, dan berada di jalur yang dipelihara secara aktif. Anda dapat mengandalkannya di bawah sebuah constraint major ^. Sebuah halaman dengan stability: deprecated dan replaced_by yang tidak kosong adalah sinyal migrasi: baca halaman penerus dan rencanakan perpindahan sebelum major berikutnya.

Konformitas

Kebijakan ini sesuai dengan Semantic Versioning 2.0.0 untuk penomoran versi dan dengan Conventional Commits 1.0.0 untuk generasi changelog. Jendela dukungan PHP adalah constraint >=8.4 <9.0 yang dideklarasikan dalam composer.json engine. Halaman ini tidak membuat klaim standar normatif tersendiri; ia mendokumentasikan kontrak dukungan yang sudah dikodekan oleh field front-matter lifecycle.

Lihat juga

• Aturan stabilitas SPI — tag @stability per-kontrak dan empat kelas janji kompatibilitas-ke-belakang (interface, enum, value-object beku, experimental).
• Matriks dukungan CSS — state dukungan per-modul yang diaudit-kebenaran untuk pipeline rendering HTML dan CSS.
• Indeks referensi — entry point untuk materi referensi API, konfigurasi, dan kompatibilitas.