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 oSphinx
atualmente suporta. Quando oSphinx
não precisa mais suportar a versão mais antiga do Python que não inclui a biblioteca, a biblioteca será descontinuada noSphinx
.
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 dePendingDeprecationWarning
, 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 deDeprecationWarning
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 executarmake html
(Linux/Mac)set PYTHONWARNINGS=
e executarmake 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+ |
24 Apr 2026 |
3.12+ |
Procedimentos de lançamento¶
The release procedures are listed in utils/release-checklist.rst
.