Política de versionamento, estabilidade, depreciação e suporte

Visão geral

Toda página de documentação do NextPDF carrega campos de ciclo de vida em seu front matter: stability, since, deprecated_since, replaced_by, version_lifecycle e eol_date. Esses campos já codificam um contrato de suporte. Esta página declara esse contrato em um único lugar para que uma equipe de produção possa ler os metadados de qualquer página e avaliar o risco de fixar uma versão.

O NextPDF segue o Semantic Versioning 2.0.0 para seus números de release e os Conventional Commits 1.0.0 para a geração de changelog. A service provider interface (os contratos públicos em NextPDF\Contracts e NextPDF\Event) é governada pelas mesmas regras; consulte Regras de estabilidade da SPI para a mecânica da tag @stability por contrato. Esta página é a política mais ampla que as regras da SPI especializam.

Versionamento semântico para o NextPDF

Uma versão de release é MAJOR.MINOR.PATCH. A posição que muda diz a você o que pode mudar no seu código:

Incremento	O que significa	O que pode quebrar
Major (3.x → 4.0.0)	Mudanças que quebram compatibilidade são permitidas.	Um contrato stable pode mudar de assinatura ou ser removido; um símbolo depreciado marcado no major anterior pode ser deletado; o comportamento padrão pode mudar.
Minor (6.0 → 6.1.0)	Adições compatíveis com versões anteriores.	Nada para um contrato stable. Uma interface estável publicada ganha nenhum novo método obrigatório; o crescimento vem de novos contratos/interfaces, métodos opcionais em classes concretas e novas opções de construtor/config com padrões. Um contrato experimental pode mudar aqui, com um aviso de depreciação primeiro.
Patch (4.0.0 → 3.2.1)	Correções de bug compatíveis com versões anteriores.	Nada intencional. O comportamento converge em direção ao contrato documentado.

A regra prática para uma superfície stable: uma restrição do Composer como ^3.2 recebe cada release minor e patch da sua linha major sem nenhuma mudança que quebre compatibilidade. Mudanças que quebram compatibilidade só chegam em uma fronteira major.

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

Fixe mais estritamente (por exemplo ~3.2.0) quando você depende de um contrato experimental, porque um contrato experimental pode mudar em uma release minor.

Rótulos de estabilidade

O campo stability de uma página, e a tag @stability da fonte de um contrato, extraem do mesmo vocabulário. O rótulo declara a força da promessa de compatibilidade.

Rótulo	O que garante	Onde muda
stable	Pronto para produção. Seguro para depender. Nenhuma mudança que quebre compatibilidade em uma release minor ou patch. Uma interface estável (como a SPI NextPDF\Contracts) não ganha novos métodos obrigatórios em uma minor ou patch — o crescimento compatível com versões anteriores chega em um novo contrato, como um método opcional em uma classe concreta, ou via opções de construtor/config com padrões.	Apenas em release major.
beta	Completa em funcionalidade e utilizável, mas a superfície ainda não está congelada. Trate-a como experimental para fins de fixação: encapsule ou fixe estritamente.	Pode mudar em uma release minor, com um aviso de depreciação primeiro.
experimental	Utilizável, mas explicitamente não congelada. O NextPDF pode entregar uma implementação de engine testada enquanto o contrato público ainda se move.	Pode mudar em uma release minor, com um aviso de depreciação primeiro.
deprecated	Agendada para remoção. A página ou o contrato declara seu substituto e o major em que é removida.	Removida no próximo major; nunca em uma minor ou patch.

Os contratos de streaming NextPDF\Contracts\CursorInterface e NextPDF\Contracts\StreamingWriterInterface são exemplos reais de superfícies experimental: o NextPDF entrega implementações finais e testadas, mas o contrato público ainda pode mudar em uma release minor. Fixe estritamente ou encapsule tal contrato atrás do seu próprio adaptador antes de depender dele em produção.

Ciclo de vida de depreciação

A depreciação é um caminho definido de quatro etapas. Ela sempre nomeia o substituto, e a remoção é sempre adiada para uma fronteira major:

1. Marcar. O owner define @stability deprecated em um contrato (ou deprecated_since em uma página) e registra o substituto e o major de remoção. Em uma página, deprecated_since é a versão que introduziu a depreciação e replaced_by é o caminho do sucessor canônico.
2. Aviso. A depreciação é anunciada no changelog da release que a marca.
3. Sobreposição. A superfície depreciada e seu substituto coexistem por pelo menos uma release minor, para que você possa migrar sem um dia de virada.
4. Remover. A superfície é removida na release major declarada. A remoção nunca acontece em uma release minor ou patch.

Um exemplo em nível de página que já percorreu o ciclo de vida completo: a receita legada /docs/cookbook/php/sign-pades/ foi marcada com deprecated_since: "3.0.0" e replaced_by: /docs/cookbook/php/sign-pades-b-b/, coexistiu com o seu sucessor durante a janela de sobreposição e, desde então, foi removida — a URL antiga agora responde com um redirecionamento permanente para a receita sucessora, de modo que os links escritos para a página depreciada continuam funcionando mesmo após a remoção.

Planeje uma migração assim que uma superfície for marcada como deprecated. Como o substituto é sempre declarado e os dois se sobrepõem por pelo menos uma minor, você pode mudar antes de o major de remoção chegar.

Ciclo de vida de versão e suporte de segurança

O campo version_lifecycle classifica como uma linha de versão documentada é mantida. Os valores são:

version_lifecycle	Significado	Recebe
active	A linha atual sob desenvolvimento ativo.	Recursos, correções e correções de segurança.
lts	Uma linha de suporte de longo prazo.	Correções e correções de segurança durante sua janela de suporte.
maintenance	Passou do desenvolvimento ativo, ainda mantida.	Correções de segurança e correções de bugs sérios.
frozen	Nenhuma mudança funcional adicional planejada.	Apenas correções de segurança, onde aplicável.
eol	Fim de vida.	Nada. A atualização é obrigatória.

Quando uma linha atinge o fim de vida, seu eol_date registra a data (ISO 8601, YYYY-MM-DD). Uma página com version_lifecycle: eol e um eol_date no passado é um sinal para migrar para fora dessa linha: ela não recebe mais correções, incluindo correções de segurança.

Esta é uma declaração de política, não uma promessa de calendário. Os campos dizem a você a classe de suporte em que uma linha está; consulte o changelog e as notas de release para a versão concreta que carrega uma determinada correção. As correções de segurança são backportadas para as linhas cujo ciclo de vida ainda as inclui (active, lts e maintenance), não para linhas marcadas como frozen-sem-aplicabilidade ou eol.

Janela de suporte de versão do PHP

O NextPDF Core exige PHP >=8.4 <9.0. Essa janela é declarada no composer.json do engine e é a única fonte da verdade; os pacotes premium (nextpdf/pro, nextpdf/enterprise) exigem o mesmo intervalo.

• O limite inferior (>=8.4) é o runtime mínimo. Elevá-lo é uma mudança que quebra compatibilidade e só chega em uma fronteira major.
• O limite superior (<9.0) exclui o próximo major do PHP até que ele tenha sido validado. O suporte a um novo major do PHP é adicionado em uma release do NextPDF, não presumido.

As páginas de documentação também carregam uma lista compatibility das versões minor do PHP contra as quais uma receita foi verificada. Uma página pode listar minors mais antigas (por exemplo ["8.1", "8.2", "8.3", "8.4"]) onde a receita é portável, enquanto o piso de instalação rígido do engine permanece >=8.4. Na dúvida, a restrição do composer.json prevalece sobre a dica de compatibility de uma página.

Como ler o front matter de ciclo de vida de uma página

Use estes seis campos para avaliar qualquer página antes de construir sobre ela:

Campo	Tipo	Como lê-lo
stability	stable | beta | experimental | deprecated	A promessa de compatibilidade para a superfície que a página documenta.
since	SemVer (por exemplo "3.1.0")	A versão que introduziu a superfície documentada. Sua instalação deve ser pelo menos esta versão.
deprecated_since	SemVer ou vazio	Se definido, a superfície está depreciada; o valor é a versão que a depreciou. Vazio significa não depreciada.
replaced_by	Caminho do site ou vazio	Quando depreciada, a página sucessora canônica para a qual migrar.
version_lifecycle	active | lts | maintenance | frozen | eol	A classe de manutenção da linha documentada.
eol_date	Data ISO ou vazio	Quando version_lifecycle é eol, a data de fim de vida. Vazio caso contrário.

Uma leitura trabalhada: uma página com stability: stable, since: "3.0.0", deprecated_since: "" e version_lifecycle: active documenta uma superfície pronta para produção que existe desde a 3.0.0, não está depreciada e fica na linha ativamente mantida. Você pode depender dela sob uma restrição major ^. Uma página com stability: deprecated e um replaced_by não vazio é um sinal de migração: leia a página sucessora e planeje a mudança antes do próximo major.

Conformidade

Esta política está em conformidade com o Semantic Versioning 2.0.0 para numeração de versão e com os Conventional Commits 1.0.0 para geração de changelog. A janela de suporte do PHP é a restrição >=8.4 <9.0 declarada no composer.json do engine. Esta página não faz nenhuma afirmação normativa de padrões por conta própria; ela documenta o contrato de suporte que os campos de front matter de ciclo de vida já codificam.

Veja também

• Regras de estabilidade da SPI — a tag @stability por contrato e as quatro classes de promessa de compatibilidade com versões anteriores (interface, enum, value-object congelado, experimental).
• Matriz de suporte a CSS — o estado de suporte por módulo auditado-pela-verdade para o pipeline de renderização de HTML e CSS.
• Índice de referência — o ponto de entrada para o material de referência de API, configuração e compatibilidade.