Sphinx’s release process¶
Modelo de Branch¶
O projeto Sphinx
usa as seguintes ramificações para desenvolvimento que estão em conformidade com o Semântica de versão 2.0.0 (refs: https://semver.org/).
master
Desenvolvimento para a versão MAJOR. Todas as alterações, incluindo comportamentos incompatíveis e atualizações de API públicas, são permitidas.
A.x
(ex.2.x
)Where
A.x
is theMAJOR.MINOR
release. Used to maintain current MINOR release. All changes are allowed if the change preserves backwards-compatibility of API and features.Apenas o branch
MAJOR.MINOR
mais recente está atualmente retido. Quando uma nova versão MAJOR for lançada, a antiga ramificaçãoMAJOR.MINOR
será excluída e substituída por uma tag equivalente.A.B.x
(ex.2.4.x
)Where
A.B.x
is theMAJOR.MINOR.PATCH
release. Only backwards-compatible bug fixes are allowed. In Sphinx project, PATCH version is used for urgent bug fix.o ramo
MAJOR.MINOR.PATCH
será ramificado a partir da tag de release prefixadav
(por exemplo, make 2.3.1 que ramificou de v2.3.0) quando um release urgente é necessário. Quando uma nova versão PATCH é lançado, a ramificação será excluída e substituída por uma tag equivalente (ex. V2.3.1).
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:
Sphinx 2.x will contain a backwards-compatible replica of the function which will raise a
RemovedInSphinx40Warning
. This is a subclass ofPendingDeprecationWarning
, i.e. it will not get displayed by default.Sphinx 3.x will still contain the backwards-compatible replica, but
RemovedInSphinx40Warning
will be a subclass ofDeprecationWarning
then, and gets displayed by default.O Sphinx 4.0 removerá o recurso imediatamente.
Deprecation warnings¶
Sphinx will enable its RemovedInNextVersionWarning
warnings by default, if
PYTHONWARNINGS
is not set. Therefore you can disable them
using:
PYTHONWARNINGS= make html
(Linux/Mac)export PYTHONWARNINGS=
e executarmake html
(Linux/Mac)set PYTHONWARNINGS=
e executarmake html
(Windows)
But you can also explicitly enable the pending ones using e.g.
PYTHONWARNINGS=default
(see the Python docs on configuring warnings) for more details.
Release procedures¶
The release procedures are listed in utils/release-checklist
.