Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.28
Izdavanje vašeg proširenja
Kako dodatak ili paket prelazi put od uspješne izrade do jedinica koje ga izvršavaju, i kako se ponovno povlači. Verzije, pregled izdanja, kanali i instalacije, potpisivanje, odobrenja promjena, zapis o identitetu isporuke, migracije, vraćanje na prethodno stanje i umirovljenje verzije.
Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

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 vanjsku adresu, za upozorenja o rashladnim kontejnerima. Izgradnja je bila zelena, testovi su prošli na sve tri sintetičke grane, a izdanje je ipak stajalo u razvojnom prostoru dva dana dok su dvije osobe čitale što traži, a treća odobravala adresu. Upravo se tako izdavanje na Nexusu i treba osjećati: kod je lakši dio, a dokazi i odobrenja čine izdanje.
Ovo poglavlje obuhvaća sve između zelene izgradnje i verzije koja radi za svaku jedinicu, kao i načine povratka. Sam put promocije, od razvojnog prostora preko testnog okruženja i pilot-jedinice do svih jedinica, predstavljen je u poglavlju 2.24, Izgradnja prilagođene vertikale od početka do kraja, i ovdje neću ponavljati njegove kontrolne točke. Jedno pravilo uokviruje sve. Implementacija se provodi isključivo kroz kanale izdanja instalacije. Ne postoje sporedna vrata za hitan popravak i nitko ne uređuje pokrenutu sliku ručno.
Verzije
U izdanju paketa mijenjaju se tri broja verzije i isplati se držati ih odvojenima u glavi.
| Što | Gdje se nalazi | Primjer | Pravilo |
|---|---|---|---|
| Dodatak | version u nexus.manifest.json |
0.4.0 |
Semantička verzija; dopušten je sufiks predizdanja poput -rc.1 |
| Paket | version u pack.json |
0.4.0 |
Mijenja se s lećama, riječima i klasterima paketa |
| Model znanja | Vlastita verzija modela | 1.3 na 1.4 |
Mijenja se samo putem zahtjeva za promjenu grafa |
Razvojna izgradnja nosi sufiks, 0.4.0-dev, dok ne stigne u testno okruženje. Neka verzije dodatka i paketa budu jednake kada se isporučuju zajedno; to štedi raspravu na svakom pregledu izdanja o tome kojem broju pripadaju dokazi.
Dvije druge verzije su fiksirane, a ne birane. Verzija predloška paketa (domain-pack@1.6.0 za Cold chain) određuje se pri izradi paketa i mijenja se samo kao pregledana promjena. SDK (komplet za razvoj softvera) instalira se u točno određenoj verziji, nikada u rasponu, tako da ista izgradnja daje isti rezultat i sljedeći mjesec:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0I vještine u Skills Engineu imaju verzije, ali se ponašaju drukčije. Svaka objavljena verzija je fiksna, a live, canary i shadow oznake su na verzijama. Vraćanje premješta oznaku, a izvođenja koja su već u tijeku završavaju na verziji s kojom su započela.
Prije nego što zatražite pregled: manifest
Stranica Manifest i dopuštenja uspoređuje ono što ovo izdanje deklarira s prethodnim izdanjem: njegove opsege, pohrane, odlazne adrese i profil sandboxa. Pročitajte je prije nego što ikoga zamolite za pregled, jer vam točno govori što će se od recenzenata tražiti da prihvate.
Izdanje koje traži više nego što je njegov manifest prethodno deklarirao zadržava se gdje jest, uz MANIFEST_SCOPE_WIDENED, dok dva recenzenta ne prihvate prošireni manifest. Vanjska adresa također zahtijeva odobrenje osobe koja kod korisnika odgovara za vanjske adrese; to se odobrenje daje na određeno razdoblje, a naše je bilo na 12 mjeseci. Imate dvije mogućnosti: ukloniti retke ili zatražiti pregled. Stranica nudi oba gumba.
Svaki redak na toj stranici provodi se tijekom izvođenja, a ne samo pregledava. Svaki poziv alata provjerava se prema deklariranim opsezima, vanjska adresa je blokirana ako nije navedena, a profil sandboxa ne dopušta nikakvu drugu mrežu. Dodatak koji pokuša dosegnuti nešto što nije deklarirao bit će odbijen, a jedini je popravak novo izdanje koje to deklarira.
Pregled izdanja
Stranica Pregled izdanja okuplja dokaze za jedno izdanje u jednoj tablici, za recenzenta koji nije autor.
| Dokazi | Što je pokazalo za 0.4.0 |
|---|---|
| Testovi | 66 od 66, na tri sintetičke grane |
| Provjere kvalitete | Dokumentacija i kod se podudaraju |
| Pravilo | Svaka leća samo sužava; osobna polja zadano su isključena |
| Potpisi | Slika i paket potpisani su od strane cjevovoda |
| Razlika opsega | Dodaje slanje pošte i jednu vanjsku adresu, s pripadajućim odobrenjem |
| Kompatibilnost | Verzija platforme i verzija osnovnog paketa s kojima je testirano |
| Promjena modela | Probno izvođenje zahtjeva za promjenu grafa: 1.284 veze preimenovane, ništa uklonjeno |
Ispod tablice nalaze se komentari o promjeni i podrijetlo: koji ju je cjevovod izgradio, iz koje promjene, sažetak slike i predložak. Recenzenti odobravaju svojim pristupnim ključem. Odobravaju dva recenzenta koji nisu autor, a cjevovod zatim premješta izdanje u testno okruženje. Autor se nikada ne računa kao recenzent, a pokušaj se odbija s NEEDS_SECOND_PERSON. Zahtjev za pregled istječe nakon 3 dana.
Na pitanja recenzenata odgovarajte u komentarima, a ne u prozoru za razgovor. Tijekom našeg pregleda naša je službenica za usklađenost pitala zašto je iznos potraživanja razvrstan kao komercijalan, a drugi je recenzent zatražio plan vraćanja za promjenu modela. Oba odgovora sada su dio zapisa izdanja, gdje će sljedeći recenzent i gledati.
Odobrenja politike promjena
Pregled izdanja obuhvaća izdanje u cjelini. Blok changePolicy u manifestu ide dalje: navodi koje klase promjena implementabilnih komponenti vašeg dodatka zahtijevaju odobrenje i od koliko osoba.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Tri su klase website (web-aplikacija), bff (pozadinski sustav za sučelje) i migration (migracija baze podataka). Svaka klasa navedena u classes mora imati vlastiti broj u approvals, od 1 do 10. Klasa koju izostavite nije regulirana, a shema vas tjera da to zapišete kao izbor umjesto da do toga dođe propustom. Za migracije tražimo dva odobrenja jer je migracija jedina promjena koju je teško poništiti.
Odobrenja se broje po različitim osobama, a predlagatelj nikada nije jedna od njih. Pravila koja to podupiru vrijedi poznavati jer svako ima svoje odbijanje:
- Odobrenje osobe koja je predložila promjenu odbija se s
TRUST_APPROVAL_SELF_APPROVAL. - Osoba koja uopće ne smije izvršiti promjenu te klase odbija se s
CHANGE_CLASS_NOT_PERMITTED. - Kada je bilo koji commit u promjeni potpisan agentskim identitetom organizacije, kvorum je uobičajeni minimum plus jedan, a vlastiti glas agenta se ne računa.
- Svako odobrenje bilježi razliku i vrh koji je vidjelo. Ako se promjena pomakne nakon posljednjeg odobrenja, spajanje se odbija s
HASH_MISMATCH, a odobrenja se moraju ponovno prikupiti za novi sadržaj.
To treće pravilo važno je ako gradite s alatom za programiranje s AI-jem (umjetnom inteligencijom), kako opisuje poglavlje 2.26, Izgradnja s alatima za programiranje s AI-jem. Rad koji je napisao agent treba jedno ljudsko odobrenje više od rada koji je napisala osoba. Planirajte to.
Potpisivanje i provjera
Svaku sliku i paket potpisuje cjevovod koji ih je izgradio, a potpisana slika jedna je od kontrolnih točaka za ulazak u testno okruženje. Razvojni prostor od početka pokreće samo potpisane slike. U izdanju Enterprise administrator za svaki imenski prostor postavlja hoće li bilježiti ili odbijati nepotpisane slike te imenske prostore jedan po jedan prebacuje na odbijanje, tako da produkcija na kraju pokreće samo slike koje je cjevovod izgradio i potpisao. Potpisivanje je dio izgradnje, a ne nešto što dodajete prije izdanja.
Pravilo koje se provlači kroz sve to jest da je neuspjeli potpis odbijanje, nikada upozorenje. Provjera koja primi SIG_INVALID zaustavlja se. Ne vraća se na nepotpisanu verziju niti nastavlja s bilješkom u zapisniku, jer je upozorenje u zapisniku izgradnje prolaz za svakoga tko ga nije pročitao.
Isto pravilo vrijedi za sve što predajete na mediju. Zapečaćeni paket za korisnika bez mrežne veze provjerava se prema vašem javnom ključu prije nego što se išta raspakira, a poglavlje 2.25, Izgradnja za svako izdanje, prikazuje naredbu.
Identitet isporuke
Dodatak se isporučuje kroz nekoliko stvari od kojih svaka ima ime: njegove repozitorije, ključ za potpisivanje, imenski prostor za implementaciju, prefiks registra, shemu baze podataka, skup domena i pravila o promjenama. Svaka od njih mjesto je na kojem bi se dva dodatka mogla sukobiti ili bi jedan dodatak mogao odstupiti. Identitet isporuke jedan je potpisani zapis po dodatku koji ih sve sadrži, tako da svaka provjera na putu izdanja čita isti odgovor i odbija u slučaju nepodudaranja.
Svoj dio doprinosite isključivo putem manifesta: schema, db, domains, changePolicy i URL repozitorija. Platforma dopunjuje zapis ostatkom i potpisuje ga. Nikada sami ne imenujete svoj imenski prostor, prefiks registra ili ključ za potpisivanje. Oni vam se dodjeljuju, a manifest koji bi ih pokušao deklarirati iznosio bi tvrdnju u koju bi provjere tada morale posumnjati.
Potpisani zapis sadrži jedanaest polja: slug dodatka, organizaciju vlasnicu, organizaciju koja ga gradi, njegove repozitorije, naziv ključa za potpisivanje, imenski prostor za implementaciju, prefiks registra, shemu baze podataka, domene, pravila o promjenama te kratak popis starijih naziva slika koje je koristio prije nego što je postojao njegov prefiks registra. Taj se posljednji popis može samo smanjivati. Budući da je potpisan, novi potpis može ukloniti unos, a ništa ga ne može tiho dodati. Potpis je Ed25519 nad standardnim kanonskim JSON oblikom tih jedanaest polja, tako da se zapis u kojem se nalazi "Tomás" ili "Sinéad" svugdje jednako provjerava.
Kada izdanje ne odgovara svojem zapisu, prevladava prvo odbijanje:
| Kod | Kada | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Za dodatak ne postoji zapis | 403 |
DELIVERY_PATH_REFUSED |
Slanje slike izvan prefiksa registra koje nije na potpisanom popisu starijih naziva | 403 |
NAMESPACE_MISMATCH |
Implementacija usmjerena na drugi imenski prostor | 403 |
IMAGE_NAME_COLLISION |
Naziv slike koji već polaže drugi dodatak | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Klasa promjene koju pravila ne reguliraju | 403 |
IMAGE_NAME_COLLISION je ono koje iznenađuje ljude. Odaberite drugi naziv i nikada ga ne koristite ponovno: zajednički naziv slike znači da promocija jednog dodatka može premjestiti podove drugog dodatka.
Migracije, potvrđene i s definiranim opsegom
Migracija se isporučuje unutar slike vašeg dodatka i izvodi se prije pokretanja nove verzije, putem jedinog pokretača migracija u SDK-u, nexus-migrate. Ne pišete vlastiti alat za primjenu. Prije nego što se bilo koje izdanje može pomaknuti, isti pokretač primjenjuje vaše migracije datoteku po datoteku na privremenu bazu podataka, tako da migracija koja ne uspije ne uspije upravo tamo. Shadow izgradnja predloška poziva pokretač jednom po datoteci, redom, i bilježi svaku datoteku kao što će to učiniti produkcija.
Pravila pokretača ista su ona koja provjeravaju kontrolne točke, zapisana kao kod:
- Povezuje se kao uloga migratora vaše sheme i izvodi svaku datoteku kao vlasnik sheme. Svaka druga prijava, prije svega superkorisnik, odbija se. Datoteka koja sama pokuša promijeniti ulogu odbija se prije nego što se išta izvede.
- Datoteka zakupa, s brojem 0, nikada se ne uređuje nakon primjene. Promjena zakupa dobiva vlastitu datoteku revizije,
000_tenancy_r<N>.sql, kojunexus-tenancy render --revision <N>piše umjesto vas. - Uobičajeno pokretač upravlja transakcijom svake datoteke i odbija
BEGINiliCOMMITunutar nje. Datoteka koja sama upravlja svojim transakcijama deklarira da se izvodi po naredbi, a tada svakiBEGINkoji otvori mora imati par. - Vodi evidenciju, jedan redak po datoteci, sa SHA-256 datoteke i načinom izvođenja. Primijenjena datoteka nikada se ne mijenja na mjestu; promjena je nova numerirana datoteka.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlOgraničeno na opseg znači da svaka nova tablica sadrži organization_id, owner_user_id i business_unit_id, uz stupac oznake is_demo, osim ako gates/demo-exempt.json izuzme tablicu uz obrazloženje, s primarnim ključem koji počinje organizacijom i stranim ključevima koji je nose te s nametnutom sigurnošću na razini retka. Kontrolna točka migrations-are-scoped provjerava ta pravila u svakoj datoteci, a migrations-commit-what-they-open broji potvrđuje li svaka datoteka ono što otvori. Druga kontrolna točka postoji jer je migracija koja je tiho vraćena jednom završila s izlaznim kodom 0, a tablica koju je trebala stvoriti nikada nije postojala.
Još jedna datoteka pripada svakom izdanju. scripts/ci/required-env ispisuje varijable okruženja koje su vašoj usluzi potrebne za pokretanje, kao JSON polje preuzeto iz vašeg učitavača konfiguracije. Put izdanja pokreće ga i odbija izdanje čija implementacija ne postavlja svaku od njih, tako da se nedostajuća varijabla otkriva prije izdanja, a ne po podu koji se ne želi pokrenuti.
node scripts/ci/required-envIzdavanje vještina
Dvije vrste vještina dolaze do ljudi različitim putovima, stoga ih izdajte različito.
Manifestna vještina, tipizirani redak u skills[] vašeg dodatka, isporučuje se s dodatkom i prolazi istu promociju kao i ostatak. Uvođenje pri svakom izdanju sinkronizira cijeli skup vještina s registrom. Izostavite li vještinu iz skupa, ona se onemogućuje, a u izdanju Enterprise sinkronizacija s jednom neispravnom vještinom ne preuzima nijednu, tako da prethodna verzija nastavlja raditi umjesto polovice nove.
Vještina Skills Enginea objavljuje se iz knjižnice. U izdanju Enterprise vještina koja dodaje alat za pisanje čeka da je odobre dvije imenovane osobe svojim pristupnim ključevima, a predlagatelj ne može biti jedna od njih. Odobrena verzija zatim radi u sjenovitom načinu, potom u canary načinu za jednu jedinicu iza imenovanih uvjeta, a zatim za sve, i sama se zaustavlja ako neki uvjet nije ispunjen. Ako vaš dodatak i vještina Skills Enginea ovise jedno o drugome, najprije objavite vještinu i pustite da dođe do svih prije nego što izdanje dodatka koje je poziva izađe iz pilota.
Kanali i instalacije
Kada izdanje prođe pilot i dođe do svih jedinica, nudi se na kanalu, a svaka jedinica bira svoj kanal. Njezin administrator odobrava svaki prijelaz. Stranica Kanali i instalacije prikazuje koje jedinice pokreću koju verziju, sa stopama pogrešaka iskazanima samo kao brojevi: vidite kako se vaše proširenje ponaša, ali nikada što je itko s njim radio.
Naš dodatak carrier-sync istodobno pokreće tri verzije, i to je uobičajeno. Većina jedinica koristi trenutačno 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š nitko nije odabrao. Ne opirite se tome; jedinica kojoj je za reviziju potrebna stabilnost ima pravo na nju.
Zapisnici i metrike vašeg proširenja
Stranica zapisnika i metrika za vaš paket ograničena je na vaša vlastita radna opterećenja, u jedinicama u kojima smijete gledati. Možete filtrirati po jedinici i okruženju, a vidite brojeve, vremena i stanja.
Osobna polja zamjenjuju se prije nego što se redak zapiše, a sadržaj korisnika, poput teksta zahtjeva, pošte ili sadržaja dokumenata, nikada se ne zapisuje u zapisnike. Zapisnici se čuvaju 14 dana. Organizaciju određuje pristupnik, nikada vaš upit, pa se upit koji navodi drugu organizaciju odbija s TENANT_BOUNDARY. Asistent u doku može zajedno s vama čitati iste zapisnike, i samo njih: kada sam ga pitao zašto su zapisi o odstupanjima jednog jutra stigli s kašnjenjem, pronašao je da je 18 minuta ponovnih pokušaja uzrokovano dvostrukim očitanjima s napajanja jednog pristaništa.
Vraćanje na prethodno stanje
Postoje dvije vrste vraćanja, i obje su pregledane promjene, a ne prekidači.
Vraćanje okruženja koristi prethodnu verziju. Svako okruženje čuva je 30 dana. Vraćanje se priprema kao promjena izdanja, unaprijed prikazuje što će učiniti i zahtijeva drugu osobu; nakon odobrenja cjevovod izvršava vraćanje za otprilike minutu. Svako vraćanje mjeri se vremenski, kao i svaka vježba, stoga ga uvježbajte prije nego što vam zatreba. Vraćanje jedne jedinice koristi stranicu Kanali i instalacije. Modalni prozor za vraćanje navodi što se mijenja (ta jedinica ponovno pokreće stariju verziju, a njezina se stopa pogrešaka prati sat vremena), što ostaje (ostale jedinice te postavke i zapisi te jedinice), razlog i tko je druga osoba: administrator te jedinice.
Postavke i zapisi zadržavaju se pri vraćanju, stoga svako izdanje planirajte uz pretpostavku da bi prethodna verzija mogla ponovno raditi na podacima koje je zapisala novija. To je praktičan razlog da migracije unutar izdanja koje biste mogli vratiti budu isključivo dodavanja, i razlog zbog kojeg tražimo da svaku odobre dvije osobe. Isto vrijedi za promjenu modela: recenzent može, i trebao bi, prije odobrenja zatražiti plan vraćanja za zahtjev za promjenu grafa.
Vještine se vraćaju blaže. Vraćanje oznake live na raniju verziju jedan je korak, a izvođenja koja su već u tijeku završavaju na verziji s kojom su započela.
Umirovljenje verzije
Izdanje se, jednom kada je napravljeno, nikada ne uređuje. Verzija koja se više ne bi smjela koristiti povlači se, a ispravak se isporučuje kao novi broj verzije. Vlastiti kanali izdanja SDK-a slijede istu naviku: loša verzija SDK-a povlači se i nikada se ne zamjenjuje drugačijim sadržajem pod istim brojem. Preuzmite tu praksu, jer broj verzije koji može označavati dvije različite izgradnje čini bezvrijednim svaki dokaz o njoj.
Povlačenje dodatka ili paketa zaustavlja nove instalacije. Jedinice zadržavaju verziju koju pokreću dok ne prijeđu, stoga je povlačenje signal i rok, a ne isključivanje. Recite administratorima jedinica na koju verziju trebaju prijeći i do kada.
Umirovljenje vještine slijedi istu zamisao uz jedan korak više. Skills Engine premješta sve preostale pozivatelje na zamjenu nakon izvođenja slučajeva zamjene, zaustavlja nova izvođenja te čuva verzije, slučajeve i zapečaćene zapise o izvođenju, kako bi se vještina mogla vratiti ako se zamjena pokaže pogrešnom.
Kontrolni popis za izdavanje
Ovo je popis koji čitamo prije svakog izdanja paketa Cold chain. Kratak je jer platforma većinu toga provjerava umjesto nas.
- Verzije se podudaraju: manifest,
pack.jsoni model znanja ako se promijenio. - Svaki je uvjet lokalno zelen, iz čistog stanja, a za svaki je novi test pokazano da najprije ne prolazi.
- Stranica Manifest i dopuštenja ne prikazuje proširenje, ili je proširenje upravo ono što smo namjeravali i recenzenti znaju zašto.
- Svaka je migracija nova numerirana datoteka, s definiranim opsegom, i čisto primijenjena na privremenu bazu podataka.
scripts/ci/required-envnavodi svaku varijablu koja je usluzi potrebna, a implementacija postavlja svaku od njih.- Plan vraćanja zapisan je u promjeni, uključujući za svaku promjenu modela.
- Ovaj su tjedan dostupna dva recenzenta koji nisu autori.
Posljednja stavka zvuči trivijalno. Upravo je ona odgodila više naših izdanja nego svi uvjeti zajedno.



