lumosframework/lumos-for-astro

Aktualisieren einer Lumos-Seite

Zwei Dinge müssen am Ende wahr sein, und sie ziehen in entgegengesetzte Richtungen:

1. Nichts, was der Benutzer geschrieben hat, geht verloren. Seine Überschreibungen, seine Seiten, seine Tokens, seine Komponenten.
2. Nichts bleibt auf alten Konventionen. Umbenannte Props wurden umbenannt, verschobene Komponenten verschoben, ausgemusterte Muster ausgemustert.

Seine Arbeit zu bewahren, indem man sie in Ruhe lässt, scheitert am zweiten Punkt. Modernisieren durch Überschreiben scheitert am ersten. Der Weg dorthin ist ein Drei-Wege-Merge – wovon er ausgegangen ist, was er jetzt hat, was heute ausgeliefert wird – und die Disziplin nachzufragen statt zu raten, wenn diese drei uneins sind.

Wo die Seite gestartet ist

Ein Upgrade ist nur so gut wie sein Wissen über den Ausgangspunkt.

node -p "JSON.parse(require('fs').readFileSync('package.json')).lumos ?? 'unstamped'"

• Gestempelt (Stamped) – { version, commit, scaffolded } geschrieben von create-lumos. Die Version ist das Release, von dem die Seite stammt, zum Lesen; der Commit ist das, wogegen gemerged wird, und das ist der, der zählt. Sie sind nicht redundant: Eine Seite, die zwischen Releases gerüstet wurde, ist diese Version plus das, was danach dazu kam, und nur der Commit sagt, wie viel. Seiten, die vor dem Hinzufügen der Version gestempelt wurden, tragen nur den Commit, was ausreicht. Dieser Commit ist die Merge-Basis. Hole ihn und du weißt genau, welche Zeilen vom Framework sind und welche vom Benutzer.
• Unbestempelt (Unstamped) – Die Seite datiert vor der Stempelung. Behandle v0.0.1 als Basis. Sag das im Bericht deutlich: Die Basis ist eine Vermutung, also wird mehr vom Merge als Konflikt landen und braucht mehr Augen.

Die eigene package.json-Version der Seite sagt nichts – create-lumos setzt jede neue Seite auf 0.0.1. Lies sie nicht als Framework-Version.

Schritte

1. Commit, was da ist

Weigere dich, auf einem unsauberen Baum zu starten – ein Diff während eines Upgrades ist unlesbar, wenn es mit der gestrigen Arbeit vermischt ist.

git status --porcelain          # muss leer sein
git commit --allow-empty -m "Vor Lumos-Upgrade"

Der leere Commit ist beabsichtigt: Er ist der Anker, gegen den das gesamte Upgrade gelesen wird, und git diff <dieser Commit> wird zur Überprüfung.

2. Fotografiere die Seite

Bevor sich etwas ändert, bei laufendem Dev-Server:

astro dev --background
node .agents/skills/lumos-upgrade-version/visual-check.mjs capture before

Jede statische Route auf Desktop und Mobil. Das ist der Beweis, gegen den Schritt 8 prüft, und er kann nicht hinterher gemacht werden.

3. Hole beide Referenzkopien

npm create lumos@latest .lumos-upgrade/latest    # was heute ausgeliefert wird

Und die Merge-Basis – der Commit, von dem die Seite gerüstet wurde:

curl -sL https://codeload.github.com/lumosframework/lumos-for-astro/tar.gz/<commit> \
  | tar -xz -C .lumos-upgrade --one-top-level=base --strip-components=1

Jetzt existieren drei Bäume: base (wo sie angefangen haben), die Seite (wo sie sind), latest (wo sie hingehen).

4. Sortiere jede Datei in einen von vier Stapeln

Für jede Datei in der Framework-Oberfläche – Komponenten, Layouts, Styles, Hilfsprogramme:

base vs site	base vs latest	Was es ist	Was zu tun ist
gleich	gleich	auf beiden Seiten unberührt	belassen
gleich	geändert	Framework bewegt, Benutzer nie angefasst	nimm latest komplett
geändert	gleich	Benutzer-Override, Framework unverändert	behalte ihre
geändert	geändert	beide bewegt	Drei-Wege-Merge, Konflikte in den Bericht

src/pages, src/content und src/assets sind per Definition des Benutzers – ersetze sie niemals. Sie müssen trotzdem in Schritt 6 migriert werden.

.agents/skills wird komplett upgegradet, mit einer Ausnahme. Der Prosa eines Skills gehört dem Framework und sollte auf den neuesten Stand gebracht werden, aber ein Skill kann einen Abschnitt enthalten, den das Projekt hineingeschrieben hat – /lumos-import-webflows Dieses Projekt ist einer, und er zeichnet Pfade, Anbieter und CMS-Filter auf, die nirgendwo sonst existieren. Übernimm jeden solchen Abschnitt wörtlich, bevor du die neue Datei nimmst, und sag im Bericht, dass du es getan hast. Das komplette Übernehmen von latest zerstört eine Aufzeichnung, die es sonst nirgendwo gibt.

5. Merge base.css statt es zu ersetzen

Globales CSS ist die Datei, die am wahrscheinlichsten im vierten Stapel ist: Das Framework fügt Tokens hinzu, der Benutzer ändert Markenfarben und Schriftarten. Merge es drei Wege, Token für Token, und halte dich an zwei Regeln:

• Ein Token, das der Benutzer geändert hat, behält seinen Wert, auch wenn das Framework den Standard geändert hat. Seine Markenfarbe ist kein veralteter Standard.
• Ein Token, das das Framework hinzugefügt hat, kommt mit dem Wert des Frameworks, platziert in einem eigenen Abschnitt – nicht ans Ende angehängt.

Jeder Token, bei dem sich beide Seiten geändert haben, kommt mit beiden Werten in den Bericht. Entscheide nicht für sie.

6. Migriere den eigenen Code der Seite

Diff base gegen latest, um zu erfahren, was sich bewegt hat, und wende es dann auf src/pages und alles an, was der Benutzer geschrieben hat:

• Umbenannte oder verschobene Komponenten – aktualisiere jeden Import und jeden Tag. Eine Komponente, die Ordner gewechselt und ein Präfix verloren hat (FormInput → Form/Input.astro), sind zwei Änderungen in einer; mach beide.
• Umbenannte Props – benenne sie an jeder Aufrufstelle um.
• Entfernte Props – halte inne und frage. Biete für jedes die drei echten Optionen an: das Prop als lokales Override behalten, es entfernen oder zu dem verschieben, was es ersetzt hat. Entscheide niemals stillschweigend; ein entferntes Prop bedeutete normalerweise etwas.
• Gelöschte Komponenten – behalte die Kopie des Benutzers. Kopiere die Komponente aus base in den eigenen Komponentenordner der Seite, damit die Seite noch baut und immer noch gleich aussieht, und markiere sie: Sie wird nicht mehr vom Framework gewartet, und hier ist, was sie ersetzt hat, falls überhaupt etwas.

7. Beweise, dass es baut

npx astro check && npx astro build

Beide sauber, bevor du in die Nähe der Screenshots gehst. Ein jetzt gefundener Typfehler ist eine Migration, die übersehen wurde.

Überprüfe die Astro-Paarung, während du schon hier bist. Astro ist die eigene Abhängigkeit der Seite, nicht die des Frameworks – Lumos wird eingerüstet, nicht installiert –, also ist ein Upgrade der natürliche Moment zum Nachsehen, nicht eine Lizenz, eines zu erzwingen. Vergleiche das astro der Seite mit dem Release, das gemerged wird; wenn die Seite bei einem Major hinterherhinkt, sag es im Bericht und lass den Eigentümer entscheiden.

Erhöhe es mit npx @astrojs/upgrade statt von Hand. Es bewegt die @astrojs/*-Integrationen mit Astro, und @astrojs/sitemap deklariert keine Peer-Abhängigkeit von Astro – also installiert ein nicht passendes Paar sich ohne ein Wort und taucht als Build-Fehler auf oder als eine Sitemap, die stillschweigend nicht mehr geschrieben wird.

8. Beweise, dass nichts verrutscht ist

node .agents/skills/lumos-upgrade-version/visual-check.mjs capture after
node .agents/skills/lumos-upgrade-version/visual-check.mjs compare

Pixel-Diffs jede Route gegen Schritt 2 mit einer Toleranz für Anti-Aliasing und schreibt ein hervorgehobenes Diff für alles über 0,1 % der Pixel. Exit-Code ist ungleich Null, wenn sich etwas bewegt hat.

Ein Upgrade, das das Design ändert, ist irgendwo schiefgelaufen – ein Token falsch gemerged, ein Prop fallen gelassen, eine Komponente gegen eine ausgetauscht, die nicht ganz gleich ist. Arbeite rückwärts vom Diff-Bild, bis jedes erklärt ist. Einige sind legitim: Ein echter Bugfix upstream wird Pixel verschieben. Die Regel ist nicht „keine Unterschiede“, es ist „keine unerklärten Unterschiede“.

9. Committe das Ergebnis

git add -A && git commit -m "Upgrade Lumos auf <commit>"

Aktualisiere den Stempel in package.json auf den gerade gemergten Commit, damit das nächste Upgrade eine exakte Basis hat. Lösche dann .lumos-upgrade/.

Der Bericht

• Von latest übernommen – Dateien komplett ersetzt, weil sie unberührt waren.
• Als deine behalten – Overrides bewahrt, Framework-Änderungen abgelehnt.
• Gemerged – Dateien, bei denen sich beide Seiten bewegt haben, mit dem, was woher kam.
• Migriert – Umbenennungen und Verschiebungen, die auf den eigenen Code des Benutzers angewendet wurden, gezählt.
• Am Leben erhalten – Komponenten, die upstream gelöscht und in die Seite kopiert wurden, mit dem, was sie ersetzt hat.
• Beantwortet – Entfernte Props und wie der Benutzer sich entschieden hat, jedes zu lösen.
• Visuelle Unterschiede – jede Ansicht, die sich bewegt hat, und warum.
• Noch offen – alles Ungelöste. Ein Upgrade kann mit dieser Liste nicht leer abschließen, solange es angegeben wird.

Versionen

• Skill-Version – 1.0.0.
• Framework – es gibt noch keine nennenswerten Releases: create-lumos rüstet von mains HEAD, also bedeutet „latest“ den neuesten Commit, und die Merge-Basis ist ein Commit statt eines Tags. Wenn getaggte Releases kommen, bevorzuge das Tag im Stempel und lies das Changelog in Schritt 4, anstatt blind zu differenzieren.

Verwendung ohne Claude Code

Die Schritte sind reines Git und Node. visual-check.mjs braucht Headless Chrome und sharp, beides hat ein Astro-Projekt auf einem Mac bereits. Nur die automatische Auslösung und /lumos-upgrade sind Claude Code-Funktionen.