Sürümleme, kararlılık, kullanımdan kaldırma ve destek ilkesi

Bir bakışta

Her NextPDF belge sayfası, ön bilgisinde yaşam döngüsü alanları taşır: stability, since, deprecated_since, replaced_by, version_lifecycle ve eol_date. Bu alanlar zaten bir destek sözleşmesi kodlar. Bu sayfa, o sözleşmeyi tek bir yerde belirtir, böylece bir üretim ekibi herhangi bir sayfanın meta verisini okuyabilir ve bir sürümü sabitlemenin riskini değerlendirebilir.

NextPDF, sürüm numaraları için Semantic Versioning 2.0.0’ı ve değişiklik günlüğü üretimi için Conventional Commits 1.0.0’ı izler. Hizmet sağlayıcı arayüzü (NextPDF\Contracts ve NextPDF\Event içindeki genel sözleşmeler) aynı kurallarla yönetilir; sözleşme başına @stability etiketi mekaniği için SPI kararlılık kuralları sayfasına bakın. Bu sayfa, SPI kurallarının özelleştirdiği daha geniş ilkedir.

NextPDF için anlamsal sürümleme

Bir sürüm MAJOR.MINOR.PATCH’tir. Değişen konum, kodunuzda neyin değişebileceğini size söyler:

Artırma	Ne anlama geldiği	Neyin bozulabileceği
Major (3.x → 4.0.0)	Bozucu değişikliklere izin verilir.	Bir stable sözleşme imza değiştirebilir veya kaldırılabilir; önceki major’da işaretlenmiş kullanımdan kaldırılmış bir sembol silinebilir; varsayılan davranış değişebilir.
Minor (6.0 → 6.1.0)	Geriye dönük uyumlu eklemeler.	Bir stable sözleşme için hiçbir şey. Yayımlanmış kararlı bir arayüz hiçbir yeni gerekli yöntem kazanmaz; büyüme yeni sözleşmelerden/arayüzlerden, somut sınıflardaki isteğe bağlı yöntemlerden ve varsayılanlı yeni yapıcı/yapılandırma seçeneklerinden gelir. Bir experimental sözleşme burada, önce bir kullanımdan kaldırma bildirimiyle değişebilir.
Patch (4.0.0 → 3.2.1)	Geriye dönük uyumlu hata düzeltmeleri.	Kasıtlı hiçbir şey. Davranış, belgelenmiş sözleşmeye doğru yakınsar.

stable bir yüzey için pratik kural: ^3.2 gibi bir Composer kısıtlaması, kendi major satırının her minor ve patch sürümünü bozucu bir değişiklik olmadan alır. Bozucu değişiklikler yalnızca bir major sınırında iner.

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

Bir experimental sözleşmeye bağımlı olduğunuzda daha sıkı sabitleyin (örneğin ~3.2.0), çünkü bir experimental sözleşme bir minor sürümde değişebilir.

Kararlılık etiketleri

Bir sayfanın stability alanı ve bir sözleşmenin kaynak @stability etiketi, aynı sözcük dağarcığından çekilir. Etiket, uyumluluk vaadinin gücünü belirtir.

Etiket	Neyi garanti ettiği	Nerede değiştiği
stable	Üretime hazır. Bağımlı olmak güvenli. Bir minor veya patch sürümünde bozucu değişiklik yok. Kararlı bir arayüz (örneğin NextPDF\Contracts SPI) bir minor veya patch’te hiçbir yeni gerekli yöntem kazanmaz — geriye dönük uyumlu büyüme yeni bir sözleşmede, somut bir sınıftaki isteğe bağlı bir yöntem olarak ya da varsayılanlı yapıcı/yapılandırma seçenekleriyle gelir.	Yalnızca major sürümde.
beta	Özellik açısından eksiksiz ve kullanılabilir, ancak yüzey henüz dondurulmamış. Sabitleme için onu experimental gibi ele alın: sarın ya da sıkı sabitleyin.	Bir minor sürümde, önce bir kullanımdan kaldırma bildirimiyle değişebilir.
experimental	Kullanılabilir, ancak açıkça dondurulmamış. NextPDF, genel sözleşme hâlâ hareket ederken test edilmiş bir motor uygulaması gönderebilir.	Bir minor sürümde, önce bir kullanımdan kaldırma bildirimiyle değişebilir.
deprecated	Kaldırılmak üzere planlanmış. Sayfa veya sözleşme, değiştiricisini ve kaldırıldığı major’ı belirtir.	Bir sonraki major’da kaldırılır; asla bir minor veya patch’te değil.

Akış sözleşmeleri NextPDF\Contracts\CursorInterface ve NextPDF\Contracts\StreamingWriterInterface, experimental yüzeylerin gerçek örnekleridir: NextPDF nihai, test edilmiş uygulamalar gönderir, ancak genel sözleşme bir minor sürümde hâlâ değişebilir. Üretimde ona bağımlı olmadan önce böyle bir sözleşmeyi sıkı sabitleyin veya kendi adaptörünüzün ardına sarın.

Kullanımdan kaldırma yaşam döngüsü

Kullanımdan kaldırma, tanımlı, dört adımlı bir yoldur. Her zaman değiştiriciyi adlandırır ve kaldırma her zaman bir major sınırına ertelenir:

1. İşaretle. Sahibi, bir sözleşmede @stability deprecated (ya da bir sayfada deprecated_since) ayarlar ve değiştiriciyi ve kaldırma major’ını kaydeder. Bir sayfada deprecated_since, kullanımdan kaldırmayı tanıtan sürümdür ve replaced_by, kanonik halefin yoludur.
2. Bildirim. Kullanımdan kaldırma, onu işaretleyen sürümün değişiklik günlüğünde duyurulur.
3. Örtüşme. Kullanımdan kaldırılmış yüzey ve değiştiricisi en az bir minor sürüm boyunca bir arada bulunur, böylece bir geçiş günü olmadan taşıyabilirsiniz.
4. Kaldır. Yüzey, belirtilen major sürümde kaldırılır. Kaldırma asla bir minor veya patch sürümünde gerçekleşmez.

Belgelerde yaşam döngüsünün tamamından geçmiş bir sayfa düzeyinde örnek: eski /docs/cookbook/php/sign-pades/ tarifi deprecated_since: "3.0.0" ve replaced_by: /docs/cookbook/php/sign-pades-b-b/ ile işaretlendi, örtüşme penceresi boyunca halefiyle bir arada bulundu ve o zamandan beri kaldırıldı — eski URL artık halef tarifine kalıcı bir yönlendirmeyle yanıt verir, böylece kullanımdan kaldırılmış sayfaya karşı yazılmış bağlantılar kaldırmadan sonra da çalışmaya devam eder.

Bir yüzey deprecated olarak işaretlendiğinde hemen bir geçiş planlayın. Değiştirici her zaman belirtildiğinden ve ikisi en az bir minor boyunca örtüştüğünden, kaldıran major gelmeden taşınabilirsiniz.

Sürüm yaşam döngüsü ve güvenlik desteği

version_lifecycle alanı, belgelenmiş bir sürüm satırının nasıl bakıldığını sınıflandırır. Değerler şunlardır:

version_lifecycle	Anlamı	Aldığı
active	Etkin geliştirme altındaki geçerli satır.	Özellikler, düzeltmeler ve güvenlik düzeltmeleri.
lts	Uzun vadeli destek satırı.	Destek penceresi boyunca düzeltmeler ve güvenlik düzeltmeleri.
maintenance	Etkin geliştirmenin ötesinde, hâlâ bakılan.	Güvenlik düzeltmeleri ve ciddi hata düzeltmeleri.
frozen	Daha fazla işlevsel değişiklik planlanmadı.	Yalnızca, uygulanabilir olduğu yerde güvenlik düzeltmeleri.
eol	Kullanım ömrü sonu.	Hiçbir şey. Yükseltme gereklidir.

Bir satır kullanım ömrü sonuna ulaştığında, eol_date tarihi kaydeder (ISO 8601, YYYY-MM-DD). version_lifecycle: eol ve geçmiş bir eol_date ile bir sayfa, o satırdan taşınma sinyalidir: artık güvenlik düzeltmeleri dâhil hiçbir düzeltme almaz.

Bu bir ilke beyanıdır, bir takvim vaadi değil. Alanlar size bir satırın hangi destek sınıfında olduğunu söyler; belirli bir düzeltmeyi taşıyan somut sürüm için değişiklik günlüğüne ve sürüm notlarına başvurun. Güvenlik düzeltmeleri, yaşam döngüleri hâlâ onları içeren satırlara (active, lts ve maintenance) geri taşınır, frozen-uygulanamaz veya eol olarak işaretlenmiş satırlara değil.

PHP sürüm destek penceresi

NextPDF Core, PHP >=8.4 <9.0 gerektirir. O pencere motorun composer.json dosyasında bildirilir ve tek doğru kaynaktır; premium paketleri (nextpdf/pro, nextpdf/enterprise) aynı aralığı gerektirir.

• Alt sınır (>=8.4), en düşük çalışma zamanıdır. Onu yükseltmek bozucu bir değişikliktir ve yalnızca bir major sınırında iner.
• Üst sınır (<9.0), bir sonraki PHP major’ını, doğrulanana kadar dışlar. Yeni bir PHP major’ı için destek, varsayılmaz, bir NextPDF sürümünde eklenir.

Belge sayfaları ayrıca bir tarifin doğrulandığı PHP minor sürümlerinin bir compatibility listesini taşır. Bir sayfa, tarifin taşınabilir olduğu daha eski minor’ları listeleyebilir (örneğin ["8.1", "8.2", "8.3", "8.4"]), motorun sert kurulum tabanı >=8.4 olarak kalırken. Kuşkuya düştüğünüzde, composer.json kısıtlaması bir sayfanın compatibility ipucuna karşı kazanır.

Bir sayfanın yaşam döngüsü ön bilgisi nasıl okunur

Üzerine inşa etmeden önce herhangi bir sayfayı değerlendirmek için bu altı alanı kullanın:

Alan	Tür	Nasıl okunur
stability	stable | beta | experimental | deprecated	Sayfanın belgelediği yüzey için uyumluluk vaadi.
since	SemVer (ör. "3.1.0")	Belgelenen yüzeyi tanıtan sürüm. Kurulumunuz en az bu sürüm olmalıdır.
deprecated_since	SemVer veya boş	Ayarlıysa, yüzey kullanımdan kaldırılmıştır; değer, onu kullanımdan kaldıran sürümdür. Boş, kullanımdan kaldırılmadığı anlamına gelir.
replaced_by	Site yolu veya boş	Kullanımdan kaldırıldığında, taşınılacak kanonik halef sayfa.
version_lifecycle	active | lts | maintenance | frozen | eol	Belgelenen satırın bakım sınıfı.
eol_date	ISO tarihi veya boş	version_lifecycle eol olduğunda, kullanım ömrü sonu tarihi. Aksi takdirde boş.

İşlenmiş bir okuma: stability: stable, since: "3.0.0", deprecated_since: "" ve version_lifecycle: active ile bir sayfa, 3.0.0’dan beri var olan, kullanımdan kaldırılmamış ve etkin olarak bakılan satırda yer alan üretime hazır bir yüzeyi belgeler. Ona bir ^ major kısıtlaması altında bağımlı olabilirsiniz. stability: deprecated ve boş olmayan bir replaced_by ile bir sayfa, bir taşınma sinyalidir: halef sayfayı okuyun ve bir sonraki major’dan önce taşınmayı planlayın.

Uyumluluk

Bu ilke, sürüm numaralandırma için Semantic Versioning 2.0.0’a ve değişiklik günlüğü üretimi için Conventional Commits 1.0.0’a uyar. PHP destek penceresi, motor composer.json dosyasında bildirilen >=8.4 <9.0 kısıtlamasıdır. Bu sayfa, kendine ait normatif bir standart iddiasında bulunmaz; yaşam döngüsü ön bilgi alanlarının zaten kodladığı destek sözleşmesini belgeler.

Ayrıca bakınız

• SPI kararlılık kuralları — sözleşme başına @stability etiketi ve dört geriye dönük uyumluluk vaadi sınıfı (arayüz, enum, dondurulmuş değer-nesnesi, deneysel).
• CSS destek matrisi — HTML ve CSS işleme işlem hattı için gerçeklik denetimli modül başına destek durumu.
• Referans dizini — API, yapılandırma ve uyumluluk referans malzemesi için giriş noktası.