Manifiesto de fijación de dependencias

Postura ratificada sobre cómo Apothem declara, fija y bloquea dependencias. Audiencia: colaboradores y consumidores posteriores que necesitan entender el modelo de reproducibilidad.

PosturaCopy Anchor Link

Apothem es una CLI de Python con un conjunto pequeño de dependencias de tiempo de ejecución más una cadena de herramientas más amplia de desarrollo, auditoría, lanzamiento y documentación. Las dependencias de tiempo de ejecución usan límites inferiores conservadores en pyproject.toml; el sitio web versiona site/package-lock.json; las GitHub Actions se fijan por SHA inmutable con comentarios de versión y se actualizan mediante Dependabot.

Ratificación del lanzamientoCopy Anchor Link

BloqueoCopy Anchor Link

Los archivos de bloqueo de Python propios de los colaboradores se generan bajo demanda y no se versionan: el cierre de tiempo de ejecución de Apothem es pequeño y la CLI admite múltiples versiones menores de Python. CI es la excepción. Instala los archivos bloqueados por hash de scripts/ci/: cuatro bloqueos de dependencias (requirements-ci-dev.txt, -runtime.txt, -test.txt y -prereqs.txt) y un bloqueo por cada herramienta que ejecutan los flujos de trabajo (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt y -pre-commit.txt). python scripts/dev/refresh_ci_locks.py compila los nueve a una fecha de bloqueo menos un período de espera de 7 días que coincide con el de Dependabot, de modo que CI prueba las versiones que tenían al menos una semana en la fecha de bloqueo, y actualizar los archivos las hace avanzar. Cada archivo registra la fecha de bloqueo, el período de espera y la fecha de corte resultante, y --check reproduce esa fecha de corte. Una corrección de seguridad urgente más reciente que el período de espera necesita una actualización con --cooldown-days 0, o una excepción al período de espera para su paquete en scripts/dev/ci_lock_table.py, que elimina el período de espera solo para ese paquete. La ejecución semanal de pip-audit.yml audita las versiones más recientes que permite pyproject.toml además de los nueve bloqueos, y consulta al servicio OSV los avisos de seguridad. Los colaboradores siguen instalando con pip install -e ".[dev]".

# Astral uv:
uv pip install -e ".[dev,security,release]"
uv pip freeze > requirements.dev.lock

# pip-tools:
pip-compile --extra=dev --extra=security --extra=release -o requirements.dev.lock pyproject.toml

# Plain pip:
pip install -e ".[dev,security,release]"
pip freeze > requirements.dev.lock

El sitio web es diferente: site/package-lock.json se versiona y CI usa npm ci, de modo que el sitio de documentación renderizado tiene un cierre de Node reproducible.

JustificaciónCopy Anchor Link

• ¿Por qué fijaciones por rango para Python? La CLI admite una matriz de Python amplia, así que pyproject.toml mantiene pisos conservadores. CI instala cierres bloqueados por hash de esos rangos, que el mantenedor actualiza con scripts/dev/refresh_ci_locks.py (la cadencia prevista es semanal), y la ejecución semanal de pip-audit.yml resuelve las versiones permitidas más recientes para revelar problemas con las herramientas actuales.
• ¿Por qué un bloqueo de Node versionado? El sitio web es un artefacto estático desplegado; el archivo de bloqueo da compilaciones npm ci deterministas para esa superficie pública.
• ¿Por qué Actions fijadas por SHA? Las etiquetas son mutables; los SHA son inmutables. Dependabot propone los incrementos de SHA y reescribe cada comentario de versión, mientras que la puerta de lanzamiento registra cualquier retención intencionada.
• Lo que el bot de actualizaciones no toca. Las actualizaciones de versión de Dependabot (.github/dependabot.yml) cubren las fijaciones de GitHub Actions, el archivo de bloqueo del sitio web, el archivo de bloqueo del empaquetador vsce (tools/vsce), el archivo de bloqueo de las CLI de entornos que instala el channel smoke (tools/channel-smoke), el pip bloqueado por hash que instala CI (scripts/ci/requirements-ci-pip.txt) y los hooks de pre-commit. Los otros nueve archivos de scripts/ci son cierres que scripts/dev/refresh_ci_locks.py regenera completos; ninguno fija pip, y las actualizaciones de versión de Dependabot para esa carpeta se limitan a pip. Los pisos de tiempo de ejecución en pyproject.toml, los requisitos de lanzamiento bloqueados por hash, el cierre vendorizado en src/apothem/_vendor/vendor.txt y los hooks de pre-commit fijados en sincronía con pyproject.toml se mueven a mano, porque el incremento de una sola fijación rompería los archivos con los que concuerdan. Los hooks de ruff y mypy son dos de ellos: tests/scripts/test_ci_tool_locks.py falla hasta que la fijación exacta de ruff en pyproject.toml, la rev del hook, el bloqueo de ruff y el bloqueo dev lleven una misma versión, y hasta que la fijación exacta de mypy, la rev del hook de mypy y las bibliotecas que ese hook enumera coincidan con el bloqueo dev. Por eso, un pull request de seguridad de Dependabot para cualquiera de las dos herramientas se adapta a mano. La versión mayor de @types/node del sitio web sigue su piso de Node (engines y .nvmrc, Node 22), por lo que Dependabot solo propone sus actualizaciones menores y de parche; sube esa versión mayor junto con el piso. Las actualizaciones de versión dejan intactos los bloques overrides de npm. Las actualizaciones de seguridad de Dependabot siguen cubriendo todos los manifiestos, de modo que un pull request de seguridad puede proponer una de estas fijaciones, o mover un override; adáptalo a mano o ciérralo.
• Fusionar un pull request de Dependabot. El valor predeterminado de squash del repositorio toma el título del PR. Algunos títulos de Dependabot, sobre todo los agrupados que nombran un directorio, superan el asunto de squash de 72 caracteres; la comprobación PR Title los señala, y cambiar el título los corrige. Un pull request que cambia un archivo de bloqueo de herramientas no ejecuta ningún trabajo de ci.yml, así que el flujo de trabajo de auditoría de npm lo audita y lo instala, empaqueta la extensión de VS Code para el archivo de bloqueo de vsce y ejecuta las pruebas de lanzamiento de vsce, y el flujo de trabajo del channel smoke se ejecuta para el archivo de bloqueo de channel-smoke. El flujo de trabajo Markdown Lint ejecuta el hook de markdownlint en un pull request de hooks de pre-commit; los demás hooks no se ejercitan en CI, así que ejecuta pre-commit run --all-files en su rama antes de fusionarlo.