Polityka wersjonowania, stabilności, deprecjacji i wsparcia

W skrócie

Każda strona dokumentacji NextPDF niesie pola cyklu życia w swoim front matter: stability, since, deprecated_since, replaced_by, version_lifecycle oraz eol_date. Te pola już kodują kontrakt wsparcia. Ta strona przedstawia ten kontrakt w jednym miejscu, aby zespół produkcyjny mógł odczytać metadane dowolnej strony i ocenić ryzyko przypięcia danej wersji.

NextPDF stosuje Semantic Versioning 2.0.0 dla numerów wydań oraz Conventional Commits 1.0.0 do generowania dziennika zmian. Interfejs dostawcy usług (publiczne kontrakty w NextPDF\Contracts oraz NextPDF\Event) podlega tym samym regułom; zobacz Reguły stabilności SPI dla mechaniki znacznika @stability per kontrakt. Ta strona to szersza polityka, którą reguły SPI uszczegóławiają.

Wersjonowanie semantyczne dla NextPDF

Wersja wydania to MAJOR.MINOR.PATCH. Pozycja, która się zmienia, mówi Ci, co może się zmienić w Twoim kodzie:

Inkrementacja	Co oznacza	Co może się zepsuć
Główna (3.x → 4.0.0)	Zmiany łamiące są dozwolone.	Kontrakt stable może zmienić sygnaturę lub zostać usunięty; symbol zdeprecjonowany oznaczony w poprzedniej wersji głównej może zostać skasowany; domyślne zachowanie może się zmienić.
Pomocnicza (6.0 → 6.1.0)	Dodatki wstecznie zgodne.	Nic dla kontraktu stable. Opublikowany stabilny interfejs nie zyskuje żadnych nowych wymaganych metod; wzrost pochodzi z nowych kontraktów/interfejsów, opcjonalnych metod na klasach konkretnych oraz nowych opcji konstruktora/konfiguracji z wartościami domyślnymi. Kontrakt experimental może się tu zmienić, najpierw z powiadomieniem o deprecjacji.
Poprawkowa (4.0.0 → 3.2.1)	Wstecznie zgodne poprawki błędów.	Nic zamierzonego. Zachowanie zbiega się ku udokumentowanemu kontraktowi.

Praktyczna reguła dla powierzchni stable: ograniczenie Composera takie jak ^3.2 otrzymuje każde wydanie pomocnicze i poprawkowe swojej linii głównej bez zmiany łamiącej. Zmiany łamiące lądują wyłącznie na granicy wersji głównej.

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

Przypnij ciaśniej (na przykład ~3.2.0), gdy zależysz od kontraktu experimental, ponieważ kontrakt experimental może się zmienić w wydaniu pomocniczym.

Etykiety stabilności

Pole stability strony oraz źródłowy znacznik @stability kontraktu czerpią z tego samego słownictwa. Etykieta podaje siłę obietnicy zgodności.

Etykieta	Co gwarantuje	Gdzie się zmienia
stable	Gotowy do produkcji. Bezpiecznie polegać. Brak zmiany łamiącej w wydaniu pomocniczym lub poprawkowym. Stabilny interfejs (taki jak SPI NextPDF\Contracts) nie zyskuje nowych wymaganych metod w wydaniu pomocniczym ani poprawkowym — wstecznie zgodny wzrost przybywa na nowym kontrakcie, jako opcjonalna metoda na klasie konkretnej albo przez opcje konstruktora/konfiguracji z wartościami domyślnymi.	Tylko wydanie główne.
beta	Kompletny funkcjonalnie i użyteczny, ale powierzchnia jeszcze nie zamrożona. Traktuj go jak experimental przy przypinaniu: opakuj lub przypnij ciasno.	Może się zmienić w wydaniu pomocniczym, najpierw z powiadomieniem o deprecjacji.
experimental	Użyteczny, ale jawnie niezamrożony. NextPDF może wydać przetestowaną implementację silnika, podczas gdy publiczny kontrakt wciąż się zmienia.	Może się zmienić w wydaniu pomocniczym, najpierw z powiadomieniem o deprecjacji.
deprecated	Zaplanowany do usunięcia. Strona lub kontrakt podaje swój zamiennik oraz wersję główną, w której zostaje usunięty.	Usuwany w następnej wersji głównej; nigdy w pomocniczej ani poprawkowej.

Kontrakty strumieniowe NextPDF\Contracts\CursorInterface oraz NextPDF\Contracts\StreamingWriterInterface to rzeczywiste przykłady powierzchni experimental: NextPDF dostarcza ostateczne, przetestowane implementacje, ale publiczny kontrakt wciąż może się zmienić w wydaniu pomocniczym. Przypnij ciasno lub opakuj taki kontrakt za własnym adapterem, zanim oprzesz na nim produkcję.

Cykl życia deprecjacji

Deprecjacja to zdefiniowana, czteroetapowa ścieżka. Zawsze nazywa zamiennik, a usunięcie zawsze jest odroczone do granicy wersji głównej:

1. Oznacz. Właściciel ustawia @stability deprecated na kontrakcie (lub deprecated_since na stronie) i zapisuje zamiennik oraz wersję główną usunięcia. Na stronie deprecated_since to wersja, która wprowadziła deprecjację, a replaced_by to kanoniczna ścieżka następcy.
2. Powiadom. Deprecjacja jest ogłaszana w dzienniku zmian dla wydania, które ją oznacza.
3. Nakładanie. Zdeprecjonowana powierzchnia i jej zamiennik współistnieją przez co najmniej jedno wydanie pomocnicze, dzięki czemu możesz migrować bez dnia przełomu.
4. Usuń. Powierzchnia jest usuwana w podanym wydaniu głównym. Usunięcie nigdy nie następuje w wydaniu pomocniczym ani poprawkowym.

Przykład na poziomie strony, który przeszedł cały łuk cyklu życia: starszy przepis /docs/cookbook/php/sign-pades/ został oznaczony deprecated_since: "3.0.0" wraz z replaced_by: /docs/cookbook/php/sign-pades-b-b/, współistniał ze swoim następcą przez okno nakładania, a od tamtej pory został wycofany — stary adres URL odpowiada teraz trwałym przekierowaniem do przepisu następcy, więc odnośniki napisane wobec strony deprecated nadal działają po jej usunięciu.

Zaplanuj migrację, gdy tylko powierzchnia zostanie oznaczona jako deprecated. Ponieważ zamiennik jest zawsze podany, a oba nakładają się przez co najmniej jedno wydanie pomocnicze, możesz przejść, zanim nadejdzie usuwająca wersja główna.

Cykl życia wersji i wsparcie bezpieczeństwa

Pole version_lifecycle klasyfikuje sposób utrzymywania udokumentowanej linii wersji. Wartości to:

version_lifecycle	Znaczenie	Otrzymuje
active	Bieżąca linia pod aktywnym rozwojem.	Funkcje, poprawki oraz poprawki bezpieczeństwa.
lts	Linia z długoterminowym wsparciem.	Poprawki oraz poprawki bezpieczeństwa przez okno wsparcia.
maintenance	Po aktywnym rozwoju, wciąż utrzymywana.	Poprawki bezpieczeństwa oraz poprawki poważnych błędów.
frozen	Brak planowanych dalszych zmian funkcjonalnych.	Tylko poprawki bezpieczeństwa, tam gdzie mają zastosowanie.
eol	Koniec życia.	Nic. Wymagana aktualizacja.

Gdy linia osiąga koniec życia, jej eol_date zapisuje datę (ISO 8601, YYYY-MM-DD). Strona z version_lifecycle: eol oraz przeszłą eol_date to sygnał do migracji z tej linii: nie otrzymuje już poprawek, w tym poprawek bezpieczeństwa.

To stwierdzenie polityki, a nie obietnica kalendarzowa. Pola mówią Ci o klasie wsparcia, w której znajduje się linia; po konkretną wersję, która niesie dany poprawek, sięgnij do dziennika zmian i informacji o wydaniu. Poprawki bezpieczeństwa są backportowane do linii, których cykl życia wciąż je obejmuje (active, lts oraz maintenance), a nie do linii oznaczonych frozen-bez-zastosowania ani eol.

Okno wsparcia wersji PHP

NextPDF Core wymaga PHP >=8.4 <9.0. To okno jest zadeklarowane w composer.json silnika i jest jedynym źródłem prawdy; pakiety premium (nextpdf/pro, nextpdf/enterprise) wymagają tego samego zakresu.

• Dolna granica (>=8.4) to minimalne środowisko uruchomieniowe. Jej podniesienie to zmiana łamiąca i ląduje wyłącznie na granicy wersji głównej.
• Górna granica (<9.0) wyklucza następną wersję główną PHP, dopóki nie zostanie zwalidowana. Wsparcie dla nowej wersji głównej PHP jest dodawane w wydaniu NextPDF, a nie zakładane.

Strony dokumentacji niosą również listę compatibility wersji pomocniczych PHP, wobec których przepis jest zweryfikowany. Strona może wymieniać starsze wersje pomocnicze (na przykład ["8.1", "8.2", "8.3", "8.4"]), gdzie przepis jest przenośny, podczas gdy twardy próg instalacji silnika pozostaje >=8.4. W razie wątpliwości ograniczenie composer.json ma pierwszeństwo nad podpowiedzią compatibility strony.

Jak czytać front matter cyklu życia strony

Użyj tych sześciu pól do oceny dowolnej strony, zanim na niej zbudujesz:

Pole	Typ	Jak je czytać
stability	stable | beta | experimental | deprecated	Obietnica zgodności dla powierzchni, którą strona dokumentuje.
since	SemVer (np. "3.1.0")	Wersja, która wprowadziła udokumentowaną powierzchnię. Twoja instalacja musi być co najmniej w tej wersji.
deprecated_since	SemVer lub pusta	Jeśli ustawione, powierzchnia jest zdeprecjonowana; wartość to wersja, która ją zdeprecjonowała. Pusta oznacza brak deprecjacji.
replaced_by	Ścieżka witryny lub pusta	Gdy zdeprecjonowane, kanoniczna strona następcy, na którą należy migrować.
version_lifecycle	active | lts | maintenance | frozen | eol	Klasa utrzymania udokumentowanej linii.
eol_date	Data ISO lub pusta	Gdy version_lifecycle to eol, data końca życia. W przeciwnym razie pusta.

Przepracowany odczyt: strona z stability: stable, since: "3.0.0", deprecated_since: "" oraz version_lifecycle: active dokumentuje gotową do produkcji powierzchnię, która istnieje od 3.0.0, nie jest zdeprecjonowana i znajduje się na aktywnie utrzymywanej linii. Możesz na niej polegać pod ograniczeniem głównym ^. Strona z stability: deprecated oraz niepustym replaced_by to sygnał migracji: przeczytaj stronę następcy i zaplanuj przejście przed następną wersją główną.

Zgodność

Ta polityka jest zgodna z Semantic Versioning 2.0.0 dla numerowania wersji oraz z Conventional Commits 1.0.0 dla generowania dziennika zmian. Okno wsparcia PHP to ograniczenie >=8.4 <9.0 zadeklarowane w composer.json silnika. Ta strona nie zgłasza własnego normatywnego roszczenia co do standardów; dokumentuje kontrakt wsparcia, który pola cyklu życia front matter już kodują.

Zobacz także

• Reguły stabilności SPI — znacznik @stability per kontrakt oraz cztery klasy obietnicy wstecznej zgodności (interfejs, wyliczenie, zamrożony obiekt wartości, eksperymentalny).
• Macierz wsparcia CSS — zweryfikowany pod kątem prawdziwości stan wsparcia per moduł dla potoku renderowania HTML i CSS.
• Indeks dokumentacji referencyjnej — punkt wejścia do materiałów referencyjnych API, konfiguracji i zgodności.