İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Yayımlama yüzeyi

Her Aggrega katalog YAML’ı, varlığı katalog dağıtımı için tanımlayan tek tip bir meta veri alanları kümesi taşır: onu kimin sürdürdüğü, hangi lisansla sunulduğu, kaynağının nerede bulunduğu, keşif için onu hangi anahtar sözcüklerin öne çıkardığı. Bu alanlar birlikte yayımlama yüzeyini oluşturur: katalog yayımcılarının ve araç tüketicilerinin dayandığı, labels-and-annotations.md sayfasında belgelenen içerik tarafındaki metadata.labels / metadata.annotations mekanizmasından ayrı olan meta veri sözcük dağarcığı.

Bu sayfa yayımlama yüzeyi alanlarını, külliyat genelindeki açıklama alanı envanterini (zarf, örnek ve alan düzeyindeki açıklamalar), sürdürücü alanının amaçlanan kullanımını ve doğrulanmış tüketicisini ve varlık başına zorunlu alan asimetrilerini (her varlığın bugün hangi alanları zorunlu kıldığını ve asimetrilerin nerede kasıtlı olduğunu) belgeler.

Yayımlama yüzeyi alanları

Aşağıdaki alanlar her Domain 2 (Component, Feature) ve Domain 3 (Recipe, FeatureRecipe, Plugin) varlığında, ayrıca yeniden kullanılabilir bir modül olarak Aggregate’te bulunur. Manifest ve Release’te de daraltılmış bir anlamla (katalog yayımı yerine çalışma alanı atfı) bulunurlar.

AlanTürAmaçTüketici
descriptionstringVarlığın insanlar tarafından okunabilir özetiDüzenleyici üzerine gelme kartları (aggrega serve); bir asistanın çağırdığı describe aracı (aggrega mcp); yayımlanan yapıt üzerinde aranabilir bir ek açıklama (aggrega push); aggrega inspect
maintainersnesne dizisiVarlığın sahibi (ad, e-posta, url)IR’de, Component düğümlerinde düğüm başına catalog_metadata
licensestringYasal uyumluluk (genellikle SPDX tanımlayıcısı)IR’de, Component düğümlerinde düğüm başına catalog_metadata
repositorystring (URL)Kaynağın bulunduğu Git deposuIR’de, Component düğümlerinde düğüm başına catalog_metadata; başka hiçbir şey onu okumaz
homestring (URL)Belgelendirme / wiki URL’siIR’de, Component düğümlerinde düğüm başına catalog_metadata; başka hiçbir şey onu okumaz
keywordsstring dizisiKeşif etiketleriIR’de, Component düğümlerinde düğüm başına catalog_metadata; hiçbir arama dizini bunları tüketmez

Altı alanın tümü, onları taşıyan her varlıkta isteğe bağlıdır. Bu alanların tamamını atlayan bir katalog yazarı da geçerli bir YAML üretir: yayımlama yüzeyi, katalog dağıtımı amaçlanan varlıklar içindir; dahili kullanıma yönelik varlıklar onu hiçbir sonucu olmadan atlayabilir.

Tüketici sütunu bugün sunulanlar için eksiksizdir ve bunun iki sonucunu açıkça belirtmek gerekir, çünkü bunlar neyin yazmaya değer olduğunu değiştirir:

  • description, birden fazla okuyucusu olan tek alandır. aggrega serve onu Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest ve dört kütüphane türü (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) için üzerine gelme kartına işler; Plugin veya Release için işlemez. aggrega mcp’nin sunduğu describe aracı onu her türden bir varlık için döndürür. aggrega push onu yayımlanan yapıta aranabilir bir ek açıklama olarak damgalar. aggrega inspect onu her tür için varlığın başlığının altında yazdırır ve başka hiçbir yayımlama yüzeyi alanını yazdırmaz.
  • repository, home ve keywords doğrulanır ve taşınır; IR’nin ötesinde onları hiçbir şey okumaz. Hiçbir listeleme yüzeyi, katalog sitesi veya arama dizini onları tüketmez. Bunları yazmak, varlıkla birlikte taşınan ve IR çıktısından ve bir yönetişim politikasından okunabilen köken bilgisini kaydeder; varlığı hiçbir yerde bulunabilir kılmaz.

Kullanımdan kaldırma bir yayımlama yüzeyi alanı değildir. Bir varlık, yayımdan sonra kayıt defterinde ona karşı bir işaretçi kaydedilerek kullanımdan kaldırılır: bir önem derecesi (warning, error veya retracted), bir gerekçe ve bir yedek taşıyan, çekme sırasında doğrulanan imzalı bir işaretçi. Ardından kilit dosyasını okuyan her yüzey bunu bildirir; build.halt_on_deprecated_severity yalnızca bunun bir derlemeyi de durdurup durdurmayacağına karar verir. İşaretçi hiçbir zaman varlığın kendi YAML’ında yazılmaz ve bunun nedeni yapısaldır: yayımlanan bir yapıt değiştirilemez, dolayısıyla yayım anında ona dondurulan bir bayrak daha sonra alınan bir kararı asla ifade edemezdi. aggrega inspect’in bir katalog varlığı için yazdırdığı kullanımdan kaldırma bildirimi, adıyla çözümlediği her tür için işaretçiden gelir.

IR tüketimi: düğüm başına catalog_metadata

Derleyici, yayımlama yüzeyi alanlarını her Component’ten o düğümün catalog_metadata bloğuna taşır; bu blok, bir çalıştırmanın geri verdiği IR grafiğinde görünür (aggrega inspect <release> --ir-graph). Blok maintainers, license, repository, home ve keywords alanlarını tutar; bunlar IR’nin taşıdığı beş alandır, description aralarında değildir. IR grafiği sözleşmesine göre oluşturulan araçlar, katalog YAML’ını yeniden okumak yerine meta verileri buradan okur.

Yalnızca Component düğümleri. Blok, düğümün bileşen türü katalogda bir Component olarak aranarak doldurulur; bu nedenle bir Feature’ın, Recipe’nin, FeatureRecipe’nin veya Plugin’in yayımlama yüzeyi IR’ye hiçbir zaman ulaşmaz: bu varlıklar alanları taşır ve alanlar doğrulanır, ancak onlardan hiçbir IR düğümü oluşmaz.

Kaynak Component üzerindeki her yayımlama yüzeyi alanı boş veya sıfır olduğunda catalog_metadata, IR JSON’ından tamamen çıkarılır: blok boş değerlerle yayılmak yerine atlanır. Böylece aynı girdi aynı sıkı çıktıyı üretir ve bu da IR farkını çalıştırmalar arasında kararlı tutar.

Bir yönetişim politikası bloğu okuyabilir. plugins.governance altında ir-verdict rolüyle eklenen bir plugin, her Component düğümünün catalog_metadata’sı dahil olmak üzere IR grafiğinin tamamını düğüm düğüm alır; böylece bir politika, bir düğümün license, repository, home, keywords veya maintainers alanına göre bir derlemeyi kabul edebilir ya da reddedebilir. Bu erişim yönetişim soketine özgüdür: bir sağlayıcının işleme plugin’i, catalog_metadata içermeyen sınırlı bir düğüm başına izdüşüm alır; dolayısıyla işleme plugin’leri bu alanları okuyamaz.

Üç açıklama türü

description alanı zarf üzerinde tek biçimde yer alır, ancak derlem ayrıca şema bildirimlerinin içinde (alan başına açıklamalar) ve sütun gövdelerinin içinde (örnek başına açıklamalar) açıklama tarzı dizeler de taşır. Üç ayrı açıklama türü bir arada bulunur; aşağıdaki tablo bunları birbirinden ayırır.

TürBulunduğu yerYazanAmaç
Zarf açıklamasıHer varlıkta metadata.descriptionKatalog yayıncısıVarlığın bütününün özeti; düzenleyici üzerine gelme kartlarında gösterilir ve yayımlanan yapıta damgalanır
Örnek açıklamasıÖrnek başına bir bildirimin yanındaki description alanı (ör. featuresSchema.<slot>.description, usesSchema.<socket>.description)Şema yazarıYuva / soket / port başına açıklama; bildirimi okuyan, onu tüketen varlıkların yazarları için
Alan açıklamasıschema: / featuresSchema: / usesSchema: içeriğindeki (kompakt biçim veya tam JSON Schema YAML) JSON Schema 2020-12 description: ek açıklamasıŞema yazarıŞemayla birlikte taşınan alan başına belgeler

Üç tür “description” sözcüğünü paylaşır, ancak yapısal olarak farklı düzeylerde bulunur. Zarf açıklaması varlığın bütününe uygulanır; örnek açıklaması bir şema yuvasının içindeki bir bildirime uygulanır; alan açıklaması ise türlendirilmiş bir şemanın içindeki belirli bir değere uygulanır. Bir Component yazan yazarlar:

  • Component varlığının kendisi için metadata.description alanını bir kez ayarlar.
  • Component’in bildirdiği her kimlik bilgisi yuvası için featuresSchema.admin_password.description alanını bir kez ayarlar.
  • Component’in şemasını okuyan herkes için her alanı belgelemek üzere schema: bloğunun içinde, kompakt biçimde (port: { type: integer, description: "..." }) veya tam JSON Schema YAML olarak, alan başına description: ek açıklamaları ayarlar.

Üç tür birbirine aktarılmaz ve çakışmaz; her biri farklı bir yüzeye ulaşır ya da hiçbirine ulaşmaz:

  • Zarf açıklaması: yukarıdaki Tüketici sütununa göre düzenleyici üzerine gelme kartları, yayımlanan yapıtın aranabilir ek açıklamaları ve aggrega inspect.
  • Alan açıklaması: bir Component’in veya bir Feature’ın üzerine gelme kartının işlediği şema alıntısında olduğu gibi görünür. Alıntı yalnızca spec.schema alanını kapsar ve ilk satırlarına kısaltılır; bu nedenle bloğun daha derinindeki bir açıklama ya da featuresSchema: veya usesSchema: içindeki bir açıklama orada görünmez.
  • Örnek açıklaması: bildirilir ve varlıkla birlikte taşınır; yayımlanan hiçbir yüzey onu tek başına işlemez. aggrega inspect, bir Component’in soketlerini ve feature yuvalarını açıklamaları olmadan listeler.

Bakımcı alanının amacı

maintainers alanı, her biri name, email ve url içeren bir nesne dizisi taşır. Amacı ve doğrulanmış tüketicisi:

Amaç (bilgilendirme + IR kaynak bilgisi). Alan, katalog yayımlama için bilgilendirme amaçlıdır: mimari amaç “bu katalog varlığından kim sorumlu” sorusudur; varlıkla birlikte taşınan bir sahiplik sinyalidir. Hiçbir yüzey onu bir iletişim listesi olarak sunmaz ve hiçbir yerleşik denetim onu herhangi bir şeyle karşılaştırmaz.

Doğrulanmış tüketici (düğüm başına catalog_metadata). Derleyici, her Component’in metadata.maintainers değerini IR’de o düğümün catalog_metadata.maintainers alanına taşır; kaynak Component bir bakımcı bildirdiğinde bu, aggrega inspect <release> --ir-graph komutunun döndürdüğü grafikte görünür. Alanın tek okuyucusu budur. ir-verdict rolünde plugins.governance altına eklenen bir yönetişim politikası onu orada görür; böylece bir sahiplik kuralı (her varlık en az bir bakımcı adlandırır, bir bakımcının alan adı onaylı bir kümeyle eşleşir) katalog YAML’ı yerine IR’ye karşı ifade edilebilir. Böyle bir kural birlikte gelmez; soket, böyle bir kuralın yer alacağı yerdir.

Derleyici, bakımcı içeriğini JSON Schema’nın yapısal biçiminin (name zorunlu; email ve url isteğe bağlı, ikisi de string) ötesinde zorlamaz veya doğrulamaz. Listelenen bakımcıların varlığa gerçekten sahip olup olmadığı, e-postalarına ulaşılıp ulaşılamadığı, bir depo commit’inin içlerinden biri tarafından imzalanıp imzalanmadığı katalog yönetişimi konularıdır ve birlikte gelen hiçbir denetim bunların hiçbirini değerlendirmez. Bunlar derleyiciye değil, bir operatörün eklediği bir yönetişim politikasına aittir.

Zorunlu alan asimetrileri

Aggrega’nın varlık türleri, JSON Schema’larında birbirinden biraz farklı zorunlu alan kümeleri taşır. Asimetrilerin çoğu kasıtlıdır ve varlığın rolünü yansıtır.

Varlık başına zorunlu alanlar (her varlığın tek tip olarak zorunlu tuttuğu apiVersion / kind / metadata.name / metadata.version hariç):

VarlıkEk zorunlu alanlarGerekçe
Componentmetadata.labels.component.aggrega.ai/typeEtiket zorunluluğu seçici eşleştirmesi için yük taşıyıcıdır: usesSchema x-aggrega-selector: ek açıklamaları hedef Components’i bu etikete göre filtreler; etiket yoksa Component yüklenirken reddedilir
Feature—Ayrılmış etiket zorunluluğu yoktur; Features ad + yayıncı ile tanımlanır
Recipespec.capability, spec.implementsYetenek, sağlayıcıya yönlendirmeyi denetler; implements, Component bağlamayı denetler
FeatureRecipespec.capability, spec.implementsRecipe ile aynı
Pluginmetadata.pluginType, spec.abiVersionEklentinin uyguladığı soket türü (adresleme bloğunun parçasıdır ve türetilen plugin/<pluginType>/<name> koordinatının <pluginType> kesimini sağlar) ve hedeflediği ABI sürümü; .wasm konumu yazılmaz, bu kimlikten türetilir; sağlayıcı çıktısı üreten bir eklenti (pluginType: provider) ayrıca çeviri sözleşmesini spec.provider altında taşır
Aggregate—components, subsystems ve aggregates alanlarından hiçbirini bildirmeyen bir Aggregate yüklenir ve derlenir, ancak hiçbir şey işlemez
Manifestspec.mappingsEşleme katmanları, Manifest’in tek amacıdır
Releasespec.aggregate, spec.manifest (extends bildiren bir Release aggregate yazmaz ve manifest alanını atlayabilir); metadata.environmentİlk ikisi derlemeyi belirli bir Aggregate + Manifest’e bağlar; environment, işlenen çıktıya aggrega.ai/environment etiketi olarak damgalanır

Component etiket zorunluluğu yük taşıyıcıdır

component.aggrega.ai/type etiketi, Aggrega’nın herhangi bir varlıkta zorunlu tuttuğu tek etikettir. Bu zorunluluk, standart kütüphanenin usesSchema mekanizmasının hedef adayları "component.aggrega.ai/type=database" gibi seçici dizeleri taşıyan x-aggrega-selector: ek açıklamalarıyla filtrelemesi nedeniyle vardır — seçici, türün soketin kabul ettiği türlerle eşleşip eşleşmediğini belirlemek için hedefin etiketlerine bakar. Component şeması bunu zorunlu kılar: etiketi atlayan bir Component yüklenirken reddedilir (E0215) ve eksik anahtar adlandırılır.

Dolayısıyla bu zorunluluk bir yayımlama yüzeyi meselesi değil (etiket katalogda keşif için değildir), bir topoloji meselesidir: katalog dağıtımını hedeflemeyen iç kullanımlı Components de dahil olmak üzere her Component bu etiketi taşır.

Release metadata.environment alanı zorunludur

Release şeması metadata.environment alanını zorunlu tutar; bu, derlemenin işlenen çıktıya aggrega.ai/environment etiketi olarak damgaladığı bir dizedir.

Diğer asimetriler

Kalan asimetriler (Recipe ile Component zorunlu alanları, Manifest’in mappings zorunluluğu) her varlığın rolünü yansıtır. Her varlık türünde tek tip bir zorunlu alan sözleşmesi isteyen yazarlar bunu bulamaz; asimetriler, role dayalı tasarım gereği kasıtlıdır.

Çapraz başvurular

  • labels-and-annotations.md — yayımlama yüzeyini tamamlayan, içerik tarafındaki meta veri mekanizması.
  • entities/component.md — Component’in metadata.labels.component.aggrega.ai/type gereksinimi ve schema / usesSchema / featuresSchema bildirimleri.
  • entities/release.md — Release’in metadata.environment alanı ve bu alanın zorunluluğu.
  • 10-status.md — meta veri zarfının durumu.
  • architecture/02-ecosystem-philosophy.md — Katı API Bölümlemesi ve Kurumsal Meta Veri Paketi tasarım çerçevesi.
  • architecture/13-catalog-and-registry.md §“Lockfile pinning and artifact immutability” + §“Catalog entity name-shape enforcement” — değişmezlik kuralının yayımlama anında neyi reddettiği ve varlık türüne göre ad biçimlerinin nerede denetlendiği: yayımlama disiplini plugin’i, bir yazar aggrega lint çalıştırdığında bunları tavsiye niteliğinde raporlar; ne derleme ne de yayımlama bunları denetler.
  • architecture/11-governance-and-compliance.md §“Inheritance and publishing discipline” — hangi yönetişim kurallarının yayımlama disiplini plugin’ine ait olduğu ve hangilerinin bunun yerine genişleten bir Component’in kalıtımı tarafından yapısı gereği çözüldüğü.