Semantik sürüm oluşturma

Semantik Sürüm Oluşturma (SemVer) - sürüm numarasının değişikliklerin doğasını nasıl yansıttığına dair bir sözleşme. Biçim: MAJOR. MINÖR. PATCH [-PRERELEASE] [+ BUILD].

• MAJOR - Uyumsuz değişiklikler (kırılma).
• MINOR - karşılıklı olarak uyumlu özellikler/uzantılar.
• PATCH - Geriye Dönük Uyumlu Hata/Güvenlik Düzeltmeleri.

Hedef: ani tüketici arızaları olmadan API'lerin, olayların, veri şemalarının, SDK'ların ve yapılandırmaların öngörülebilir evrimi.

1) Sözleşme numaraları

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Ön sürüm ('-alpha', '-beta', '-rc') - kararsız meclisler; Uyumluluk sözü vermeyin.
Yapı meta verileri ('+ sha') - karşılaştırma sırasını etkilemez, izleme için kullanışlıdır.
1'e kadar. 0. 0 Herhangi bir değişiklik kırılma olarak kabul edilebilir (ancak kuralları en baştan takip etmek daha iyidir).

2) Kırılma/minör/yama dikkate alınması gerekenler

• Sözleşmeyi değiştirmeden hatalar ve güvenlik için düzeltmeler.
• Sözleşmeyi etkilemeyen yükleme güncellemeleri.
• Yanıtları/olayları/şemaları değiştirmeden optimizasyon.

• Yeni isteğe bağlı alanlar/yöntemler/uç noktalar ekleyin.
• Tüketiciler bilinmeyen değerleri tolere ederse enum değerlerini genişletmek.
• Yeni veritabanı indeksleri, öntanımlı geçersiz sütunlar, eskilere ek olarak yeni olaylar.

• Alanları silme/yeniden adlandırma, türleri değiştirme, zorunlu.
• Anlambilim/durum/hata kodlarını değiştirin.
• Serileştirme biçiminin değiştirilmesi, anahtar şeması, taşıma protokolü.
• Konuları sıkıştırın/birleştirin, olayın anlamını aktarın, bölümleme şemasını değiştirin.
• Geriye dönük uyumluluk olmadan "iki fazlı" anahtarlama gerektiren veritabanı geçişleri.

3) Artifact sürüm oluşturma

3. 1 REST

Değişkenler: 'URI/v1/...', başlıklar ('Accept: application/vnd. Acme. oyun + json; sürüm = 1 '), parametre.
Öneri: Genel API'ler için URI'de sürüm; İç için - başlık c müzakere yoluyla.
MINOR: isteğe bağlı alanlar, yeni filtreler/kaynaklar ekleyin; Mevcut cevapları değiştirmeyin.
PATCH: düzeltmeler, tanım iyileştirme, kararlı sıralama.

3. 2 gRPC

MAJOR'u değiştirme - imzalar/türler (yeni paket/hizmet: 'acme. Cüzdan. v2 ').
Yeni alanlar - isteğe bağlı olarak etiketlenmiş; Sunucu bilinmeyeni göz ardı etmelidir.
Alanları silmiyoruz: "depricket + bir numara rezerve et", sil - sadece bir sonraki MAJOR'da.

3. 3 GraphQL

MINOR: yeni alanlar/türler/sorgu; Kaldırma - '@ kullanımdan kaldırıldı' + geçiş penceresi, tam kaldırma - MAJOR.
Nullable değiştir - non-nullable - MAJOR.

3. 4 Olaylar ve Konular (Kafka/SQS)

Schema Registry'deki şemalar: eklemenin evrimi (varsayılanları olan alanları ekleyin).
Yeni uyumsuz versiyon - yeni konu/konu ('bet. yerleşmiş. v2 ').
Bölümleme anahtarı MAJOR içinde değişmez.

3. 5 DB diyagramı

1. Bir sütun ekle (geçersiz/varsayılan)

2. Arka dolguyu doldur

3. Çevir> Okur

4. Eski (sadece MAJOR) kaldırın.

Değişim tipi/PK/benzersizlik - MAJOR, phicheflag ve çift giriş altında.

3. 6 SDK/CLI

Genel yöntemler/imzalar aynı kurallardır.
Otojenerasyon için (OpenAPI/Proto) - toplu iş adı ve artefaktlarının sürümü.

4) Yoksunluk politikası ve yaşam döngüsü

Her kırılma değişiminden önce depriksiyon gelir (genellikle dış için 90-180 gün, iç için 30-60).
İletişim: changelog, ortaklara e-posta/webhooks, geliştirici portalında afişler.
Çift çalıştırma modu: 'v1've' v2'yi paralel tutun, 'v1' trafiğinin payını izleyin.
Sunset başlıkları (REST): 'Sunset: 2026-03-31', 'Link: <url>; rel = "amortisman" '.

5) Sürüm müzakeresi

İstemci istenen sürümü + maksimum desteklenen sürümü gönderir (örneğin, 'Accept-Version: 1,2').
Sunucu 'Content-Version: 2'ile yanıt verir.
Çift yönlü protokollerde (WebSocket, gRPC) - Hello çerçevelerinin 'supported _ versions'ile değişimi.

6) Sağlayıcı Adaptörü Entegrasyonu (ACL)

Harici sağlayıcı şemayı değiştirir - adaptörün içinde v1/v2 haritalarını saklarız ve dahili olay için MINOR'u serbest bırakırız, alan sözleşmemizi koruruz.
Dış değişiklikler içeri girerse, bu alan etkinliğimizin MAJOR'u ve yeni bir konudur.

7) Changelog ve taahhüt etiketleri

• 'sahte:'... - KÜÇÜK
• 'düzeltme:... '/' angarya ',' dokümanlar ',' perf '(sözleşme yok) - PATCH
• 'feat!:'/' fix!:'/' refactor!:'ya da' BREAKING CHANGE: 'IN MAJOR ™ body

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Serbest bırakma otomasyonu

CI: devre doğrulayıcılar (OpenAPI/Protobuf/Avro/JSON-Schema), breaking-diffuse detect. Daha fazla

SemVer-bot: analiz Konvansiyonel Commits ™ yumru (majör/minör/yama) hesaplar, bir etiket koyar, bir changelog oluşturur.
CD: ayrı dağıtım ve sürüm (phicheflags/configurs yeni sürümü etkinleştirir).
Kontrol: Başarılı kanarya ve kabul edilen SLO'lara kadar PRO'da'en son "yayınlamayın.

9) Yapılandırmalar ve politikalar için semantik

Configs (YAML/JSON) ayrıca bir şema sürümüne sahiptir: 'schema _ version: 3'.
MINOR - yeni isteğe bağlı alanlar/kurallar MAJOR - yapı/yükümlülük değişikliği.
Doğrulayıcıda v2/v3 desteği; uyumsuzluk raporu ile config migrator.

10) Uyumluluk testi

Tüketici odaklı sözleşme testleri (Pact): entegrasyon başına.
Şema-evrim testleri: Eski yükleri yeni bir şema üzerinde çalıştırın ve bunun tersi de geçerlidir.
Replay - Prodüksiyon trafiğini 'v1'den' v2'ye gölgede oynatır.
Özellik tabanlı: bilinmeyen alanlara/enuma karşı direnç.

11) Versiyona göre gözlemlenebilirlik

Etiket metrikleri/günlükleri: 'api _ version', 'schema _ version', 'event _ version'.
Geçiş panoları: sürümlere göre trafik paylaşımı, 'v1/v2'ile hata/gecikme.
Uyarılar: 'v1' planlandığı gibi gitmezse; 'V2' sürümünden sonra 4xx/5xx büyümesi.

12) Kesinti olmadan geçiş kalıpları

Genişlet - Göç Et - Sözleşme (БД).
Çift yazma + okumayı değiştirmeden önce farklılıkları karşılaştırın.
Sıralama/kurallar için gölge karşılaştırması.
Kanarya kiracı/bölgeye göre; Hızlı geri dönüşler için özellik bayrakları.
Read-compat/Write-compat pencereleri: Yeni sürüm eski verileri okur, ancak yeni bir biçimde yazar.

13) Anti-desenler

Kaynak/olayın sürümü yerine "Her alandaki sürüm".
MINOR altında gizli kırılma değişiklikleri (örneğin, varsayılanları değiştirme).
Pencere ve tüketim metrikleri olmadan depricated kaldırılması.
"Forever v1": Teknik borçların ve güvenlik açıklarının eski sürümlerini kaldırma planı yok.
İş sürümünü ve konteyner görüntü sürümünü karıştırın.

14) Sürüm İlkesi Kontrol Listesi

• Sabit sürüm biçimi ve doğruluk kaynakları (Kayıt Defteri/Portal).
• Eserler tarafından kırılma kriterlerinin onaylanmış listesi (REST/gRPC/GraphQL/events/DB).
• Deprications süreci: zamanlama, iletişim, gün batımı/afişler, çift çalışma.
• Otomatik diff denetleyicisi ve Konvansiyonel Taahhütler.
• Sürüm ve uyarı tüketim panoları.
• Migration playbooks (expand/migrate/contract, dual-write, shadow).
• Configs ve SDK'ların kendi sürümleri ve durumları vardır.
• Müşteriler için'bir sürüm nasıl seçilir've ekipler için "nasıl yükseltilir" belgeleri.

15) Sürüm oluşturma örnekleri (iGaming örnekleri)

'BetSettled v1' event> 'v2': 'void _ reason' (isteğe bağlı) ve 'tax' eklendi. Tutar '(isteğe bağlı) - MINOR. Yeniden adlandırılmış 'ödeme' - 'win _ amount' - MAJOR, yeni bir konu.
REST'/wallets/transfer ': eklenmiş filtre'? tenant _ id = '- MINOR. '409' - '422' - MAJOR hata kodu değiştirildi.
GraphQL: işaretli 'Player. age ',' Player 'lehine' @ depressed'olarak. AgeGroup '- MINOR'da serbest bırakma, X döneminden sonra MAJOR'da silme.
DB: eklenen sütun 'bonus _ wager _ left' nullable - MINOR. Null olmayan yapılmış ve silinmiş 'bonus _ left' - MAJOR (genişletme/sözleşme yoluyla).

Sonuç

Semantik sürüm oluşturma sayılarla değil, güven ve öngörülebilirlikle ilgilidir. Açık kurallar, otomatik kontroller, kontrollü depolamalar ve şeffaf telemetri, API'lerin, olayların ve ağrısız şemaların entegrasyonlar için gelişmesini sağlar ve değişiklikleri sık, güvenli ve anlamlı bir şekilde serbest bırakır.