Манифест закрепления зависимостей

Утверждённая позиция о том, как Apothem объявляет, закрепляет и блокирует зависимости. Аудитория: участники и нижестоящие потребители, которым нужно понять модель воспроизводимости.

ПозицияCopy Anchor Link

Apothem — это Python CLI с небольшим набором зависимостей среды выполнения плюс более крупная цепочка инструментов для разработки, аудита, релиза и документации. Зависимости среды выполнения используют консервативные нижние границы в pyproject.toml; сайт коммитит site/package-lock.json; GitHub Actions закреплены по неизменяемому SHA с комментариями версий и обновляются через Dependabot.

Утверждение релизаCopy Anchor Link

БлокировкаCopy Anchor Link

Собственные lock-файлы Python участники генерируют по требованию, и они не коммитятся: замыкание среды выполнения Apothem невелико, а CLI поддерживает несколько минорных версий Python. Исключение — CI. Он устанавливает заблокированные по хешу файлы из scripts/ci/: четыре lock-файла зависимостей (requirements-ci-dev.txt, -runtime.txt, -test.txt и -prereqs.txt) и по одному lock-файлу на каждый инструмент, который запускают рабочие процессы (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt и -pre-commit.txt). python scripts/dev/refresh_ci_locks.py компилирует все девять на дату блокировки за вычетом 7-дневного периода ожидания, как у Dependabot. Поэтому CI тестирует релизы, которым на дату блокировки исполнилась хотя бы неделя, а обновление файлов сдвигает их вперёд. Каждый файл записывает дату блокировки, период ожидания и итоговую граничную дату, а --check воспроизводит эту граничную дату. Срочному исправлению безопасности, которое моложе периода ожидания, нужен запуск обновления с --cooldown-days 0 или исключение из периода ожидания для его пакета в scripts/dev/ci_lock_table.py; такое исключение снимает период ожидания только для этого пакета. Еженедельный запуск pip-audit.yml проверяет новейшие версии, которые допускает pyproject.toml, а также все девять lock-файлов и запрашивает у сервиса OSV сведения об уязвимостях. Участники по-прежнему устанавливают пакет командой 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

Сайт устроен иначе: site/package-lock.json коммитится, а CI использует npm ci, поэтому отрендеренный сайт документации имеет воспроизводимое замыкание Node.

ОбоснованиеCopy Anchor Link

• Почему диапазонные закрепления для Python? CLI поддерживает широкую матрицу Python, поэтому pyproject.toml задаёт консервативные нижние границы. CI устанавливает заблокированные по хешу замыкания этих диапазонов, которые сопровождающий обновляет с помощью scripts/dev/refresh_ci_locks.py (задуманный ритм — раз в неделю), а еженедельный запуск pip-audit.yml разрешает новейшие допустимые версии, чтобы выявить проблемы с текущими инструментами.
• Почему закоммиченный lock Node? Сайт — это развёрнутый статический артефакт; lock-файл даёт детерминированные сборки npm ci для этой публичной поверхности.
• Почему закреплённые по SHA Actions? Теги изменяемы; SHA неизменяемы. Dependabot предлагает повышения SHA и переписывает каждый комментарий версии, а шлюз релиза фиксирует любое намеренное удержание версии.
• Чего бот обновлений не касается. Обновления версий Dependabot (.github/dependabot.yml) охватывают закрепления GitHub Actions, lock-файл сайта, lock-файл упаковщика vsce (tools/vsce), lock-файл CLI окружений, который устанавливает channel smoke (tools/channel-smoke), заблокированный по хешу pip, который устанавливает CI (scripts/ci/requirements-ci-pip.txt), и хуки pre-commit. Остальные девять файлов в scripts/ci — это замыкания, которые scripts/dev/refresh_ci_locks.py генерирует заново целиком; ни один из них не закрепляет pip, и обновления версий Dependabot для этой папки ограничены pip. Нижние границы среды выполнения в pyproject.toml, заблокированные по хешу требования релиза, вендорное замыкание в src/apothem/_vendor/vendor.txt и хуки pre-commit, закреплённые синхронно с pyproject.toml, обновляются вручную, потому что повышение одного закрепления сломало бы файлы, с которыми они согласованы. Хуки ruff и mypy — два из них: tests/scripts/test_ci_tool_locks.py падает, пока точное закрепление ruff в pyproject.toml, rev хука, lock-файл ruff и lock-файл dev не укажут одну и ту же версию и пока точное закрепление mypy, rev хука mypy и библиотеки, которые перечисляет этот хук, не совпадут с lock-файлом dev. Поэтому pull request безопасности от Dependabot для любого из этих инструментов адаптируется вручную. Мажорная версия @types/node сайта следует за его нижней границей Node (engines и .nvmrc, Node 22), поэтому Dependabot предлагает только её минорные и патч-обновления; повышайте эту мажорную версию вместе с нижней границей. Обновления версий не трогают блоки npm overrides. Обновления безопасности Dependabot по-прежнему охватывают каждый манифест, поэтому pull request безопасности может предложить одно из этих закреплений или сдвинуть override; адаптируйте его вручную или закройте.
• Слияние pull request от Dependabot. Squash по умолчанию в репозитории берёт заголовок PR. Некоторые заголовки Dependabot, в основном групповые, называющие каталог, превышают 72 символа темы squash-коммита; проверка PR Title называет их, а смена заголовка их исправляет. Pull request, изменяющий lock-файл инструмента, не запускает ни одного задания ci.yml, поэтому рабочий процесс npm audit проверяет и устанавливает его, упаковывает расширение VS Code для lock-файла vsce и запускает тесты релиза vsce, а рабочий процесс channel smoke запускается для lock-файла channel-smoke. Рабочий процесс Markdown Lint запускает хук markdownlint на pull request с хуками pre-commit; остальные хуки в CI не проверяются, поэтому перед слиянием запустите pre-commit run --all-files на его ветке.