Uyumluluk: bir sürümün vaat ettikleri
Aggrega’nın yükseltilmesi, üzerine inşa ettiğiniz birkaç yüzeyi değiştirebilir: belgelerinizin dayandığı şemalar, betiklerinizin çağırdığı komutlar ve bayraklar, bir yapay zekâ asistanının çağırdığı araçlar, kaydettiğiniz hata kodları ve bir eklentinin derlenmesinde kullanılan eklenti kitleri. Bu sayfa, her biri için bir sürümün neyi değiştirebileceğini ve neyi değiştirmeyeceğini belirtir. Bu sayfanın adını anmadığı bir yüzey, kendi başvuru sayfasının belirttiklerinin ötesinde hiçbir vaat taşımaz. Son bölüm, bunlardan birinin değiştiğini bir sürümün size nerede bildirdiğini söyler. Bu sayfadaki vaatler 0.9.0 ile başlar. 0.9.0’dan önceki Releases desteklenmez: hub kayıt defteri, hub.aggrega.ai, bunlar için yapılmış hiçbir Plugin sürümü sunmaz ve bunların derleyicileri, belgeleri aggrega.ai/v1beta1 bildiren kayıt defteri kataloğunu okuyamaz.
Aggrega 0.x.y sürümleri olarak yayımlanır: bir yama sürümü son sayıyı, bir küçük sürüm ortadakini artırır. Bir katalog varlığının kendi metadata.version değeri ayrı bir konudur — onu yazarı, aggrega lint --pre-publish komutunun denetlediği sürüm artırma ölçütlerine göre seçer ve Sürüm çözümleme bir başvurunun bunlardan birini nasıl seçtiğini açıklar.
Şemalar
Aggrega’nın yayımladığı her şema tek bir API sürümüne, aggrega.ai/v1beta1 sürümüne aittir — bir varlık belgesinin apiVersion alanında bildirdiği değer. Aşağıdaki kural bunların her birini kapsar: varlık türleri, eklenti yükleri ve çalışma alanı ile diğer şemalar — IR, çalışma alanı yapılandırması, kilit dosyaları ve geri kalanı —, tümü Şema başvurusu sayfasında listelenmiştir. API sürümü, sürüm numarasından bağımsızdır: birçok sürüm aynı API sürümünü okur.
v1beta1 içinde neler değişebilir
Bir API sürümü içinde bir şema, Kubernetes’in kendi API sürümlerini değiştirdiği gibi, yalnızca ekleme yoluyla değişir. Bir sürüm şunları yapabilir:
- bir açıklamayı değiştirmek;
- alan isteğe bağlı olduğunda bir alan eklemek.
Böyle bir değişiklikten önce geçerli olan her belge, değişiklikten sonra da geçerlidir ve aynı anlamı taşır. Derleyicinin yazdığı bir belgeyi, örneğin IR’yi veya bir kilit dosyasını okuyan bir programın tanımadığı bir alanı kabul etmesi gerekir; çünkü v1beta1 içinde eklenen isteğe bağlı bir alan bu çıktıda görünebilir.
v1beta2 gerektirenler
Bu değişikliklerin her biri yeni bir API sürümü, aggrega.ai/v1beta2 gerektirir:
- bir alanı kaldırmak veya yeniden adlandırmak;
- bir alanı zorunlu hâle getirmek;
- bir türü veya bir alanın kabul ettiği değerler kümesini daraltmak;
- bir değerin anlamını değiştirmek.
Yeni bir API sürümü, uyumluluğu bozan bir değişikliktir; onu getiren sürümde bu şekilde planlanır ve duyurulur.
Yeni bir isteğe bağlı alan, kataloğa onu tanıyan derleyiciyle birlikte ulaşır
Derleyici, şemasının bildirmediği bir alanı reddeder. Yanlış yazılmış bir anahtarı yakalayan bu katılıktır ve okuyucunun tahmin edemeyeceği bir sonucu vardır: bir katalog varlığı, yeni eklenen isteğe bağlı bir alanı ancak o alanı tanıyan bir derleyiciyi içeren bir sürümde kullanmaya başlayabilir.
Örneğin, bir sürümün Component şemasına isteğe bağlı bir alan eklediğini varsayalım — buna spec.newField diyelim:
- O sürümden önce yazılmış her Component geçerliliğini korur; hiçbiri bu alanı ayarlamaz.
- Bir katalog yazarı,
spec.newFieldalanını ayarlayan bir Component’in yeni bir sürümünü yayımlar. - O sürümden veya daha sonraki bir sürümden bir derleyici, Component’i doğrular ve derler.
- Daha önceki bir sürümden bir derleyici onu reddeder, çünkü kendi şeması bu alanı bildirmez: doğrulama
spec.newField: unexpected propertybildirir ve satırı belirtir.
Dolayısıyla o katalog sürümüne karşı derleme yapan kişi önce alanı ekleyen sürüme yükseltir ve bir katalog, alanı kullanan bir varlığı ancak o sürüm çıktıktan sonra yayımlar. Kilitlenmiş bir Release’in çözümlediği sürümleri nasıl koruduğu Sürüm çözümleme sayfasında anlatılır.
Komut satırı ve asistan araçları
Betikler, CI ardışık düzenleri ve asistan yapılandırmaları aggrega komutlarını, bayraklarını ve asistan araçlarını adlarıyla çağırır. 0.x sürümlerinde:
- Bir yama sürümü hiçbir zaman bir komutu, bir bayrağı veya bir asistan aracını kaldırmaz ya da yeniden adlandırmaz.
- Bir küçük sürüm bunlardan birini kaldırabilir veya yeniden adlandırabilir ve değişiklik günlüğü bunu Removed veya Changed altında belirtir.
- Eklemeler — yeni bir komut, bayrak veya araç — herhangi bir sürümde gelebilir.
Asistan araçları, aggrega mcp komutunun bağlı bir asistana sunduğu araçlardır. Tam listeleri sunucunun kendi yanıtıdır ve Asistanınızın Aggrega ile yapabilecekleri bu listenin nasıl isteneceğini açıklar. Bir komutu çalıştıran bir araç, adını komutun çağrı yolundan alır; bu nedenle bir komutu yeniden adlandırmak onun aracını da yeniden adlandırır. CLI’ya genel bakış tüm komutları listeler.
Hata kodları
Durduran her koşul kısa bir kod taşır — E harfi ve dört rakam, [DEVELOPER_ERROR E0007] örneğindeki gibi — ve bu kod tanılamanın başında yazdırılır. Kısa kodlar kamuya açık bir sözleşmedir: bir kod yalnızca bir kez verilir, asla yeniden numaralandırılmaz ve asla farklı bir koşula verilmez. Kullanımdan kaldırılmış bir koşulun kodu kullanım dışı kalır; böylece bir runbook’ta, bir CI kuralında veya bir issue’da kaydedilmiş bir kod her yükseltmeden sonra aynı koşulu adlandırır.
Hata sentinelleri, bir koşulun taşıdığı tanımlayıcıları — bir kişinin alıntıladığı kısa kodu, bir programın kaydettiği açıklayıcı kodu ve bir programın eşleştirdiği Go erişimcisini —, her birinin neyi vaat ettiğini ve kullanımdan kaldırılmış bir numaranın yeniden verilmesinin nasıl önlendiğini anlatır. Bu sayfadaki tüm koşulların tablosu, kullanımdan kaldırılmış olanlar dahil her kısa kodu çözümler ve aggrega explain terminalde bir kodu çözümler.
Plugin kitleri
Eklenti geliştirme kitleri — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust ve @aggrega-ai/aggrega-pdk-typescript — ve bunların yeniden dışa aktardığı aggrega-abi codec’leri, 0.9.0 sürümünden itibaren anlamsal sürümlemeyi izler. Kitlerin üç dili tek bir sürüm numarasını, codec’lerin üç dili ise başka bir sürüm numarasını paylaşır.
- Bir sürüme karşı derlenen bir eklenti, aynı serinin sonraki her sürümüne karşı da derlenmeye devam eder.
0.9.xiçinde bir sürüm dışa aktarılan işlevler, türler ve sabitler ekleyebilir; hiçbirini asla kaldırmaz veya değiştirmez. - Dışa aktarılan bir API’de uyumluluğu bozan bir değişiklik yalnızca yeni bir küçük sürümde yayımlanır (
0.9.xsürümünden0.10.0sürümüne) ve bir yama sürümü uyumluluğu asla bozmaz. Kitler ve codec’ler, Aggrega’nın kendi1.0.0sürümüyle birlikte1.0.0sürümüne geçer; bundan sonra uyumluluğu bozan bir değişiklik ana sürüm numarasını artırır. - Codec’lerde uyumluluğu bozan bir değişiklik, kitlerde de uyumluluğu bozan bir değişikliktir; kitler codec türlerini yeniden dışa aktardıkları için bununla birlikte kendi küçük sürümlerini artırır.
- Mevcut bir türe eklenen bir alanın veya üyenin ekleme sayılıp sayılmadığı dile bağlıdır. Paketle birlikte yayımlanan her kitin README dosyası, kendi dilinin durumunu “Compatibility” başlığı altında belirtir.
Bu vaat, bir eklentinin kaynak kodunun adını andığı API’yi kapsar. Derleyici ile çalışan bir eklenti arasında aktarılanlar ise eklenti ABI sürümü tarafından korunur: bir ABI sürümü içinde bir soket yalnızca açıklamalar ve isteğe bağlı alanlar kazanır; böylece ona karşı derlenen bir eklenti yüklenmeye devam eder. Eklenti sözleşmesi soketleri, eklenti geliştirici kılavuzu ise bunların etrafındaki iş akışını açıklar.
Bir sürümün değişiklik günlüğü ne söyler
Her sürümün sürümler sayfasındaki notları, Added, Changed, Removed ve Fixed gibi başlıklar altında gruplanmış değişiklik günlüğünü içerir. Bu sayfadaki yüzeyler için:
- Kaldırılan veya yeniden adlandırılan bir komut, bayrak ya da asistan aracı, değişikliği yapan küçük sürümde Removed veya Changed altında listelenir.
- Yeni bir şema API sürümü, onu getiren sürümde uyumluluğu bozan bir değişiklik olarak duyurulur.
- Eklenti kitlerinde veya codec’lerde uyumluluğu bozan bir değişiklik sürüm numaralarında görünür:
1.0.0altındaki yeni bir küçük sürümdür. - Bir hata kodu anlamını asla değiştirmez; bu nedenle hiçbir sürümün duyuracak böyle bir şeyi yoktur.