Manifes Penyematan Dependensi

Sikap yang diratifikasi tentang cara Apothem mendeklarasikan, menyematkan, dan mengunci dependensi. Audiens: kontributor dan konsumen hilir yang perlu memahami model reproduktibilitas.

SikapCopy Anchor Link

Apothem adalah CLI Python dengan kumpulan dependensi runtime yang kecil ditambah rantai perkakas pengembangan, audit, rilis, dan dokumentasi yang lebih besar. Dependensi runtime menggunakan batas bawah yang konservatif di pyproject.toml; situs web meng-commit site/package-lock.json; GitHub Actions disematkan oleh SHA yang tak dapat diubah dengan komentar versi dan ditingkatkan oleh Dependabot.

Ratifikasi rilisCopy Anchor Link

PenguncianCopy Anchor Link

Berkas kunci Python milik kontributor sendiri dihasilkan sesuai permintaan dan tidak di-commit: penutupan runtime Apothem kecil dan CLI mendukung beberapa versi minor Python. CI adalah pengecualiannya. CI memasang berkas yang dikunci hash di scripts/ci/: empat kunci dependensi (requirements-ci-dev.txt, -runtime.txt, -test.txt, dan -prereqs.txt) dan satu kunci untuk setiap perkakas yang dijalankan alur kerja (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt, dan -pre-commit.txt). python scripts/dev/refresh_ci_locks.py mengompilasi kesembilannya per tanggal penguncian dikurangi masa tunggu 7 hari yang sama dengan milik Dependabot, sehingga CI menguji rilis yang sudah berumur setidaknya satu minggu pada tanggal penguncian, dan penyegaran berkas memajukannya. Setiap berkas mencatat tanggal penguncian, masa tunggu, dan tanggal batas yang dihasilkan, dan --check mereproduksi tanggal batas itu. Perbaikan keamanan mendesak yang lebih baru daripada masa tunggu memerlukan penyegaran dengan --cooldown-days 0, atau pengecualian masa tunggu untuk paketnya di scripts/dev/ci_lock_table.py, yang mencabut masa tunggu hanya untuk paket itu. Eksekusi mingguan pip-audit.yml mengaudit versi terbaru yang diizinkan pyproject.toml serta kesembilan kunci, dengan menanyakan advisori keamanan ke layanan OSV. Kontributor tetap memasang dengan 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

Situs web berbeda: site/package-lock.json di-commit dan CI menggunakan npm ci, sehingga situs dokumentasi yang dirender memiliki penutupan Node yang dapat direproduksi.

RasionelCopy Anchor Link

• Mengapa penyematan rentang untuk Python? CLI mendukung matriks Python yang luas, sehingga pyproject.toml mempertahankan batas bawah yang konservatif. CI memasang penutupan yang dikunci hash dari rentang tersebut, yang disegarkan pemelihara dengan scripts/dev/refresh_ci_locks.py (iramanya direncanakan mingguan), dan eksekusi mingguan pip-audit.yml me-resolve versi terbaru yang diizinkan untuk mengungkap masalah dengan perkakas saat ini.
• Mengapa kunci Node yang di-commit? Situs web adalah artefak statis yang di-deploy; berkas kunci memberikan build npm ci yang deterministik untuk permukaan publik tersebut.
• Mengapa Actions yang disematkan SHA? Tag dapat diubah; SHA tidak dapat diubah. Dependabot mengusulkan peningkatan SHA dan menulis ulang setiap komentar versi, sementara gerbang rilis mencatat setiap penahanan yang disengaja.
• Apa yang tidak disentuh bot pembaruan. Pembaruan versi Dependabot (.github/dependabot.yml) mencakup penyematan GitHub Actions, berkas kunci situs web, berkas kunci pengemas vsce (tools/vsce), berkas kunci CLI harness yang dipasang oleh channel smoke (tools/channel-smoke), pip yang dikunci hash yang dipasang CI (scripts/ci/requirements-ci-pip.txt), dan hook pre-commit. Sembilan berkas lainnya di scripts/ci adalah penutupan yang dibuat ulang secara utuh dengan scripts/dev/refresh_ci_locks.py; tidak satu pun menyematkan pip, dan pembaruan versi Dependabot untuk folder itu dibatasi pada pip. Batas bawah runtime di pyproject.toml, persyaratan rilis yang dikunci hash, penutupan vendor di src/apothem/_vendor/vendor.txt, dan hook pre-commit yang disematkan seiring dengan pyproject.toml diubah secara manual, karena peningkatan satu penyematan saja akan merusak berkas-berkas yang harus selaras dengannya. Hook ruff dan mypy termasuk di antaranya: tests/scripts/test_ci_tool_locks.py gagal sampai penyematan eksak ruff di pyproject.toml, rev hook, kunci ruff, dan kunci dev memuat satu versi yang sama, dan sampai penyematan eksak mypy, rev hook mypy, dan pustaka yang didaftarkan hook itu cocok dengan kunci dev. Karena itu, pull request keamanan Dependabot untuk salah satu perkakas itu disesuaikan secara manual. Versi mayor @types/node situs web mengikuti batas bawah Node-nya (engines dan .nvmrc, Node 22), sehingga Dependabot hanya mengusulkan pembaruan minor dan patch-nya; naikkan versi mayor tersebut bersamaan dengan batas bawahnya. Pembaruan versi tidak menyentuh blok overrides npm. Pembaruan keamanan Dependabot tetap mencakup setiap manifes, sehingga pull request keamanan dapat mengusulkan salah satu penyematan ini, atau memindahkan sebuah override; sesuaikan secara manual atau tutup pull request tersebut.
• Menggabungkan pull request Dependabot. Default squash repositori mengambil judul PR. Beberapa judul Dependabot, kebanyakan judul berkelompok yang menyebut sebuah direktori, melampaui batas 72 karakter subjek squash; pemeriksaan PR Title menyebutkannya, dan penggantian judul memperbaikinya. Pull request yang mengubah berkas kunci perkakas tidak menjalankan job ci.yml apa pun, sehingga alur kerja audit npm mengaudit dan memasangnya, mengemas ekstensi VS Code untuk berkas kunci vsce dan menjalankan pengujian rilis vsce, dan alur kerja channel smoke berjalan untuk berkas kunci channel-smoke. Alur kerja Markdown Lint menjalankan hook markdownlint pada pull request hook pre-commit; hook lainnya tidak dijalankan di CI, jadi jalankan pre-commit run --all-files pada branch-nya sebelum menggabungkannya.