PrijavaZakažite brifing

Poglavlje 2.28

Objavljivanje vašeg proširenja

Kako plugin ili paket stiže od uspešne izgradnje do jedinica koje ga pokreću i kako se ponovo uklanja. Verzije, pregled izdanja, kanali i instalacije, potpisivanje, odobrenja izmena, zapis o identitetu isporuke, migracije, vraćanje na prethodno stanje i povlačenje verzije.

Ovu stranicu je sa engleskog originala prevela AI tehnologija. Ako nešto nije jasno, merodavna je stranica na engleskom. Pročitajte ovu stranicu na engleskom

18 min čitanja

Cold chain 0.4.0 bilo je naše prvo izdanje koje je tražilo više od prethodnog. Dodalo je slanje pošte i jednu spoljnu adresu, za upozorenja o rashladnim kontejnerima. Build je bio zelen, testovi su prošli na sve tri sintetičke grane, a izdanje je ipak dva dana stajalo u razvojnom prostoru dok su dvoje ljudi čitali šta traži, a treći odobravao adresu. Tako izdavanje na platformi Nexus i treba da izgleda: kod je lakši deo, a dokazi i odobrenja čine samo izdanje.

Ovo poglavlje obuhvata sve između zelenog builda i verzije koja radi za svaku jedinicu, kao i načine povratka. Sam put promocije, od razvojnog prostora preko stejdžinga i pilot-jedinice do svih jedinica, predstavljen je u poglavlju 2.24, Izgradnja prilagođene vertikale od početka do kraja, i ovde neću ponavljati njegove kapije. Sve to uokviruje jedno pravilo. Postavljanje se vrši isključivo kroz kanale izdanja instalacije. Ne postoje sporedna vrata za hitnu ispravku i niko ne menja pokrenutu sliku ručno.

Verzije

U izdanju paketa menjaju se tri broja verzije i isplati se da ih jasno razlikujete.

Šta Gde se nalazi Primer Pravilo
Plugin version u nexus.manifest.json 0.4.0 Semantička verzija; dozvoljen je sufiks pre-izdanja, kao što je -rc.1
Paket version u pack.json 0.4.0 Menja se zajedno sa sočivima, rečima i klasterima paketa
Model znanja Sopstvena verzija modela 1.3 na 1.4 Menja se isključivo kroz zahtev za izmenu grafa

Razvojni build nosi sufiks, 0.4.0-dev, dok ne stigne u stejdžing. Neka verzije plugina i paketa budu jednake kada se isporučuju zajedno; tako se na svakom pregledu izdanja izbegava rasprava o tome kom broju dokazi pripadaju.

Dve druge verzije su fiksirane, a ne birane. Verzija šablona paketa (domain-pack@1.6.0 za Cold chain) određuje se pri pravljenju paketa i menja se samo kao pregledana izmena. SDK (komplet za razvoj softvera) instalira se u tačno određenoj verziji, nikada u opsegu, kako bi isti build dao isti rezultat i sledećeg meseca:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

I veštine u Skills Engine imaju verzije, ali se ponašaju drugačije. Svaka objavljena verzija je nepromenljiva, a live, canary i shadow su oznake na verzijama. Vraćanje unazad pomera oznaku, a izvršavanja koja su već u toku završavaju se na verziji na kojoj su započela.

Pre nego što zatražite pregled: manifest

Stranica Manifest i dozvole poredi ono što ovo izdanje deklariše sa poslednjim izdanjem: opsege, skladišta, odlazne adrese i profil sandboxa. Pročitajte je pre nego što ikoga zamolite za pregled, jer vam tačno pokazuje šta će recenzenti morati da prihvate.

Manifest i dozvole
Manifest i dozvole
Šta Cold chain 0.4.0 deklariše u odnosu na 0.3.2. Obratite pažnju na dva reda označena kao proširenje, slanje pošte i jednu spoljnu adresu, kao i na pločicu koja kaže da izdanje neće preći razvojni prostor dok ih dva recenzenta ne prihvate.

Izdanje koje traži više nego što je njegov manifest ranije deklarisao zadržava se gde jeste, uz MANIFEST_SCOPE_WIDENED, dok dva recenzenta ne prihvate prošireni manifest. Spoljna adresa zahteva i odobrenje osobe koja je kod klijenta zadužena za spoljne adrese; to odobrenje se daje na određeni rok, a naše je važilo 12 meseci. Imate dva puta: uklonite te redove ili zatražite pregled. Stranica nudi oba dugmeta.

Svaki red na toj stranici primenjuje se tokom izvršavanja, a ne samo pri pregledu. Svaki poziv alata proverava se u odnosu na deklarisane opsege, spoljna adresa je blokirana ako nije navedena, a profil sandboxa ne dozvoljava nikakvu drugu mrežu. Plugin koji pokuša da pristupi nečemu što nije deklarisao biva odbijen, a jedino rešenje je novo izdanje koje to deklariše.

Pregled pre objavljivanja

Stranica Pregled izdanja objedinjuje dokaze za jedno izdanje u jednoj tabeli, za recenzenta koji nije autor.

Pregled izdanja
Pregled pre objavljivanja
Prikaz drugog recenzenta za Cold chain 0.4.0, sa tabelom dokaza, razlikom opsega i komentarima. Obratite pažnju na pločicu desno: autor ne može da odobri sopstveno izdanje.
Dokaz Šta je pokazao za 0.4.0
Testovi 66 od 66, na tri sintetičke grane
Provere kvaliteta Dokumentacija i kod se slažu
Politika Svako sočivo samo sužava; lična polja su podrazumevano isključena
Potpisi Sliku i paket potpisao je pipeline
Razlika opsega Dodaje slanje pošte i jednu spoljnu adresu, uz njeno odobrenje
Kompatibilnost Verzija platforme i verzija osnovnog paketa na kojima je testirano
Izmena modela Probno izvršavanje zahteva za izmenu grafa: 1.284 veza preimenovano, ništa uklonjeno

Ispod tabele nalaze se komentari na izmenu i poreklo: koji pipeline ju je izgradio, iz koje izmene, digest slike i šablon. Recenzenti odobravaju svojim passkey ključem. Odobravaju dva recenzenta koji nisu autori, a pipeline zatim prebacuje izdanje u stejdžing. Autor se nikada ne računa kao recenzent, a pokušaj se odbija sa NEEDS_SECOND_PERSON. Zahtev za pregled ističe nakon 3 dana.

Na pitanja recenzenata odgovarajte u komentarima, a ne u prozoru za ćaskanje. Tokom našeg pregleda, naš službenik za usklađenost pitao je zašto je iznos odštetnog zahteva klasifikovan kao komercijalni podatak, a drugi recenzent je zatražio plan vraćanja za izmenu modela. Oba odgovora sada su deo zapisa izdanja, a tamo će sledeći recenzent i gledati.

Odobrenja politike izmena

Pregled izdanja obuhvata izdanje u celini. Blok changePolicy u manifestu ide dalje: navodi koje klase izmena na komponentama vašeg plugina zahtevaju odobrenje i od koliko ljudi.

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Tri klase su website (veb-aplikacija), bff (backend za frontend) i migration (migracija baze podataka). Svaka klasa navedena u classes mora imati sopstveni broj u approvals, od 1 do 10. Klasa koju izostavite nije regulisana, a šema vas tera da to napišete kao izbor, a ne da do toga dođete propustom. Za migracije tražimo dva odobrenja jer je migracija jedina izmena koju je teško povući.

Odobrenja se broje po različitim osobama, a predlagač se nikada ne računa. Pravila na kojima to počiva vredi poznavati, jer svako ima svoje odbijanje:

  • Odobrenje osobe koja je predložila izmenu odbija se sa TRUST_APPROVAL_SELF_APPROVAL.
  • Osoba koja uopšte ne sme da vrši izmene te klase odbija se sa CHANGE_CLASS_NOT_PERMITTED.
  • Kada je bilo koji commit u izmeni potpisan identitetom agenta organizacije, kvorum je uobičajeni minimum plus jedan, a glas samog agenta se ne računa.
  • Svako odobrenje beleži razliku i head koji je video. Ako se izmena promeni nakon poslednjeg odobrenja, spajanje se odbija sa HASH_MISMATCH, a odobrenja se moraju ponovo prikupiti za novi sadržaj.

To treće pravilo je važno ako razvijate pomoću AI (veštačka inteligencija) alata za kodiranje, kako opisuje poglavlje 2.26, Razvoj pomoću AI alata za kodiranje. Rad koji je napisao agent zahteva jedno ljudsko odobrenje više od rada koji je napisao čovek. Planirajte to.

Potpisivanje i verifikacija

Svaku sliku i paket potpisuje pipeline koji ih je izgradio, a potpisana slika je jedna od kapija za ulazak u stejdžing. Razvojni prostor od početka pokreće samo potpisane slike. Na Enterprise izdanju administrator za svaki namespace podešava da li se nepotpisane slike beleže ili odbijaju, i prebacuje namespace-ove na odbijanje jedan po jedan, tako da produkcija na kraju pokreće samo slike koje je pipeline izgradio i potpisao. Potpisivanje je deo builda, a ne nešto što se dodaje pre izdanja.

Pravilo koje se provlači kroz sve ovo jeste da je neuspeli potpis odbijanje, nikada upozorenje. Provera koja dobije SIG_INVALID se zaustavlja. Ne vraća se na nepotpisanu verziju i ne nastavlja uz napomenu u logu, jer je upozorenje u build logu prolaz za svakoga ko ga nije pročitao.

Isto pravilo važi za sve što predajete na medijima. Zapečaćeni paket za klijenta bez mrežne veze proverava se vašim javnim ključem pre nego što se bilo šta raspakuje, a poglavlje 2.25, Razvoj za svako izdanje, prikazuje komandu.

Identitet isporuke

Plugin se isporučuje kroz više stvari od kojih svaka ima ime: njegove repozitorijume, ključ za potpisivanje, namespace za postavljanje, prefiks registra, šemu baze podataka, skup domena i politiku izmena. Svaka od njih je mesto gde bi se dva plugina mogla sudariti ili gde bi jedan plugin mogao da odstupi. Identitet isporuke je jedan potpisani zapis po pluginu koji sadrži sve to, tako da svaka provera na putu izdanja čita isti odgovor i odbija u slučaju neslaganja.

Svoj deo doprinosite kroz manifest i ništa drugo: schema, db, domains, changePolicy i URL repozitorijuma. Platforma dopunjuje zapis ostatkom i potpisuje ga. Nikada sami ne imenujete svoj namespace, prefiks registra ili ključ za potpisivanje. Oni vam se dodeljuju, a manifest koji bi pokušao da ih deklariše iznosio bi tvrdnju u koju bi provere zatim morale da posumnjaju.

Potpisani zapis sadrži jedanaest polja: slug plugina, organizaciju vlasnika, organizaciju koja ga gradi, njegove repozitorijume, naziv ključa za potpisivanje, namespace za postavljanje, prefiks registra, šemu baze podataka, domene, politiku izmena i kratku listu starijih naziva slika koje je koristio pre nego što je dobio prefiks registra. Ta poslednja lista može samo da se smanjuje. Pošto je potpisana, novi potpis može da ukloni stavku, a ništa ne može tiho da je doda. Potpis je Ed25519 nad standardnim kanonskim JSON oblikom tih jedanaest polja, tako da se zapis sa „Tomás” ili „Sinéad” u sebi svuda verifikuje isto.

Kada izdanje ne odgovara svom zapisu, važi prvo odbijanje:

Kod Kada HTTP
DELIVERY_IDENTITY_MISSING Za plugin ne postoji zapis 403
DELIVERY_PATH_REFUSED Slanje slike izvan prefiksa registra koje nije na potpisanoj listi starijih naziva 403
NAMESPACE_MISMATCH Postavljanje koje cilja drugi namespace 403
IMAGE_NAME_COLLISION Naziv slike koji već prisvaja drugi plugin 409
CHANGE_CLASS_NOT_PERMITTED Klasa izmena koju politika ne reguliše 403

IMAGE_NAME_COLLISION je ono koje iznenađuje ljude. Izaberite drugi naziv i nikada ga ne koristite ponovo: zajednički naziv slike znači da promocija jednog plugina može da pomeri podove drugog plugina.

Migracije, potvrđene i ograničenog opsega

Migracija se isporučuje unutar slike vašeg plugina i izvršava se pre pokretanja nove verzije, kroz jedini pokretač migracija u SDK-u, nexus-migrate. Ne pišete sopstveni mehanizam za primenu. Pre nego što se bilo koje izdanje pomeri, isti pokretač primenjuje vaše migracije fajl po fajl na privremenu bazu podataka, tako da migracija koja ne uspe, ne uspe tamo. Shadow build šablona poziva pokretač jednom po fajlu, redom, i beleži svaki fajl onako kako će to činiti produkcija.

Pravila pokretača su ista ona koja proveravaju kapije, napisana kao kod:

  1. Povezuje se kao migratorska uloga vaše šeme i izvršava svaki fajl kao vlasnik šeme. Svaka druga prijava, pre svega superuser, odbija se. Fajl koji sam pokuša da promeni ulogu odbija se pre nego što se bilo šta izvrši.
  2. Fajl za tenancy, sa brojem 0, nikada se ne menja nakon primene. Izmena tenancy-ja dobija sopstveni fajl revizije, 000_tenancy_r<N>.sql, koji za vas piše nexus-tenancy render --revision <N>.
  3. Obično pokretač upravlja transakcijom svakog fajla i odbija BEGIN ili COMMIT unutar nje. Fajl koji sam upravlja svojim transakcijama deklariše da se izvršava po naredbi, i tada svaki BEGIN koji otvori mora imati par.
  4. Vodi evidenciju, jedan red po fajlu, sa SHA-256 fajla i načinom na koji je izvršen. Primenjeni fajl se nikada ne menja na licu mesta; izmena je novi numerisani fajl.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Ograničeno na opseg znači da svaka nova tabela sadrži organization_id, owner_user_id i business_unit_id, kao i kolonu-oznaku is_demo osim ako gates/demo-exempt.json izuzme tabelu uz obrazloženje, sa primarnim ključem koji počinje organizacijom i stranim ključevima koji je prenose, i sa prinudno uključenom bezbednošću na nivou redova. Kapija migrations-are-scoped proverava ta pravila u svakom fajlu, a migrations-commit-what-they-open proverava da svaki fajl potvrđuje ono što otvori. Druga kapija postoji jer je migracija koja se jednom tiho vratila unazad završila sa izlaznim kodom 0, a tabela koju je trebalo da napravi nikada nije postojala.

Svakom izdanju pripada još jedan fajl. scripts/ci/required-env ispisuje promenljive okruženja potrebne vašem servisu za pokretanje, kao JSON niz preuzet iz vašeg učitavača konfiguracije. Put izdanja ga pokreće i odbija izdanje čije postavljanje ne podešava svaku od njih, tako da se promenljiva koja nedostaje otkrije pre izdanja, a ne preko poda koji neće da se pokrene.

node scripts/ci/required-env

Objavljivanje veština

Dve vrste veština do ljudi stižu različitim putevima, pa ih izdajte na različite načine.

Veština iz manifesta, tipizovani red u skills[] vašeg plugina, isporučuje se sa pluginom i prolazi kroz istu promociju kao i ostatak plugina. Uvođenje pri svakom izdanju sinhronizuje ceo skup veština sa registrom. Ako izostavite veštinu iz skupa, ona se onemogućava, a na Enterprise izdanju sinhronizacija sa jednom neispravnom veštinom ne prihvata nijednu, tako da nastavlja da radi prethodna verzija umesto polovine nove.

Veština iz Skills Engine objavljuje se iz biblioteke. Na Enterprise planu, veština koja dodaje alat za upis čeka da je odobre dve imenovane osobe svojim pristupnim ključevima (passkey), a predlagač ne može biti jedna od njih. Odobrena verzija se zatim izvršava u senci (shadow), zatim kao canary za jednu jedinicu iza imenovanih kapija, zatim za sve, i sama se zaustavlja ako neka kapija nije ispunjena. Ako vaš dodatak i veština iz Skills Engine zavise jedno od drugog, prvo objavite veštinu i sačekajte da stigne do svih pre nego što izdanje dodatka koje je poziva izađe iz pilot faze.

Kanali i instalacije

Kada izdanje prođe pilot fazu i stigne do svih jedinica, nudi se na kanalu, a svaka jedinica bira svoj kanal. Njen administrator odobrava svaki prelazak. Stranica Kanali i instalacije prikazuje koje jedinice koriste koju verziju, uz stope grešaka isključivo kao brojeve: vidite kako se vaše proširenje ponaša, a nikada šta je iko s njim radio.

Kanali i instalacije
Kanali i instalacije
Koje jedinice koriste koju verziju dodatka carrier-sync, uz otvoren vraćanje na prethodnu verziju za jednu jedinicu. Obratite pažnju na to šta modalni prozor navodi da se menja, šta ostaje i da je potrebna druga osoba, administrator same jedinice.

Naš dodatak carrier-sync istovremeno radi u tri verzije, i to je normalno. Većina jedinica koristi aktuelno izdanje, jedna jedinica ostaje na starijoj verziji na kanalu koji se održava do navedenog datuma, a kandidat za izdanje nalazi se na kanalu koji još niko nije izabrao. Ne opirite se tome; jedinica kojoj je potrebna stabilnost zbog revizije ima pravo na nju.

Dnevnici rada i metrike vašeg proširenja

Stranica sa logovima i metrikama vašeg paketa ograničena je na vaša sopstvena radna opterećenja, u jedinicama u koje smete da gledate. Možete filtrirati po jedinici i okruženju, a vidite brojeve, vremena i stanja.

Logovi i metrike vašeg paketa
Logovi i metrike vašeg paketa
Sopstveni logovi i metrike paketa Cold chain, filtrirani na pilot u Roterdamu. Pogledajte redove loga: osoba koja je prijavila odstupanje je skrivena, a tekst napomene uz reklamaciju se uopšte ne beleži u log.

Lična polja se zamenjuju pre nego što se red upiše, a sadržaj korisnika, kao što su tekst reklamacije, pošta ili sadržaj dokumenata, nikada se ne upisuje u logove. Logovi se čuvaju 14 dana. Organizaciju postavlja gateway, a nikada vaš upit, pa se upit koji navodi drugu organizaciju odbija sa TENANT_BOUNDARY. Asistent u panelu može zajedno sa vama da čita iste logove, i samo njih: kada sam ga pitao zašto su zapisi o odstupanjima jednog jutra stigli sa zakašnjenjem, pronašao je da 18 minuta ponovnih pokušaja potiče od dupliranih očitavanja sa napajanja jednog keja.

Vraćanje na prethodnu verziju

Postoje dve vrste vraćanja na prethodnu verziju, i obe su pregledane izmene, a ne prekidači.

Vraćanje okruženja koristi prethodnu verziju. Svako okruženje je čuva 30 dana. Vraćanje se priprema kao izmena izdanja, prikazuje pregled onoga što će uraditi i zahteva drugu osobu; nakon odobrenja, pipeline vraća verziju za otprilike jedan minut. Svako vraćanje se meri, kao i svaka vežba, pa ga uvežbajte pre nego što vam zatreba. Vraćanje jedne jedinice koristi stranicu Kanali i instalacije. Modalni prozor za vraćanje navodi šta se menja (ta jedinica ponovo koristi stariju verziju, a njena stopa grešaka se prati sat vremena), šta ostaje (ostale jedinice, kao i podešavanja i zapisi te jedinice), razlog i ko je druga osoba: administrator te jedinice.

Podešavanja i zapisi se zadržavaju pri vraćanju, pa svako izdanje planirajte uz pretpostavku da prethodna verzija može ponovo da radi nad podacima koje je novija upisala. To je praktični razlog da migracije u okviru izdanja koje biste mogli da vratite budu isključivo aditivne, i razlog zbog kog tražimo da svaku odobre dve osobe. Isto važi i za izmenu modela: recenzent može, i treba, da zatraži plan vraćanja za zahtev za izmenu grafa pre nego što ga odobri.

Veštine se vraćaju blaže. Vraćanje oznake live na raniju verziju je jedan korak, a izvršavanja koja su već u toku završavaju se na verziji sa kojom su započela.

Povlačenje verzije iz upotrebe

Izdanje se, kada je jednom napravljeno, nikada ne menja. Verzija koja više ne treba da se koristi povlači se, a ispravka se isporučuje kao novi broj verzije. Kanali izdanja samog SDK-a slede istu praksu: loša verzija SDK-a se povlači (yank), a nikada se ne zamenjuje drugačijim sadržajem pod istim brojem. Preuzmite ovu praksu, jer broj verzije koji može da označava dve različite verzije builda čini bezvrednim svaki dokaz o njoj.

Povlačenje dodatka ili paketa zaustavlja nove instalacije. Jedinice zadržavaju verziju koju koriste dok ne pređu na drugu, pa je povlačenje signal i rok, a ne isključivanje. Obavestite administratore jedinica na koju verziju treba da pređu i do kada.

Penzionisanje veštine prati istu ideju, uz jedan korak više. Skills Engine prebacuje sve preostale pozivaoce na zamenu nakon izvršavanja test slučajeva zamene, zaustavlja nova izvršavanja i zadržava verzije, test slučajeve i zapečaćene zapise o izvršavanjima, kako bi veština mogla da se vrati ako se zamena pokaže kao pogrešna.

Kontrolna lista za objavljivanje

Ovo je lista koju pročitamo pre svakog izdanja paketa Cold chain. Kratka je jer platforma većinu stavki proverava umesto nas.

  1. Verzije se poklapaju: manifest, pack.json i model znanja, ako je izmenjen.
  2. Svaka kapija je zelena lokalno, od čistog stanja, a za svaki novi test je pokazano da najpre ne prolazi.
  3. Stranica Manifest i dozvole ne prikazuje proširenje, ili je proširenje upravo ono što smo nameravali i recenzenti znaju zašto.
  4. Svaka migracija je nova numerisana datoteka, ograničenog opsega, i čisto primenjena na privremenu bazu podataka.
  5. scripts/ci/required-env navodi svaku promenljivu koja je servisu potrebna, a deployment postavlja svaku od njih.
  6. Plan vraćanja je napisan u izmeni, uključujući i svaku izmenu modela.
  7. Dva recenzenta koji nisu autori dostupna su ove nedelje.

Poslednja stavka zvuči trivijalno. Upravo je ona odložila više naših izdanja nego sve kapije zajedno.