Otomasi Rilis

Rilis Libre WebUI dibuat dari akar repositori dengan skrip rilis. Skrip membaca riwayat Git sejak tag sebelumnya, memperbarui versi paket, menulis catatan perubahan, menjalankan pemeriksaan, membuat commit rilis dan tag versi. GitHub menjadi sumber build dan biner; metadata rilis serta tautan artefak dicerminkan ke repositori Forgejo proyek.

Penyiapan Lokal Sekali Saja

Pasang dependensi dan aktifkan kait repositori:

npm install
npm run setup-hooks

Penyiapan mengonfigurasi:

.githooks/commit-msg untuk validasi Conventional Commit
.githooks/pre-commit untuk pemeriksaan format
.gitmessage sebagai templat pesan commit

Membuat Rilis

Jalankan skrip pada pohon kerja bersih di cabang yang akan diberi tag:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Skrip secara otomatis:

Memeriksa pohon kerja bersih dan tag lokal berikutnya tersedia.
Mengumpulkan bukti commit, berkas, dependensi, lokal, dan catatan belum dirilis.
Membuat catatan rilis dari bukti tersebut.
Memperbarui package.json, berkas paket ruang kerja, package-lock.json, versi bagan Helm/aplikasi, dan CHANGELOG.md.
Menjalankan npm run release:check, termasuk format, lint, build, tes, audit keamanan, dan simulasi publikasi npm.
Membuat commit dan tag beranotasi hanya setelah semua pemeriksaan lulus.

Membuat Catatan Perubahan

Pratinjau bagian berikutnya tanpa mengubah berkas:

npm run changelog

Perbarui CHANGELOG.md secara manual:

npm run changelog -- update

Secara bawaan, pembuat dapat meminta draf dari model lokal yang kompatibel dengan Ollama, lalu memvalidasinya terhadap bukti Git. Jika AI tidak tersedia atau keluaran tidak aman, generator deterministik digunakan.

Penimpaan yang berguna:

CHANGELOG_AI=0 npm run release:minor
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
OLLAMA_BASE_URL=http://127.0.0.1:11434 npm run release

Mengirim Rilis

Setelah commit dan tag beranotasi dibuat, publikasikan hanya commit cabang dan tag yang ditampilkan skrip. Cabang produksi dikirim ke Forgejo lalu GitHub dengan pengikutan tag dimatikan:

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/heads/main

git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  refs/heads/main

Kedua SHA harus sama dengan commit rilis lokal. Tunggu alur kerja wajib GitHub untuk commit itu lulus sebelum menerbitkan tag.

Pastikan tag belum ada di kedua layanan, lalu kirim satu tag ke Forgejo dan GitHub:

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z
git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

Ganti vX.Y.Z dengan tag rilis. Untuk tag beranotasi, verifikasi SHA objek tag dan commit yang ditunjuk. Jangan gunakan git push --tags karena dapat menerbitkan tag lain.

Jalur Rilis CI

Mengirim tag v* menjalankan alur GitHub yang:

Menjalankan npm run release:check
Membangun artefak Electron macOS, Windows, Linux
Membuat rilis GitHub dari bagian CHANGELOG.md
Mencerminkan rekaman dan tautan ke Forgejo
Membangun image Docker
Menerbitkan bagan Helm dengan versi tag
Menerbitkan paket npm memakai NPM_TOKEN

Pemeriksaan yang sama dapat dijalankan lokal:

npm run release:check

Cermin Rilis Forgejo

Cermin memakai token akses Forgejo yang disimpan sebagai rahasia GitHub Actions FORGEJO_TOKEN. Berikan hanya cakupan write:repository, pastikan pemilik dapat menulis ke libre-webui/libre-webui, dan jangan commit atau cetak token.

Cermin sengaja idempoten. Ia mencari rilis berdasarkan tag, membuat rekaman yang hilang, menyelaraskan metadata GitHub, dan melewati tautan yang sudah ada. Pengulangan setelah kegagalan melengkapi pekerjaan tanpa duplikasi.

Artefak Forgejo berupa tautan eksternal bernama ke GitHub browser_download_url. GitHub tetap menjadi host biner; Forgejo menampilkan nama yang sama tanpa menyalin puluhan gigabita. Arsip sumber dibuat independen dari tag tepat di tiap layanan.

Pratinjau atau Lengkapi Satu Rilis

Lihat perubahan tanpa menulis:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run

Setelah memuat FORGEJO_TOKEN dan GITHUB_TOKEN dari pengelola rahasia, cerminkan rilis:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Tag harus ada di GitHub dan Forgejo serta mengarah ke objek/commit yang sama.

Pratinjau atau Lengkapi Semua Rilis

Audit semua GitHub Release terhadap Forgejo:

node scripts/mirror-forgejo-releases.mjs --all --dry-run

Lengkapi rilis yang hilang:

node scripts/mirror-forgejo-releases.mjs --all

GITHUB_TOKEN wajib untuk --all, termasuk simulasi, karena kesetaraan tag dan penemuan artefak melebihi batas anonim GitHub. FORGEJO_TOKEN juga wajib tanpa --dry-run.

Jalur --all melakukan paginasi dua API dan menilai objek GitHub Release, bukan semua tag. Tag tanpa rilis tetap tag saja di Forgejo. Jalankan simulasi lagi setelah pengisian; tidak boleh ada perubahan.

Kebijakan Tag Tetap

Tag versi yang diterbitkan tidak dapat diubah. Setelah ada di layanan jarak jauh:

Jangan hapus.
Jangan kirim paksa.
Jangan pindahkan ke commit yang diperbaiki.
Jangan gunakan kembali versi untuk isi lain.

Jika isi rilis salah, perbaiki sumber dan catatan, lalu terbitkan patch berikutnya. Jika hanya halaman atau tautan hilang, ulangi cermin idempoten tanpa menyentuh tag.

Tag Forgejo v0.8.6 pernah diselaraskan sekali dengan persetujuan saat pencerminan ganda diperkenalkan. Perbaikan historis itu bukan preseden memindahkan tag terbitan.

Kebijakan Versi Helm

version bagan Helm, appVersion, versi paket akar, dan tag rilis memakai versi semantik yang sama. Skrip menaikkan bersama; CI menolak perbedaan.

Bagan diterbitkan hanya dari tag v* tetap. Jangan menerbitkan isi berubah dengan versi lama. Perubahan harus melalui rilis berikutnya.

Bagan 0.14.1 memiliki penimpaan digest satu kali karena lebih tua dari tag Docker semantik. Digest mengenali image multiarsitektur 0.14.1 terverifikasi. Skrip menghapus penimpaan pada rilis berikutnya; image bawaan lalu memakai appVersion.

Alur Docker menerbitkan tag semantik ke GHCR dan Docker Hub dari tag v* yang sama. Helm menunggu maksimal 20 menit untuk image publik; gagal daripada menerbitkan bagan tanpa image. Image Ollama dikonfigurasi terpisah dan memakai latest.

Conventional Commits

Pesan commit memakai format Conventional Commit:

<type>[optional scope]: <description>

Jenis umum:

feat: fitur pengguna
fix: perbaikan bug
docs: pembaruan dokumentasi
refactor: restrukturisasi internal
perf: peningkatan kinerja
test: cakupan tes
chore: pemeliharaan, rilis, atau build

Perubahan tidak kompatibel memakai !:

git commit -m "feat!: remove deprecated endpoint"
git commit -m "fix(auth)!: change token validation"

Pemecahan Masalah

Direktori Kerja Tidak Bersih

Commit atau simpan perubahan sebelum rilis:

git status --short
git add .
git commit -m "fix: resolve pending changes"

Tidak Ada Perubahan yang Dapat Dirilis

Periksa commit sejak tag sebelumnya:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Catatan Perubahan Perlu Disunting

Sunting CHANGELOG.md, lalu commit sebelum tag:

git add CHANGELOG.md
git commit -m "docs: refine changelog"

Batalkan Commit Rilis Lokal

Jika commit dan tag belum dikirim:

git tag -d v0.12.0
git reset --soft HEAD~1

Jika tag sudah ada jarak jauh, jangan hapus atau ganti. Perbaiki di main, buat patch berikutnya, dan terbitkan tag baru melalui pemeriksaan lengkap.

Cermin Forgejo Tidak Lengkap

Verifikasi SHA objek dan commit di kedua layanan, lalu ulangi:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run
node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Kesalahan otorisasi berarti FORGEJO_TOKEN hilang, kedaluwarsa, tanpa akses, atau tanpa write:repository. Tag hilang/berbeda diselidiki terpisah; cermin tidak membuat atau memindahkan tag.

Berkas Pemelihara

.gitmessage - templat pesan commit
.githooks/commit-msg - validasi Conventional Commit
.githooks/pre-commit - pemeriksaan format
scripts/release.js - orkestrasi rilis
scripts/mirror-forgejo-releases.mjs - cermin Forgejo
scripts/generate-changelog.js - pratinjau/pembaruan catatan
scripts/lib/releaseNotes.js - pengumpulan bukti
.github/workflows/release.yml - rilis CI berbasis tag
.github/workflows/helm-publish.yml - validasi dan publikasi Helm

Informasi Conventional Commits: https://www.conventionalcommits.org/.

Penyiapan Lokal Sekali Saja​

Membuat Rilis​

Membuat Catatan Perubahan​

Mengirim Rilis​

Jalur Rilis CI​

Cermin Rilis Forgejo​

Pratinjau atau Lengkapi Satu Rilis​

Pratinjau atau Lengkapi Semua Rilis​

Kebijakan Tag Tetap​

Kebijakan Versi Helm​

Conventional Commits​

Pemecahan Masalah​

Direktori Kerja Tidak Bersih​

Tidak Ada Perubahan yang Dapat Dirilis​

Catatan Perubahan Perlu Disunting​

Batalkan Commit Rilis Lokal​

Cermin Forgejo Tidak Lengkap​

Berkas Pemelihara​