Processo de lançamento do Sphinx¶

Versionamento¶

Sphinx adere às versões da PEP 440, com um esquema major.minor.micro para o segmento de lançamento (por exemplo, 1.2.3). As partes da versão principal, secundária e micro devem ser alteradas da seguinte forma:

A parte da versão principal (major) deve ser incrementada para alterações de comportamento incompatíveis e atualizações de API públicas.
A parte da versão secundária (minor) deve ser incrementada para a maioria das versões do Sphinx, onde a compatibilidade com versões anteriores da API e dos recursos é preservada.
A parte da versão micro só deve ser incrementada para lançamentos urgentes somente para correção de bugs.

Quando a parte da versão principal é incrementada, as partes da versão secundária e micro devem ser definidas como 0. Quando a parte da versão secundária é incrementada, a parte da versão micro deve ser definida como 0.

Novas versões principais devem vir com um período de testes beta antes do lançamento final.

Descontinuando um recurso¶

Existem alguns motivos pelos quais o código no Sphinx pode ser descontinuado:

Se um recurso foi aprimorado ou modificado de maneira incompatível com versões anteriores, o recurso ou comportamento antigo será descontinuado.
Às vezes, o Sphinx incluirá um backport de uma biblioteca Python que não está incluída em uma versão do Python que o Sphinx atualmente oferece suporte. Quando o Sphinx não precisa mais dar suporte à versão mais antiga do Python que não inclui a biblioteca, a biblioteca será descontinuada no Sphinx.

Como a Política de descontinuação descreve, o primeiro lançamento do Sphinx que descontinuou um recurso (A.B) deve levantar uma RemovedInSphinxXXWarning (sendo XX a versão do Sphinx na qual o recurso será removido) quando o recurso descontinuado for chamado. Supondo que tenhamos uma boa cobertura de teste, esses avisos serão convertidos em erros ao executar o conjunto de testes com avisos ativados:

pytest -Wall

Assim, ao adicionar um RemovedInSphinxXXWarning, você precisa eliminar ou silenciar quaisquer avisos gerados ao executar os testes.

Política de descontinuação¶

As versões MAJOR e MINOR podem descontinuar certos recursos de versões anteriores. Se um recurso foi descontinuado em uma versão A.x, ele continuará a funcionar em todas as versões A.x.x (para todas as versões de x). Ele continuará a funcionar em todas as versões B.x.x, mas vai levantar os avisos de descontinuação. Os recursos descontinuados serão removidos na C.0.0. Isso significa que o recurso descontinuado funcionará durante pelo menos 2 lançamentos MAJOR.

Então, por exemplo, se decidimos iniciar a descontinuação de uma função no Sphinx 2.x:

O Sphinx 2.x conterá uma réplica compatível com versões anteriores da função que vai levantar uma exceção RemovedInSphinx40Warning. Esta é uma subclasse de PendingDeprecationWarning, ou seja, não será exibida por padrão.
O Sphinx 3.x ainda conterá a réplica compatível com versões anteriores, mas RemovedInSphinx40Warning será uma subclasse de DeprecationWarning e será exibida por padrão.
O Sphinx 4.0 removerá o recurso imediatamente.

Avisos de descontinuação¶

O Sphinx habilitará seus avisos RemovedInNextVersionWarning por padrão, se PYTHONWARNINGS não estiver definido. Portanto, você pode desativá-los usando:

PYTHONWARNINGS= make html (Linux/Mac)
export PYTHONWARNINGS= e executar make html (Linux/Mac)
set PYTHONWARNINGS= e executar make html (Windows)

Mas você também pode ativar explicitamente os pendentes usando, por exemplo, PYTHONWARNINGS=default (veja a documentação do Python sobre configuração de avisos) para mais detalhes.

Política de suporte a versões do Python¶

O Sphinx oferece suporte a todas as versões secundárias do Python lançadas nos últimos 43 anos a partir da data de lançamento prevista, com um mínimo de 3 versões secundárias do Python. Esta política é derivada da SPEC 0, um padrão científico de domínio Python.

Por exemplo, uma versão do Sphinx lançada em maio de 2025 teria suporte ao Python 3.11, 3.12 e 3.13.

Esta é uma tabela resumo com a política atual:

Data	Python
05 Out 2023	3.10+
04 Out 2024	3.11+
24 Out 2025	3.12+
01 Out 2026	3.13+
01 Out 2027	3.14+

Procedimentos de lançamento¶

Os procedimentos de lançamento estão listados em utils/release-checklist.rst.