AkiGarage/readme-release-sync

README-Release-Synchronisation

Verwenden Sie diesen Skill immer dann, wenn eine Aufgabe README-Kopien, Release-Notes, Changelogs, Produkt-Screenshots/GIFs oder zweisprachige Produktdokumentation betrifft.

Ziel ist es, den Review-Aufwand für Maintainer zu reduzieren: Die Dokumentation sollte mit dem tatsächlichen Produktzustand übereinstimmen, bevor Reviewer veraltete Namen, Screenshots, Feature-Beschreibungen oder englisch-japanische Unstimmigkeiten bemängeln müssen.

Kernregel

Bearbeiten Sie produktnahe Dokumente nicht allein auf Basis der vorhandenen Dokumentation. Identifizieren Sie zuerst die aktuelle Quelle der Wahrheit: App-Code, UI-Texte, Screenshots/GIFs, Release-Branch, Versionsdateien, Paket-Metadaten oder ein vom Benutzer bereitgestelltes aktuelles Screenshot/Video.

Arbeitsablauf

1. Zielzustand verankern

   • Bestätigen Sie Produkt-/App-Name, Branch, Version, Binärname und Plattform-Umfang aus den Repository-Dateien oder expliziten Benutzeranweisungen.
   • Prüfen Sie die relevante Implementierung oder die UI-Texte auf die beschriebenen Funktionen.
   • Behandeln Sie vom Benutzer bereitgestellte aktuelle Screenshots/Videos als maßgeblichen visuellen Nachweis, es sei denn, Code oder Branch-Kontext widersprechen ihnen eindeutig.

2. Dokumentation und Medien gemeinsam aktualisieren

   • Ersetzen Sie veraltete Screenshots/GIFs, wenn sich die UI geändert hat.
   • Überprüfen Sie, dass jeder Bildverweis existiert und auf die beabsichtigte Datei verweist.
   • Stellen Sie sicher, dass Screenshots dem aktuellen Produktnamen, Menübeschriftungen, Version oder UI-Zustand nicht sichtbar widersprechen.
   • Entfernen Sie alte Medienverweise, wenn sie entferntes Verhalten beschreiben.
   • Aktualisieren Sie bei einer öffentlichen Version, die von einem privaten Repository gespeist wird, die öffentlichen README-Dateien im öffentlichen Repository auf release/vX.Y.Z, nachdem die bereinigte Momentaufnahme dorthin kopiert wurde. Verlassen Sie sich nicht auf das private README als endgültige öffentliche Quelle der Wahrheit.
   • Behandeln Sie öffentliches CHANGELOG, Entwürfe von Release-Notes, Installationsdokumente und öffentliche Entwicklungs-Protokolle als Teil desselben versionsbezogenen Dokumentsets. Sie sollten dieselben Produktnamen, Version, Asset-Namen, Datenschutzangaben und anwenderorientierte Formulierungen wie das README verwenden.

3. Zweisprachige Dokumentation äquivalent halten

   • Vergleichen Sie englische und japanische Abschnitte Behauptung für Behauptung.
   • Bewahren Sie in beiden Sprachen dieselben Produktfakten, Feature-Reihenfolge, Hinweise und Setup-Anforderungen.
   • Lassen Sie wichtiges Verhalten nicht nur in einer Sprache erklärt.

4. Lesbares öffentliches README schreiben

   • Gestalten Sie erstlesbare Abschnitte überfliegbar: kurze Absätze, eine Idee pro Absatz und Leerzeilen, wo sie die Lesbarkeit verbessern.
   • Beginnen Sie mit dem, was das Produkt tut und was der Benutzer sehen oder tun kann. Fügen Sie Implementierungsdetails später ein, wenn sie für Setup, Sicherheit oder Fehlerbehebung relevant sind.
   • Bevorzugen Sie klare Verhaltensbeschreibungen gegenüber überladenen Feature-Sätzen. Eine gute Form ist ein Satz als Übersicht, gefolgt von 2-4 prägnanten Funktionszeilen.
   • Beschreiben Sie bei UI-Verhalten das sichtbare Ergebnis: ziehen zum Verschieben, an einer Kante oder Ecke die Größe ändern, Doppelklick zum Zurücksetzen. Vermeiden Sie interne Framework-Details wie Hit-Bänder, Cursor-Rechtecke, Skalierungsinterna oder genaue Standardprozente, es sei denn, der Benutzer benötigt sie.
   • Behalten Sie detaillierte Informationen dort, wo sie wirklich nützlich sind, aber lassen Sie das öffentliche README nicht mit Maintainer-exklusiven Implementierungserklärungen belasten.
   • Wenden Sie dieselbe Lesbarkeitsregel auf Release-Notes und Changelog-Einträge an: Vermeiden Sie interne Präzision wie genaue Standardprozente, Hit-Band-Formulierungen, Cursor-Rechteck-Mechaniken oder Build-System-Trivia, es sei denn, es betrifft einen benutzersichtbaren Fix, Installationsschritt oder Troubleshooting-Pfad.

5. Japanisch leserfreundlich gestalten

   • Bevorzugen Sie gewöhnliche japanische UI-Begriffe, wenn sie natürlich sind: タブ, 詳細パネル, マウスオーバー, 最小表示, フローティングタブ.
   • Behalten Sie technische Literale wie Befehle, Pfade, Paketnamen, App-Namen, URLs und Code-Identifikatoren auf Englisch bei.
   • Entfernen Sie redundante Feature-Listen und wiederholte Absätze; machen Sie das Haupt-Feature-Set für einen allgemeinen japanischen Leser schnell erfassbar.

6. Auf veraltete Produkt-Inkonsistenzen prüfen

   • Alte Produktnamen, alte App-Namen, alte Binärnamen und alte Repository-Namen.
   • Alte Versionsnummern außerhalb historischer Changelog-Einträge.
   • Veraltete UI-Beschriftungen, entfernte Plattform-Hinweise und Screenshots aus älterem Verhalten.
   • Behauptungen, die implizieren, dass eine Abhängigkeit laufen muss, wenn nur ein installiertes CLI oder Paket erforderlich ist.

7. Vor Abschluss validieren

   • Führen Sie verfügbare Doc-Lint/Check-Befehle aus.
   • Führen Sie eine begrenzte rg-Suche nach veralteten Namen/Versionen/Beschriftungen durch.
   • Führen Sie die Suche nach veralteten/privaten/zu internen Formulierungen über README-Dateien, Changelogs, Release-Notes und alle in der Version ausgelieferten öffentlichen Dokumente durch, nicht nur über das oberste README.
   • Überprüfen Sie, ob die README-Bildlinks existieren.
   • Stellen Sie bei Release-PRs Maintainern die GitHub-gerenderten README-URLs für den Branch/PR zur Verfügung und warten Sie auf explizite visuelle Freigabe. Diese muss der tatsächlichen GitHub-Anzeige entsprechen, die Benutzer sehen werden; lokale Vorschauen, rohes Markdown, statische Screenshots oder automatisierte Checks sind nur unterstützende Nachweise.
   • Prüfen Sie den git diff des öffentlichen Repositorys, sodass README-Aussagen, Versionsmetadaten, Release-Asset-Namen und kopierte Implementierungsänderungen übereinstimmen.
   • Bevorzugen Sie bei öffentlichen Versionen den Ablauf release/vX.Y.Z-Branch -> PR -> CI -> Merge vor Tag oder GitHub-Release-Erstellung. Direkte main-Pushes sollten nur verwendet werden, wenn der Maintainer explizit darum bittet, das PR-Gate zu überspringen.
   • Führen Sie bei Code-Änderungen die relevanten Tests oder Builds aus.
   • Fassen Sie die Überprüfungen der Quellen der Wahrheit zusammen, nicht nur die bearbeiteten Dateien.

Ausgabe-Checkliste

Melden Sie vor Abschluss:

• Produktname/Version/Branch geprüft;
• Medienverweise geprüft;
• Japanisch/Englisch-Gleichheit geprüft;
• GitHub-gerenderte README visuelle Freigabe erhalten oder explizit noch ausstehend;
• Ergebnis der Suche nach veralteten Formulierungen;
• Tests/Build/Doc-Checks durchgeführt oder Grund, warum sie nicht durchgeführt wurden.