Sürüm Otomasyonu

Libre WebUI sürümleri depo kökünden sürüm betiğiyle oluşturulur. Betik önceki sürüm etiketinden sonraki gerçek Git geçmişini okur, paket sürümlerini günceller, değişiklik günlüğünü yazar, sürüm kontrollerini çalıştırır, sürüm kaydını ve sürüm etiketini oluşturur. Derlemelerin ve ikili dosyaların yayın kaynağı GitHub’dır; sürüm üst verileri ile adlandırılmış yapıt bağlantıları projenin Forgejo deposuna yansıtılır.

Tek Seferlik Yerel Kurulum

Bağımlılıkları kurup depo kancalarını etkinleştirin:

npm install
npm run setup-hooks

Kanca kurulumu şunları yapılandırır:

Conventional Commit doğrulaması için .githooks/commit-msg
Biçim kontrolleri için .githooks/pre-commit
Yerel kayıt iletisi şablonu olarak .gitmessage

Sürüm Oluşturma

Sürüm betiğini etiketlemek istediğiniz dalın temiz çalışma ağacında çalıştırın:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Betik otomatik olarak:

Çalışma ağacının temizliğini ve sonraki yerel etiketin kullanılabilirliğini denetler.
Kayıt, dosya, bağımlılık, yerel ve yayımlanmamış günlük kanıtlarını toplar.
Bu kanıtlardan sürüm notlarını oluşturur.
package.json, çalışma alanı paket dosyaları, package-lock.json, Helm çizelgesi ve uygulama sürümleri ile CHANGELOG.md dosyasını günceller.
Biçim, kod denetimi, derleme, test, güvenlik denetimi ve npm deneme yayını dâhil npm run release:check komutunu çalıştırır.
Yalnızca tüm kontroller geçtikten sonra sürüm kaydını ve açıklamalı etiketi oluşturur.

Değişiklik Günlüğü Oluşturma

Dosyaları değiştirmeden sonraki bölümü önizleyin:

npm run changelog

Oluşturulan bölümden CHANGELOG.md dosyasını elle güncelleyin:

npm run changelog -- update

Oluşturucu varsayılan olarak yerel, Ollama uyumlu bir modelden düzenlenmiş taslak isteyebilir, ardından sonucu Git kanıtıyla doğrular. AI kullanılamıyorsa veya çıktı güvensiz görünüyorsa belirlenimci oluşturucuya döner.

Yararlı geçersiz kılmalar:

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

Sürümü Gönderme

Sürüm kaydı ve açıklamalı etiket oluşturulduktan sonra yalnızca betiğin gösterdiği kesin dal kaydını ve etiketi yayımlayın. Üretim dalı, etiket izlemesi açıkça kapalı biçimde önce Forgejo’ya, sonra GitHub’a gönderilir:

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

Dönen iki dal SHA değeri de amaçlanan yerel sürüm kaydına eşit olmalıdır. Etiketi yayımlamadan önce tam bu kayıt için zorunlu GitHub iş akışlarının geçmesini bekleyin.

Sürüm etiketinin iki hizmette de bulunmadığını doğrulayın, ardından tek etiketi önce Forgejo’ya, sonra GitHub’a gönderin:

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^{}'

vX.Y.Z yerine sürüm etiketini yazın. Açıklamalı etikette etiket nesnesinin ve işaret ettiği kaydın SHA değerlerini doğrulayın. İlgisiz yerel etiketleri yayımlayabileceği için git push --tags kullanmayın.

CI Sürüm Yolu

v* etiketi göndermek GitHub sürüm iş akışını başlatır. İş akışı:

npm run release:check komutunu çalıştırır
macOS, Windows ve Linux için Electron yapıtları oluşturur
Uygun CHANGELOG.md bölümünden GitHub sürümü oluşturur
Sürüm kaydını ve yapıt bağlantılarını Forgejo’ya yansıtır
Docker görüntüleri oluşturur
Helm çizelgesini etiketle aynı sürümle yayımlar
npm paketini NPM_TOKEN ile yayımlar

Aynı kontrol etiketlemeden önce yerelde çalıştırılabilir:

npm run release:check

Forgejo Sürüm Yansısı

Yansı, şifreli GitHub Actions gizlisi FORGEJO_TOKEN olarak tutulan kişisel Forgejo erişim belirtecini kullanır. Belirtece yalnızca write:repository kapsamını verin, sahibinin libre-webui/libre-webui üzerine yazabildiğinden emin olun ve belirteci hiçbir zaman kaydetmeyin ya da yazdırmayın.

Yansı özellikle eşgüçlüdür. Sürümleri etikete göre bulur, yalnızca eksik kayıtları oluşturur, GitHub üst verilerini uzlaştırır ve mevcut yapıt bağlantılarını atlar. Ağ veya iş akışı hatasından sonra yeniden deneme, sürüm ya da varlıkları çoğaltmadan eksik işi tamamlar.

Forgejo sürüm varlıkları, ilgili genel GitHub browser_download_url adresine adlandırılmış dış bağlantılardır. İkili dosyaları GitHub barındırmaya devam eder; Forgejo masaüstü yapıtlarının onlarca gigabaytını kopyalamadan aynı dosya adlarını gösterir. Kaynak arşivleri her hizmette kesin etiketten bağımsız oluşturulur.

Tek Sürümü Önizleme veya Tamamlama

Forgejo’ya yazmadan değişecekleri inceleyin:

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

FORGEJO_TOKEN ve GITHUB_TOKEN değerlerini bakımcının gizli bilgi yöneticisinden işleme yükledikten sonra sürümü yansıtın:

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

Kesin etiket GitHub ve Forgejo’da bulunmalı, aynı etiket nesnesi ile kayda çözülmelidir.

Tüm Sürümleri Önizleme veya Tamamlama

Her GitHub sürümünü Forgejo ile karşılaştırın:

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

Eksik veya tamamlanmamış Forgejo sürümlerini doldurun:

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

Kesin etiket eşliği ve varlık bulma, GitHub’ın adsız API sınırından daha çok istek gerektirdiği için deneme çalıştırmaları dâhil --all için GITHUB_TOKEN gerekir. --dry-run kullanılmadığında ayrıca FORGEJO_TOKEN gerekir.

--all yolu iki API’yi sayfalar ve her Git etiketini değil GitHub sürüm nesnelerini değerlendirir. Bilerek GitHub sürümü olmayan etiket Forgejo’da yalnızca etiket kalır. Tamamlamadan sonra deneme çalıştırmasını yineleyin; bekleyen değişiklik olmamalıdır.

Değişmez Etiket İlkesi

Yayımlanmış sürüm etiketleri değişmezdir. Bir etiket uzak hizmetlerden birinde bulunduğunda:

Silmeyin.
Zorla göndermeyin.
Düzeltilmiş kayda taşımayın.
Anlamsal sürümünü farklı içerik için yeniden kullanmayın.

Yayımlanmış sürüm içeriği yanlışsa kaynağı ve günlüğü düzeltip sonraki düzeltme sürümünü yayımlayın. Yalnızca sürüm sayfası veya dış varlık bağlantısı eksikse etikete dokunmadan eşgüçlü yansıyı yeniden çalıştırın.

Forgejo v0.8.6 etiketi çift sürüm yansıtması eklenirken bir kez, açık onayla yeniden hizalandı. Aynı kaynak ağaçlarını farklı kayıt zincirlerinde tanımlayan iki tarihî etiket nesnesini onardı. Denetlenmiş bu geçiş, yayımlanmış etiketleri taşımak için emsal değildir.

Helm Sürüm İlkesi

Helm çizelgesinin version, appVersion, kök paket sürümü ve sürüm etiketi bilinçli olarak aynı anlamsal sürümü kullanır. Sürüm betiği hepsini birlikte ilerletir, CI uyumsuzluğu reddeder.

Çizelge yalnızca değişmez v* etiketinden yayımlanır. Değiştirilmiş içeriği mevcut çizelge sürümü altında yayımlamayın. Değişiklik yeni sürüm almak için sonraki uygulama sürümünden geçmelidir.

0.14.1 çizelgesi, bu sürüm anlamsal Docker etiketlerinden önce olduğu için tek seferlik özet geçersiz kılması taşır. Özet, doğrulanmış çok mimarili 0.14.1 görüntüsünü tanımlar. Sürüm betiği sonraki sürümde bunu temizler; ardından varsayılan görüntü appVersion değerine çözümlenir.

Docker iş akışı aynı v* etiketinden anlamsal sürüm etiketini GHCR ve Docker Hub’a yayımlar. Helm yayını eşleşen genel Docker Hub görüntüsünü 20 dakikaya kadar bekler; eksik varsayılan görüntülü çizelge yayımlamak yerine başarısız olur. Paketli Ollama görüntüsü bağımsız yapılandırılır ve varsayılan olarak üst kaynak latest etiketini kullanır.

Conventional Commits

Kayıt iletileri Conventional Commit biçimini kullanmalıdır:

<type>[optional scope]: <description>

Yaygın türler:

feat: kullanıcıya yönelik özellik
fix: hata düzeltmesi
docs: belge güncellemesi
refactor: iç kod yeniden yapılandırması
perf: başarım iyileştirmesi
test: test kapsamı
chore: bakım, sürüm veya derleme işi

Uyumsuz değişiklikler ! kullanır:

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

Sorun Giderme

Çalışma Dizini Temiz Değil

Sürümden önce yerel değişiklikleri kaydedin veya saklayın:

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

Yayımlanabilir Değişiklik Yok

Önceki etiketten sonraki kayıtları denetleyin:

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

Değişiklik Günlüğü Elle Düzenlenmeli

CHANGELOG.md dosyasını düzenleyip düzeltmeyi etiket yayınından önce kaydedin:

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

Yerel Sürüm Kaydını Geri Alma

Sürüm kaydı ve etiketi gönderilmediyse:

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

Etiket uzaklardan birindeyse silmeyin veya değiştirmeyin. Sorunu main üzerinde düzeltin, sonraki düzeltme sürümünü oluşturun ve yeni değişmez etiketi tam denetimden yayımlayın.

Forgejo Yansısı Eksik

Önce iki uzak etikette nesne ve kayıt SHA değerlerinin eşleştiğini doğrulayın. Ardından etkilenen sürümü önizleyip yineleyin:

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

Yetkilendirme hatası FORGEJO_TOKEN değerinin eksik, süresi dolmuş, deposuz kullanıcıya ait veya write:repository kapsamından yoksun olduğunu gösterir. Eksik ya da farklı uzak etiket ayrı incelenmelidir; yansı Git etiketlerini oluşturmaz veya taşımaz.

Bakımcı Dosyaları

.gitmessage - kayıt iletisi şablonu
.githooks/commit-msg - Conventional Commit doğrulaması
.githooks/pre-commit - biçim ön kontrolü
scripts/release.js - sürüm düzenlemesi
scripts/mirror-forgejo-releases.mjs - eşgüçlü Forgejo yansısı ve tamamlama
scripts/generate-changelog.js - günlük önizleme/güncelleme komutu
scripts/lib/releaseNotes.js - kanıt toplama ve günlük üretimi
.github/workflows/release.yml - etiket güdümlü CI sürümü
.github/workflows/helm-publish.yml - Helm doğrulaması ve etiket yayını

Conventional Commits hakkında daha fazla bilgi: https://www.conventionalcommits.org/.

Tek Seferlik Yerel Kurulum​

Sürüm Oluşturma​

Değişiklik Günlüğü Oluşturma​

Sürümü Gönderme​

CI Sürüm Yolu​

Forgejo Sürüm Yansısı​

Tek Sürümü Önizleme veya Tamamlama​

Tüm Sürümleri Önizleme veya Tamamlama​

Değişmez Etiket İlkesi​

Helm Sürüm İlkesi​

Conventional Commits​

Sorun Giderme​

Çalışma Dizini Temiz Değil​

Yayımlanabilir Değişiklik Yok​

Değişiklik Günlüğü Elle Düzenlenmeli​

Yerel Sürüm Kaydını Geri Alma​

Forgejo Yansısı Eksik​

Bakımcı Dosyaları​