Kebijakan rekayasa rilis

Lima kebijakan mengatur cara apothem dirilis.

1. Versioning semantikCopy Anchor Link

Proyek ini dirilis mengikuti Semantic Versioning 2.0. Nomor versi berbentuk MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

Tag kandidat menggunakan format vX.Y.Z-rc.N (kandidat rilis) atau vX.Y.Z-alpha.N / vX.Y.Z-beta.N (akses awal).

2. Tag rilisCopy Anchor Link

Setiap rilis mendaratkan tag git bertanda tangan berbentuk vMAJOR.MINOR.PATCH di main. Tag tersebut memicu .github/workflows/release.yml, yang membangun, menandatangani, menghasilkan SBOM dan provenance SLSA-3, serta memublikasikan halaman GitHub Release.

Konvensi tag:

• Format — tepat vMAJOR.MINOR.PATCH. Tanpa awalan release-, tanpa akhiran -final.
• Anotasi — setiap tag adalah tag beranotasi (git tag -a -s) yang membawa ringkasan catatan rilis dalam pesan tag.
• Tanda tangan — setiap tag ditandatangani dengan GPG. Alur kerja rilis juga menghasilkan tanda tangan cosign keyless Sigstore pada setiap artefak dan catatan provenans SLSA-3, keduanya dilampirkan ke halaman GitHub Release.

Model rilis: aditifCopy Anchor Link

Rilis bersifat aditif. Setiap rilis menambahkan satu commit di main dan satu tag; main tidak pernah di-force-push, dan tidak ada tag, GitHub Release, atau versi npm yang telah dipublikasikan yang dihapus, dipindahkan, atau digunakan ulang. Setiap rilis mempertahankan tag-nya, GitHub Release-nya, dan versi npm-nya, dan semuanya tetap terpublikasi. Versi npm tidak dapat diubah: name@version yang telah dipublikasikan tidak pernah dapat diganti, dan nomor yang pernah di-unpublish tidak pernah dapat digunakan lagi. Pemasangan yang dipatok dan build yang dapat direproduksi bergantung pada setiap tag yang telah dipublikasikan. Runbook siklus rilis dan pemulihan rilis sama-sama mengikuti model ini.

Aturan fasad rilis repositori (bagian Release Facade dari instruksi kontributor) menyatakan model ini. Persyaratan untuk hanya menampilkan versi saat ini, yang dicerminkan dalam aturan freshness-facade, berlaku untuk apa yang dinyatakan permukaan publik. Persyaratan itu tidak membatasi rilis mana yang tetap terpublikasi.

3. Kebijakan penghentianCopy Anchor Link

Lini dukungan publik saat ini adalah minor terbaru yang telah dirilis. Ketika proyek memiliki beberapa minor publik, matriks versi yang didukung di SECURITY.md adalah sumber kebenaran untuk setiap jendela dukungan tambahan yang hanya mencakup perbaikan kritis.

Irama penghentian:

• Pengumuman — simbol atau perilaku yang dinyatakan usang diumumkan di bagian CHANGELOG.md ### Deprecated dari rilis tempat penghentian itu mendarat. Catatan rilis mencerminkan pengumuman penghentian tersebut.
• Jendela tenggang — simbol yang dinyatakan usang tetap tersedia selama minimal satu siklus minor penuh sebelum dihapus.
• Penghapusan — penghapusan mendarat pada kenaikan MAJOR. Setiap simbol yang dihapus membawa baris CHANGELOG.md ### Removed dan entri panduan migrasi di bawah Panduan praktis.

Batas bawah runtimeCopy Anchor Link

Apothem mendeklarasikan dua batas bawah runtime: requires-python = ">=3.10" di pyproject.toml dan "engines": {"node": ">=18"} di package.json.

• Setiap batas bawah yang dideklarasikan diuji. Batas bawah Python berjalan di matriks CI quality dan alur kerja CI Matrix. Alur kerja npm Shim menjalankan shim npm pada batas bawah Node dan pada setiap mayor LTS yang lebih baru: alur kerja ini memeriksa galat prasyarat yang hilang, node bin/apothem.mjs --version, pemasangan dry-run di direktori home yang terisolasi, dan tarball yang telah dikemas melalui npx. Runtime yang tidak diuji tidak dideklarasikan.
• Akhir masa pakai diungkapkan. Ketika runtime yang masih menjadi batas bawah yang dideklarasikan mencapai akhir masa pakai (end of life) di upstream, panduan instalasi menyatakannya dan menyebutkan versi yang sebaiknya dipilih. Python 3.10 mencapai akhir masa pakai pada 2026-10-01; Node.js 18 dan 20 pada 2025-04-30 dan 2026-04-30. Ketiganya tetap menjadi batas bawah yang didukung.
• Menaikkan batas bawah adalah sebuah penghentian. Langkah ini mengikuti irama di atas: pengumuman di bawah ### Deprecated, setidaknya satu siklus minor penuh di mana batas bawah lama tetap diuji, lalu rilis yang menaikkannya mencatat perubahan tersebut. requires-python, engines.node, probe versi milik pemasang, dan matriks CI berubah bersama dalam rilis itu.

4. Kebijakan perubahan yang tidak kompatibelCopy Anchor Link

Perubahan yang tidak kompatibel mensyaratkan:

1. Sebuah isu RFC — dibuka dengan label isu rfcs yang menjelaskan perubahan tidak kompatibel tersebut, jalur migrasi, dan strategi rollback.
2. Jendela komentar 30 hari — RFC tetap terbuka setidaknya 30 hari sebelum merge. Pemelihara dapat memperpanjang jendela ketika umpan balik memerlukannya.
3. Sebuah kenaikan MAJOR — rilis yang mendaratkan perubahan tidak kompatibel tersebut menaikkan komponen MAJOR.
4. Sebuah panduan migrasi — perubahan dirilis bersama entri Panduan praktis yang memandu operator melalui migrasi.

5. Kebijakan rollbackCopy Anchor Link

Jika sebuah rilis menunjukkan regresi yang menghambat adopsi:

1. Revert — commit yang bermasalah di-revert di main.
2. Rilis perbaikan-maju — rilis lanjutan mendarat sebagai vMAJOR.MINOR.PATCH+1 yang membawa revert tersebut ditambah perbaikan inkremental apa pun. Rilis buruk sebelumnya tidak dihapus dari GitHub Releases, dan versi npm-nya tetap terpublikasi (versi npm tidak dapat diubah) serta ditandai dengan npm deprecate. Anotasi ### Yanked di CHANGELOG.md mendokumentasikan situasi tersebut sehingga build yang dapat direproduksi tetap terjangkar.
3. Komunikasi — pemberitahuan security-advisories (ketika relevan dengan keamanan) atau isu GitHub yang disematkan untuk insiden tersebut (ketika relevan dengan keandalan) menyertai rollback.

Lihat jugaCopy Anchor Link

• CHANGELOG.md — buku besar rilis kanonik.
• SECURITY.md — matriks versi yang didukung dan saluran pelaporan.
• cicd-pipeline.md — kelas pemeriksaan CI yang menggerbang setiap rilis.
• deployment-checklist.md — sapuan kesiapan produksi per rilis.