Docs

Publish semantiği

Özet

  • Publish ve promote (release) iki ayrı operasyondur. Publish, çağıranın test edebileceği değişmez, private bir prerelease build'ini saklar; promote, seçilmiş bir prerelease'i public, sabitlenebilir version'a release eder.
  • Her component build'i iki durumdan geçer: prerelease (çağırana private, yalnızca onun tarafından deploy edilebilir) ve released (public, workspace'in kitlesindeki herkes tarafından deploy edilebilir). Publish birincisini oluşturur; promote onu ikincisine dönüştürür.
  • Bir prerelease, kaynak ağacının değişmez doğrulanmış bir snapshot'ıdır. Build, derlendiğini doğrulamak için platformda çalışır, ortaya çıkan image private olarak saklanır, registry push'u olmaz, katalog tag'leri hareket etmez. Her publish yeni bir prerelease ID basar — platform version'ları yerinde güncellemez.
  • Bir promote, o prerelease'i released kataloğa release eder: image registry'ye gider, component.yml'de deklare edilen tag'ler (latest/default/custom) hareket eder, katalog odaklı alanlar (categories, modalities, neighbors, alternatives) senkronize olur, version durumu çevirir. ID değişmez.
  • İki operasyon farklı soruları yanıtlar. Publish "bu build oluyor mu" sorusunu yanıtlar. Promote "bu version public mi" sorusunu yanıtlar. Onları ayrı tutmak, yalnızca doğrulamayı geçen bir build'i public katalogun dışında tutar.
  • CLI cwd tabanlıdır: ppl component publish ve ppl component promote ikisi de component'i çalışma dizininin component.yml'sinden çözer. promote'ta version-id argümanı yoktur; cwd component'inin en son prerelease'i hedeftir.

Neden iki durum var

Publish ve promote (release) iki ayrı operasyondur. Publish, çağıranın test edebileceği değişmez, private bir prerelease build'ini saklar; promote, seçilmiş bir prerelease'i public, sabitlenebilir version'a release eder. Onları ayrı tutmak, bir şey onu açıkça promote edene kadar bir build'in private kalması anlamına gelir, böylece public tag'i sabitleyen hiç kimse release edilmemiş bir build'e bağlı olmaz.

Publish, bir build'i doğrular ve ortaya çıkan snapshot'ı test için saklar. Build, platformun builder'ında çalışır, image çağırana private olarak saklanır ve artefakt prerelease ID'siyle adreslenebilirdir. Başka kimse görmez. Çağıran onu bir test backend'inde deploy edebilir, bir canlı-fixture döngüsü çalıştırabilir ve davranışını önceki version'la karşılaştırabilir. Bu etkinliklerin hiçbiri çağıranın workspace'i dışında görünmez.

Promote, doğrulanmış prerelease'in release edilmeye hazır olduğu ayrı kararıdır — katalogda public yapılır, latest / default / component'in deklare ettiği her ne ise olarak tag'lenir ve görünürlük kapsamı onu içeren herkes tarafından deploy edilebilir. Released bir version, diğer insanların karşı sabitlediği şeydir.

Bölünme, "bu version bağlanmak için güvenli mi" sorusunu yanıtlanabilir kılar. Sabitlenmiş bir released version hem doğrulamadan (publish) hem de bir insan kararından (promote) geçmiştir. Bir prerelease ID'si yapı gereği private keşiftir: testler için doğru artefakt, üretim için yanlış artefakt.

Publish aslında ne yapar

Publish, component'in kaynak ağacının mevcut durumunu yeni bir version satırına dondurur. CLI, component'in kök dizininden (component.yml ve src/ olan dizinden) çalışır, kaynağı, manifest'i, mevcut tüm Docker stage dosyalarını, assets dizinini ve yeterince küçükse bir LICENSE'ı paketler. O paketi platformun build sistemine gönderir, build remote çalışır ve başarıda platform prerelease durumunda taze bir ID ile yeni bir version kaydeder.

ppl component publishppl component publish -m "describe the change"ppl component publish --dry-run    # hiçbir şey yazmadan doğrula

--dry-run, aynı paketlemeyi ve remote build'i çalıştırır ve başarı raporlar ama remote component oluşturmaz, herhangi bir yerel link'i kalıcılaştırmaz, bir version kaydetmez veya registry'ye bir şey push etmez. src/'i düzenlerken hızlı iterasyon için döngüdür — --dry-run geçtiğinde, platform tarafı build kaynakla uyuşur.

Lookup-or-create davranışı, ilk publish'i ve sonraki her publish'i öngörülebilir davranır kılan şeydir. Çalışma dizini mevcut bir component'e verlinkliyse, publish o component'e karşı yeni bir prerelease yazar. Değilse, component'i ada göre arar (component.yml'den gelen name:); tek bir eşleşme ona link kurar; sıfır eşleşme, yeni bir remote component oluşturmak için açık -y / --yes onayı gerektirir. Link kurmak yıkıcı değildir ve mevcut bir remote'u benimsemek onay gerektirmez; yeni bir remote oluşturmak gerektirir, çünkü onay bayrağı yeni bir nesne üreten tek eylemi kapılar.

Publish'in yapmadığı şey de aynı derecede yük taşır. Public bir registry'ye push etmez; image private kalır. Mevcut bir version'ı yerinde güncellemez; kaynak byte'lar aynı olsa bile her publish yeni bir ID'dir. Yeniden deploy etmez; backend'ler hâlâ oluşturuldukları version'a sabitlenir ve yeni kodun çalışması için bir vertex'in daha yeni bir version'a bump'lanması ve backend'in yeniden deploy edilmesi gerekir.

Promote aslında ne yapar

Promote, belirli bir prerelease'i (cwd component'ine ait olanı) alır ve üzerinde release adımlarını çalıştırır: image'i kaydedilmiş kaynaktan yeniden inşa eder (böylece registry image'i, publish anındaki çağıranın yerel docker cache'inden değil, kaydedilen kaynak paketinden yeniden üretilebilir), onu platform registry'sine push eder, component.yml'de deklare edilen tag'leri uygular (latest, default veya manifest'in adlandırdığı her ne ise), katalog odaklı alanları (categories, modalities, neighbors.upstream, neighbors.downstream, alternatives) senkronize eder ve version'ın durumunu released'a çevirir. ID değişmez; prerelease olan version artık released'tır.

cd <component-root>ppl component promote

version_id argümanı yoktur çünkü cwd component'inin prerelease'i hedeftir. Tag'ler ve katalog alanları promote anında component.yml'den alınır — ayrı bir "update tags" fiili yoktur ve platform bir prerelease'e karşı tag yazımlarını reddeder, çünkü tag'ler public sözleşmedir ve bir prerelease'in public sözleşmesi yoktur. Promote çalışana kadar, latest ve default tag'leri hâlâ daha önce yayınlanmış version'a işaret eder, böylece yeni bir build public'in çözdüğü şeyi değiştirmez.

Promote etmeden önce mevcut version'ları kontrol edin (ppl component versions <component_id> onları en eski önce listeler, her version'ın release durumu ve tag'leriyle). promote, cwd component'inin tek prerelease'ini çözer ve release eder; component.yml'de deklare edilen tag'ler latest ve default'ın nereye konacağına karar verir. Bir component'in herhangi bir anda en fazla bir prerelease'i vardır, bu yüzden promote'un hangi version üzerinde davrandığı konusunda asla bir belirsizlik yoktur.

cwd disiplini

Hem publish hem de promote, hedef component'i çalışma dizininden çözer. CLI, mevcut dizinden yukarı doğru yürüyerek verlinkli bir component.yml arar; bulunan ilki üzerinde operasyon yapılan component'tir. Komutların hiçbiri version-id argümanı almaz — cwd argümandır. Yanlış dizinden publish çalıştırmak yanlış component'i yayınlar; yanlış dizinden promote çalıştırmak yanlış prerelease'i promote eder.

Çalışma dizininden çözmek, hedefi ayrıca sağlanan bir tanımlayıcıya değil, diskteki kaynak ağacına bağlı tutar. Çağıranın içinde durduğu dizin, üzerinde operasyon yapılan component'tir.

Publish, promote ve deploy nasıl birleşir

Üç fiil, release döngüsüne birleşen bağımsız operasyonlardır:

  • Publish, çağıran tarafından deploy edilebilir bir prerelease basar. Bir sonraki adım genellikle prerelease üzerinde bir canlı backend testidir (Canlı bir backend ile test etme bölümüne bakın).
  • Promote, prerelease'i kataloğa release eder. Promote edilmiş version'lar katalogda sabitlenmeye hazır olarak durur.
  • Deploy, bir backend'i bir runtime üzerinde çalıştırır. Backend'ler belirli version ID'lerine sabitlenir; bir prerelease'i promote etmek deploy edilmiş hiçbir backend'in sabitlenmiş version'ını değiştirmez. Bir backend'i ileri almak için, vertex'in version'ını değiştirin (ppl backend change-version) ve yeniden deploy edin.

Üçü farklı yüzeylerde operasyon yapar. Publish yalnızca private prerelease'ler üretir. Promote yalnızca kataloğu değiştirir; çalışan hiçbir deployment hareket etmez. Deploy runtime'a dokunur ama kataloğa dokunmaz. Yüzeyler farklı olduğundan, her adım diğerlerini koordine etmeden çalışır.

Bunun yeri

Publish semantiği, diğer her release ile ilgili kararın dayandığı sözleşmedir. Test döngüleri prerelease'lerin değişmez olmasına bağlıdır, böylece bir prerelease ID'sine karşı bir kanıt geçerli kalır. Promote, doğrulanmış prerelease'in registry'nin sunduğu şeyin tam olarak kendisi olmasına bağlıdır. Deployment'lar sabitlenmiş version'ların altlarında değişmemesine bağlıdır. Bu garantilerin hepsi aynı kuraldan kaynaklanır: publish basar, promote release eder, deploy sabitler ve publish'ten sonra hiçbir şey mutasyona uğramaz.

Model bir yerine iki fiil kullanır. Karşılığında, released bir version her zaman doğrulamadan ve bir insan promote kararından geçmiş tek bir kaydedilmiş build'e karşılık gelir ve sabitlenmiş bir version, sabitlendiği build olarak kalır.

İlgili

Bu sayfa yardımcı oldu mu?