Docs

Publish-Semantik

Kurzfassung

  • Publish und promote (release) sind zwei getrennte Operationen. Publish speichert einen unveränderlichen, privaten prerelease-Build, den der Aufrufer testen kann; promote gibt eine gewählte prerelease in die öffentliche, pinnbare Version frei.
  • Jeder component-Build durchläuft zwei Zustände: prerelease (privat für den Aufrufer, nur von ihm deploybar) und released (öffentlich, deploybar von jedem im Publikum des workspaces). Publish erstellt den ersten; promote macht daraus den zweiten.
  • Eine prerelease ist ein unveränderlicher, validierter Snapshot des Quellbaums. Der Build läuft auf der Plattform, um zu bestätigen, dass er kompiliert, das resultierende Image wird privat gespeichert, kein Registry-Push geschieht, keine Katalog-Tags bewegen sich. Jeder publish prägt eine neue prerelease-ID — die Plattform aktualisiert Versionen nicht an Ort und Stelle.
  • Ein promote gibt diese prerelease in den released-Katalog frei: das Image geht in die Registry, die in component.yml deklarierten Tags (latest/default/custom) bewegen sich, katalog-zugewandte Felder (categories, modalities, neighbors, alternatives) synchronisieren, die Version kippt den Zustand. Die ID ändert sich nicht.
  • Die zwei Operationen beantworten verschiedene Fragen. Publish beantwortet "baut das". Promote beantwortet "ist diese Version öffentlich". Sie getrennt zu halten hält einen Build, der nur die Validierung besteht, aus dem öffentlichen Katalog heraus.
  • Die CLI ist cwd-gesteuert: ppl component publish und ppl component promote lösen beide das component aus der component.yml des Arbeitsverzeichnisses auf. Es gibt kein version-id-Argument bei promote; die neueste prerelease des cwd-components ist das Ziel.

Warum zwei Zustände existieren

Publish und promote (release) sind zwei getrennte Operationen. Publish speichert einen unveränderlichen, privaten prerelease-Build, den der Aufrufer testen kann; promote gibt eine gewählte prerelease in die öffentliche, pinnbare Version frei. Sie getrennt zu halten bedeutet, dass ein Build privat bleibt, bis ihn etwas explizit promotet, sodass niemand, der den öffentlichen Tag pinnt, von einem nicht freigegebenen Build abhängt.

Publish validiert einen Build und speichert den resultierenden Snapshot zum Testen. Der Build läuft auf dem Builder der Plattform, das Image wird privat für den Aufrufer gespeichert, und das Artefakt ist über seine prerelease-ID adressierbar. Niemand sonst sieht es. Der Aufrufer kann es in einem Test-backend deployen, eine Live-Fixture-Schleife laufen lassen und sein Verhalten mit der vorherigen Version vergleichen. Keine dieser Aktivitäten ist außerhalb des workspaces des Aufrufers sichtbar.

Promote ist die separate Entscheidung, dass die validierte prerelease bereit ist, freigegeben zu werden — öffentlich gemacht im Katalog, getaggt als latest / default / was auch immer das component deklariert, und deploybar von jedem, dessen Sichtbarkeits-Scope es einschließt. Eine released Version ist das, wogegen andere Leute pinnen.

Die Aufteilung macht "ist diese Version sicher, von ihr abzuhängen" beantwortbar. Eine gepinnte released-Version hat sowohl die Validierung (publish) als auch eine menschliche Entscheidung (promote) durchlaufen. Eine prerelease-ID ist konstruktionsbedingt private Erkundung: das richtige Artefakt für Tests, das falsche Artefakt für die Produktion.

Was publish tatsächlich tut

Publish friert den aktuellen Zustand des Quellbaums des components in eine neue Versionszeile ein. Die CLI läuft aus dem Root-Verzeichnis des components (dem mit component.yml und src/), paketiert die Quelle, das Manifest, alle vorhandenen Docker-Stage-Dateien, das Assets-Verzeichnis und ein LICENSE, falls klein genug. Sie schickt dieses Bundle an das Build-System der Plattform, der Build läuft remote, und bei Erfolg zeichnet die Plattform eine neue Version im Zustand prerelease mit einer frischen ID auf.

ppl component publishppl component publish -m "describe the change"ppl component publish --dry-run    # validieren, ohne etwas zu schreiben

--dry-run führt dieselbe Paketierung und denselben Remote-Build aus und meldet Erfolg, erstellt aber kein Remote-component, persistiert keinen lokalen Link, registriert keine Version und pusht nichts in die Registry. Es ist die Schleife für schnelle Iteration beim Editieren von src/ — wenn --dry-run besteht, stimmt der plattformseitige Build mit der Quelle überein.

Das Lookup-oder-Create-Verhalten ist es, was den ersten publish und jeden nachfolgenden publish vorhersehbar verhalten lässt. Wenn das Arbeitsverzeichnis an ein bestehendes component verlinkt ist, schreibt publish eine neue prerelease gegen dieses component. Wenn nicht, sucht es das component nach Namen (dem name: aus component.yml); eine einzelne Übereinstimmung verlinkt sich damit; null Übereinstimmungen erfordern explizite -y / --yes-Zustimmung zur Erstellung eines neuen Remote-components. Verlinken ist nicht-destruktiv und das Adoptieren eines bestehenden Remotes erfordert keine Zustimmung; das Erstellen eines neuen Remotes schon, da das Zustimmungs-Flag die eine Aktion gatet, die ein neues Objekt produziert.

Was publish nicht tut, ist ebenso tragend. Es pusht nicht in eine öffentliche Registry; das Image bleibt privat. Es aktualisiert keine bestehende Version an Ort und Stelle; jeder publish ist eine neue ID, selbst wenn die Quell-Bytes identisch sind. Es deployt nicht neu; backends pinnen weiterhin auf die Version, mit der sie erstellt wurden, und ein vertex muss auf eine neuere Version gebumpt und das backend neu deployt werden, damit der neue Code läuft.

Was promote tatsächlich tut

Promote nimmt eine bestimmte prerelease (die zum cwd-component gehörende) und führt die Release-Schritte auf ihr aus: das Image aus der gespeicherten Quelle neu bauen (sodass das Registry-Image aus dem aufgezeichneten Quell-Bundle reproduzierbar ist statt aus dem lokalen Docker-Cache des Aufrufers zur Publish-Zeit), es in die Plattform-Registry pushen, die in component.yml deklarierten Tags anwenden (latest, default oder was auch immer das Manifest benennt), die katalog-zugewandten Felder synchronisieren (categories, modalities, neighbors.upstream, neighbors.downstream, alternatives) und den Zustand der Version auf released kippen. Die ID ändert sich nicht; die Version, die prerelease war, ist jetzt released.

cd <component-root>ppl component promote

Es gibt kein version_id-Argument, weil die prerelease des cwd-components das Ziel ist. Tags und Katalog-Felder kommen zur Promote-Zeit aus component.yml — es gibt kein separates "update tags"-Verb, und die Plattform lehnt Tag-Schreibvorgänge gegen eine prerelease ab, da Tags der öffentliche Vertrag sind und eine prerelease keinen öffentlichen Vertrag hat. Bis die Promotion läuft, zeigen die latest- und default-Tags weiterhin auf die zuvor veröffentlichte Version, sodass ein neuer Build nicht ändert, was die Öffentlichkeit auflöst.

Prüfe die bestehenden Versionen vor dem Promoten (ppl component versions <component_id> listet sie ältester zuerst auf, mit Release-Zustand und Tags jeder Version). promote löst die einzelne prerelease des cwd-components auf und gibt sie frei; die in component.yml deklarierten Tags entscheiden, wo latest und default landen. Ein component hat zu jeder Zeit höchstens eine prerelease, sodass es nie eine Mehrdeutigkeit darüber gibt, auf welcher Version promote agiert.

Die cwd-Disziplin

Sowohl publish als auch promote lösen das Ziel-component aus dem Arbeitsverzeichnis auf. Die CLI läuft vom aktuellen Verzeichnis nach oben und sucht nach einer verlinkten component.yml; die erste gefundene ist das component, auf dem operiert wird. Keiner der Befehle nimmt ein version-id-Argument — das cwd ist das Argument. publish aus dem falschen Verzeichnis auszuführen veröffentlicht das falsche component; promote aus dem falschen Verzeichnis auszuführen promotet die falsche prerelease.

Das Auflösen aus dem Arbeitsverzeichnis hält das Ziel an den Quellbaum auf der Platte gebunden statt an einen separat gelieferten Identifier. Das Verzeichnis, in dem der Aufrufer steht, ist das component, auf dem operiert wird.

Wie publish, promote und deploy sich zusammensetzen

Die drei Verben sind unabhängige Operationen, die sich in die Release-Schleife zusammensetzen:

  • Publish prägt eine prerelease, die vom Aufrufer deploybar ist. Der nächste Schritt ist meist ein Live-backend-Test auf der prerelease (siehe Mit einem Live-Backend testen).
  • Promote gibt die prerelease in den Katalog frei. Promotete Versionen sitzen im Katalog, verfügbar zum Pinnen.
  • Deploy lässt ein backend auf einer runtime laufen. Backends pinnen auf bestimmte version-IDs; das Promoten einer prerelease ändert die gepinnte Version keines deployten backends. Um ein backend vorwärtszurollen, ändere die Version des vertex (ppl backend change-version) und deploye neu.

Die drei operieren auf verschiedenen Oberflächen. Publish produziert nur private prereleases. Promote ändert nur den Katalog; kein laufendes deployment bewegt sich. Deploy berührt die runtime, aber nicht den Katalog. Weil die Oberflächen verschieden sind, läuft jeder Schritt, ohne die anderen zu koordinieren.

Wo das hineinpasst

Die Publish-Semantik ist der Vertrag, auf den sich jede andere release-bezogene Entscheidung verlässt. Test-Schleifen hängen davon ab, dass prereleases unveränderlich sind, sodass ein Beweis gegen eine prerelease-ID gültig bleibt. Die Promotion hängt davon ab, dass die validierte prerelease genau das ist, was die Registry bedient. Deployments hängen davon ab, dass sich gepinnte Versionen nicht unter ihnen ändern. Diese Garantien folgen alle aus derselben Regel: publish prägt, promote gibt frei, deploy pinnt, und nichts mutiert nach dem publish.

Das Modell verwendet zwei Verben statt eines. Im Gegenzug entspricht eine released Version immer einem einzigen aufgezeichneten Build, der durch Validierung und eine menschliche Promote-Entscheidung ging, und eine gepinnte Version bleibt der Build, auf den sie gepinnt wurde.

Verwandt

War diese Seite hilfreich?