Processo de lançamento do Sphinx

Versioning

Sphinx adheres to PEP 440 versions, with a major.minor.micro scheme for the release segment (e.g. 1.2.3). The major, minor, and micro version parts should be altered as follows:

• The major version part should be incremented for incompatible behavior change and public API updates.

• The minor version part should be incremented for most releases of Sphinx, where backwards-compatibility of API and features are preserves.

• The micro version part should only be incremented for urgent bugfix-only releases.

When the major version part is incremented, the minor and micro version parts must be set to 0. When the minor version part is incremented, the micro version part must be set to 0.

New major versions should come with a beta-testing period before the final release.

Recurso em Desuso

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 suporta. Quando o Sphinx não precisa mais suportar a versão mais antiga do Python que não inclui a biblioteca, a biblioteca será descontinuada no Sphinx.

Como o Política de Desuso descreve, o primeiro release do Sphinx que marcou um recurso como estando em desuso (A.B) deve gerar um RemovedInSphinxXXWarning (em que XX é a versão do Sphinx em que o recurso será removido) quando o recurso em desuso 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 Desuso

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

Então, por exemplo, se decidimos iniciar o desuso 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 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 python: 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.

Python version support policy

Sphinx supports at all minor versions of Python released in the past 42 months from the anticipated release date with a minimum of 3 minor versions of Python. This policy is derived from NEP 29, a scientific Python domain standard.

For example, a version of Sphinx released in May 2024 would support Python 3.10, 3.11, and 3.12.

This is a summary table with the current policy:

Date	Python
26 Dec 2021	3.8+
14 Apr 2023	3.9+
05 Apr 2024	3.10+
04 Apr 2025	3.11+

Procedimentos de lançamento

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