Манифест закрепления зависимостей
Политика объявления зависимостей, охватывающая диапазоны среды выполнения Python, инструменты разработки, lock-файлы инструментов выпуска и утверждённые нижние границы версий для каждой поверхности сборки.
Утверждённая позиция в отношении того, как Apothem объявляет, закрепляет и блокирует зависимости. Аудитория: участники и нижестоящие потребители, которым нужно понять модель воспроизводимости.
Позиция
Apothem — это Python CLI с небольшим набором зависимостей среды выполнения плюс
более крупная цепочка инструментов для разработки, аудита, выпуска и
документации. Зависимости среды выполнения используют консервативные нижние
границы в pyproject.toml; сайт коммитит site/package-lock.json; GitHub
Actions закреплены по неизменяемому SHA с комментариями версий и обновляются
через Renovate.
| Класс | Объявление | Политика блокировки |
|---|---|---|
| Зависимости среды выполнения Python | [project.dependencies] в pyproject.toml | Диапазоны с нижней границей; закоммиченный lock среды выполнения Python отсутствует |
| Инструменты разработки / безопасности | extras из [project.optional-dependencies] | Диапазоны с нижней границей; CI устанавливает текущие совпадающие версии |
| Инструменты выпуска | scripts/release/requirements-build-linux.txt | Заблокированы по хешу для рабочих процессов выпуска; сгенерированы из замыкания инструментов выпуска |
| Инструменты только для CI | .github/workflows/*.yml | pip-инструменты, относящиеся только к рабочему процессу, используют точные закрепления (pip, bandit, pip-audit, pip-licenses, pyinstaller) |
| Сайт документации | site/package.json | site/package-lock.json закоммичен и потребляется npm ci |
| GitHub Actions | Закреплённые по SHA ссылки uses: с комментариями версий | Renovate предлагает обновления; исключения несут маркеры action-pinning-exempt: |
Утверждение выпуска
| Поверхность | Утверждённое состояние | Обоснование |
|---|---|---|
| Зависимости среды выполнения | Текущие нижние границы находятся в pyproject.toml [project.dependencies] | Текущие стабильные нижние границы утверждены перед выпуском; известных блокеров по CVE среды выполнения нет |
| Инструменты разработки | Текущие нижние границы находятся в extra dev файла pyproject.toml | Последние стабильные нижние границы утверждены перед выпуском |
| Инструменты безопасности | Текущие нижние границы находятся в extra security файла pyproject.toml | Текущие нижние границы сканеров утверждены перед выпуском |
| Инструменты выпуска | Заблокированное по хешу замыкание находится в scripts/release/requirements-build-linux.txt | Рабочий процесс выпуска устанавливает с --require-hashes; локальные скрипты требуют, чтобы build уже существовали, вместо молчаливой установки изменяющихся зависимостей |
| Инструменты документации | Текущие диапазоны находятся в site/package.json; точное разрешение находится в site/package-lock.json | npm outdated не возвращает устаревших зависимостей документации после обновления lock-файла |
| GitHub Actions | Существующие закрепления по SHA сохранены для текущего выпуска; повторно используемый рабочий процесс SLSA остаётся задокументированным исключением, закреплённым по тегу | Повторный запуск публичного CI зелёный; широкие мажорные обновления actions намеренно оставлены PR автоматизации зависимостей, чтобы избежать колебаний поверхности выпуска |
| Упаковка npm | Только ручной рабочий процесс publish-npm.yml; без автоматического триггера выпуска | Единственный публичный npm-пакет — @ahmed-g-gad/apothem; публикация выполняется после прохождения готовности к выпуску |
Блокировка
Lock-файлы Python генерируются по требованию участником. Они не коммитятся, поскольку замыкание среды выполнения Apothem невелико, CLI поддерживает несколько минорных версий Python, а CI намеренно прорабатывает новейшие совпадающие версии инструментов.
# 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.
Обоснование
- Почему диапазонные закрепления для Python? CLI поддерживает широкую матрицу Python, и CI должен выявлять проблемы совместимости с текущими инструментами до того, как с ними столкнутся пользователи.
- Почему закоммиченный lock Node? Сайт — это развёрнутый статический артефакт;
lock-файл даёт детерминированные сборки
npm ciдля этой публичной поверхности. - Почему закреплённые по SHA Actions? Теги изменяемы; SHA неизменяемы. Renovate обновляет закреплённые SHA, а шлюз выпуска фиксирует любую намеренную задержку.
Заголовок авторства — построчная SPDX-строка лицензии
Определение и принудительное применение пофайловых маркеров SPDX-идентификатора лицензии с помощью канонических однострочных заголовков в подходящем синтаксисе комментариев для каждого типа файла.
Дисциплина планов — проектно-локальная эфемерная рабочая память
Управление проектно-локальной эфемерной рабочей памятью в .apothem/plans/ (устаревшее дерево .plans/ обновляется через apothem migrate-workspace) со схемой frontmatter, переходами жизненного цикла, повышением до ADR и принудительным применением через хуки и валидаторы.