依存関係ピン留めマニフェスト

Apothem が依存関係をどのように宣言・ピン留め・ロックするかについての承認済みの姿勢。 対象読者：再現性モデルを理解する必要があるコントリビューターおよび下流の利用者。

姿勢Copy Anchor Link

Apothem は、小さなランタイム依存関係のセットに加えて、より大規模な開発・監査・ リリース・ドキュメントのツールチェーンを備えた Python CLI です。ランタイム依存関係は pyproject.toml で保守的な下限を使用します。ウェブサイトは site/package-lock.json をコミットします。GitHub Actions はバージョンコメント付きで 不変の SHA によってピン留めされ、Dependabot によって更新されます。

リリース承認Copy Anchor Link

ロックCopy Anchor Link

コントリビューター自身の Python ロックファイルはオンデマンドで生成し、コミットしません。 Apothem のランタイムクロージャは小さく、CLI は複数の Python マイナーバージョンを サポートしているためです。CI は例外で、scripts/ci/ 内のハッシュロックされたファイルを インストールします。依存関係ロック 4 つ（requirements-ci-dev.txt、-runtime.txt、 -test.txt、-prereqs.txt）と、ワークフローが実行するツールごとのロック 1 つずつ （-ruff.txt、-bandit.txt、-pip-audit.txt、-pip-licenses.txt、-pre-commit.txt） です。python scripts/dev/refresh_ci_locks.py は 9 つすべてを、ロック日から Dependabot と同じ 7 日間のクールダウンを差し引いた時点でコンパイルします。そのため CI は、 ロック日の時点で公開から 1 週間以上たったリリースをテストし、ファイルを更新すると テスト対象のリリースも新しくなります。各ファイルはロック日、クールダウン、その結果の カットオフを記録し、--check はそのカットオフを再現します。クールダウンより新しい 緊急のセキュリティ修正には、--cooldown-days 0 を付けた更新の実行か、 scripts/dev/ci_lock_table.py でのそのパッケージ向けのクールダウン例外が必要です。 この例外は、そのパッケージだけクールダウンを解除します。毎週の pip-audit.yml の実行は、 pyproject.toml が許容する最新バージョンと 9 つのロックを監査し、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 の実行が許容される 最新バージョンを解決し、現在のツールとの問題を明らかにします。
• なぜコミットされる Node ロックか？ ウェブサイトはデプロイされる静的成果物です。 ロックファイルは、その公開面に対して決定的な npm ci ビルドをもたらします。
• なぜ SHA ピンの Actions か？ タグは可変ですが、SHA は不変です。Dependabot は SHA の更新を提案して各バージョンコメントを書き換え、リリースゲートは意図的な保留を すべて記録します。
• 更新ボットが触れないもの。 Dependabot のバージョン更新 （.github/dependabot.yml）は、GitHub Actions のピン、ウェブサイトの ロックファイル、vsce パッケージャーのロックファイル（tools/vsce）、channel smoke が インストールするハーネス CLI のロックファイル（tools/channel-smoke）、CI が インストールするハッシュロックされた pip（scripts/ci/requirements-ci-pip.txt）、 および pre-commit フックを対象とします。scripts/ci 内のほかの 9 つのファイルは scripts/dev/refresh_ci_locks.py で丸ごと再生成するクロージャで、どれも pip を ピン留めしません。このフォルダーに対する Dependabot のバージョン更新は pip に限られます。 pyproject.toml のランタイム下限、ハッシュロックされた リリース要件、src/apothem/_vendor/vendor.txt のベンダリングされたクロージャ、 そして pyproject.toml と歩調を合わせてピン留めされた pre-commit フックは手作業で 更新します。単一のピンだけを上げると、それらが整合しているファイルが壊れるためです。 ruff と mypy のフックはそのうちの 2 つです。tests/scripts/test_ci_tool_locks.py は、 pyproject.toml の ruff の厳密なピン、フックの rev、ruff ロック、dev ロックが 同じバージョンになるまで、また mypy の厳密なピン、mypy フックの rev、そのフックが 列挙するライブラリが dev ロックと一致するまで失敗します。そのため、どちらかの ツールに対する Dependabot のセキュリティプルリクエストは手作業で調整します。 ウェブサイトの @types/node のメジャーバージョンは Node の下限（engines と .nvmrc、Node 22）に従うため、Dependabot はそのマイナーおよびパッチ更新のみを 提案します。そのメジャーバージョンは下限と一緒に引き上げてください。 バージョン更新は npm の overrides ブロックには手を付けません。Dependabot の セキュリティ更新は引き続きすべてのマニフェストを対象とするため、セキュリティの プルリクエストがこれらのピンのいずれかを提案したり、override を動かしたりすることが あります。その場合は手作業で調整するか、クローズしてください。
• Dependabot のプルリクエストのマージ。 リポジトリのスカッシュの既定では PR の タイトルが使われます。Dependabot のタイトルの一部、主にディレクトリ名を含む グループ化されたものは、72 文字のスカッシュ件名を超えます。PR Title チェックが それらを指摘し、タイトルの変更で修正できます。ツールのロックファイルを変更する プルリクエストでは ci.yml のジョブが一切実行されないため、npm audit ワークフローが それを監査してインストールし、vsce のロックファイルについては VS Code 拡張機能を パッケージ化して vsce のリリーステストを実行し、channel-smoke のロックファイルに ついては channel smoke ワークフローが実行されます。Markdown Lint ワークフローは、 pre-commit フックのプルリクエストに対して markdownlint フックを実行します。 その他のフックは CI で実行されないため、マージする前にそのブランチで pre-commit run --all-files を実行してください。