Deprecar una función en una biblioteca: avisar, documentar el reemplazo, retirar según calendario

Objetivo

Eliminar o cambiar una función, clase u opción pública de una biblioteca sin romper a los usuarios entre versiones consecutivas, y sin arrastrar la ruta antigua para siempre. Esta es la contrapartida, del lado de la biblioteca, de deprecar un endpoint HTTP (enlazado), con avisos y política de versiones en lugar de cabeceras.

Requisitos previos

Una definición de qué es público. PEP 387 considera públicos los nombres, las posiciones y tipos de argumentos, los valores de retorno y las excepciones lanzadas, y excluye los nombres precedidos por guion bajo y todo lo documentado como privado; un nombre no documentado no es automáticamente privado. Una política de cadencia por escrito, porque la fecha de eliminación se expresa en versiones.

Pasos

1. Publicar primero el reemplazo, en una versión que aún admita la ruta antigua sin cambios, de modo que la migración sea un único paso.
2. Marcar la ruta antigua en la misma versión o en la siguiente: un aviso en tiempo de ejecución de la categoría de deprecación, una nota en la documentación de referencia con la versión de deprecación y el reemplazo, y una entrada bajo un encabezado «Deprecated» en el registro de cambios.
3. Fijar la versión de eliminación por política y no caso por caso. PEP 387 establece que un cambio incompatible debe pasar por el proceso de deprecación, que la cadencia anual implica al menos dos años entre el aviso y la eliminación y (desde un cambio de 2025) que se prefieren cinco años; la política de Django mantiene una funcionalidad deprecada funcionando durante todas las versiones de la serie principal (major) actual y la elimina en la siguiente versión principal, o una versión más tarde, de modo que al menos dos versiones de funcionalidad separan el aviso de la eliminación. Un proyecto pequeño puede adoptar «no eliminar antes de la segunda versión de funcionalidad posterior al aviso».
4. Hacer visible el aviso donde importa. El filtro predeterminado de Python ignora DeprecationWarning salvo cuando lo activa directamente el código en __main__; la documentación aconseja que los ejecutores de pruebas muestren todos los avisos para el código bajo prueba. Ejecutar la propia suite de pruebas de la biblioteca convirtiendo los avisos en errores para que los usos internos de la ruta antigua salgan a la luz primero.
5. Preferir una deprecación suave cuando la ruta antigua se pueda mantener sin riesgo: PEP 387 la describe como documentada, probada, ya sin desarrollo activo y sin una eliminación ni un aviso programados.
6. Eliminar en la versión anunciada, listarlo bajo «Removed» en el registro de cambios, e incrementar la versión según la política de versionado (una versión principal bajo versionado semántico).

Resultado esperado

Los usuarios ven un aviso por cada punto de llamada antiguo que señala el reemplazo y conocen la versión en la que desaparecerá; la biblioteca arrastra cada adaptador durante un número acotado de versiones.

Límites y base de verificación

Las políticas se citan de los documentos de Python y Django referenciados; un proyecto con una cadencia distinta debe traducir «dos versiones» a su propio tiempo. No se mide ningún resultado de migración.