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 the MAJOR.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ção MAJOR.MINOR será excluída e substituída por uma tag equivalente.

A.B.x (ex. 2.4.x)

Where A.B.x is the MAJOR.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 prefixada v (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 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:

  • Sphinx 2.x will contain a backwards-compatible replica of the function which will raise a RemovedInSphinx40Warning. This is a subclass of PendingDeprecationWarning, 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 of DeprecationWarning 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 executar make html (Linux/Mac)

  • set PYTHONWARNINGS= e executar make 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.