istio.io
1.0.0
| Website | Status |
|---|---|
| Istio.io | |
| vorläufig.istio.io | |
| archive.istio.io |
Dieses Repository enthält den Quellcode für iStio.io und vorläufig.istio.io.
In der Hauptdatei "Main iStio ReadMe" erfahren Sie, wie Sie das Gesamtprojekt ISTIO und wie Sie mit uns in Verbindung setzen können. Um zu erfahren, wie Sie zu einer der ISTIO -Komponenten beitragen können, finden Sie in den Richtlinien für ISTIO -Beitragsbetrieb.
Um zu erfahren, wie Sie den Inhalt dieses Repos bearbeiten und erstellen, finden Sie im Erstellen und Bearbeiten von Seiten.
Istio hält zwei Variationen seiner öffentlichen Website bei.
iStio.io ist die Hauptstelle und zeigt Dokumentation für die aktuelle Version des Produkts an. Istio.io/archive enthält Schnappschüsse der Dokumentation für frühere Veröffentlichungen des Produkts. Dies ist nützlich für Kunden, die diese älteren Veröffentlichungen verwenden.
vorläufig.istio.io enthält die aktiv aktualisierte Dokumentation für die nächste Veröffentlichung des Produkts.
Der Benutzer kann trivial zwischen den verschiedenen Variationen der Site navigieren, indem Sie das Ausrüstungsmenü oben rechts auf jeder Seite befinden. Beide Websites werden auf Netlify gehostet.
Dokumentationsänderungen werden in erster Linie für den Master -Zweig von iSTIO.IO verpflichtet. Änderungen, die in dieser Filiale festgelegt sind, spiegeln automatisch auf vorläufig.istio.io wider.
Der Inhalt von iStio.io stammt aus der neuesten Release-XXX-Filiale. Der verwendete Zweig, der verwendet wird, wird durch die Konfiguration des Projekts iStio.io Netlify -Projekt bestimmt.
Durch die Überprüfung der Aktualisierungen in der Master -Niederlassung wird vorläufig.ISTIO.IO automatisch aktualisiert und spiegelt sich nur auf iStio.io wider, wenn eine Veröffentlichung eine Veröffentlichung erstellt wird, was in Zukunft mehrere Wochen dauern kann. Wenn Sie möchten, dass einige Änderungen sofort auf iStio.io reflektiert werden, müssen Sie Ihre Änderungen sowohl in der Master-Filiale als auch in der aktuellen Release-Filiale (mit dem Namen release-<MAJOR>.<MINOR> wie release-1.7 ) überprüfen.
Dieser Prozess kann durch unsere Infrastruktur automatisch erledigt werden. Wenn Sie eine PR an die Master-Filiale einreichen und die PR mit dem cherrypick/release-<MAJOR>.<MINOR> wird es in den angegebenen Release-Zweig in den Master zusammengefasst.
Hier sind die Schritte, die zum Erstellen einer neuen Dokumentationsversion erforderlich sind. Nehmen wir an, die aktuelle Version von ISTIO beträgt 1.6 und Sie möchten 1.7 einführen, die in der Entwicklung befinden.
Run make prepare-1.7.0 , und das war's. Dadurch werden die neuesten Referenzdokumente aus der neuen ISTIO -Quelle in den content/en/docs/reference -Ordner eingerechnet.
Für einen trockenen Lauf vor der offiziellen Veröffentlichung make release-1.7.0-dry-run , der nur eine neue Branch release-1.7-dry-run erstellt und keine anderen Zweige berührt.
Am Tag der Veröffentlichung machen Sie Run make release-1.7.0 . Dieses Ziel wird einige Variablen in master und release-1.6 geändert und eine neue Branch release-1.7 für die neue Version erstellen.
Gehen Sie zum ISTIO.IO -Projekt auf Netlify und machen Sie Folgendes aus:
Ändern Sie die Zweigstelle, die aus der Zweigstelle der vorherigen Version in die neue Release-Zweigstelle erstellt wurde, in diesem Fall release-1.7 (oder gegebenenfalls release-1.7-dry-run ).
Wählen Sie die Option zum Auslösen eines sofortigen Umbaues und einer Umschreckung.
Sobald die Bereitstellung beendet ist, stöbern Sie in Istio.io und stellen Sie sicher, dass alles gut aussieht.
Gehen Sie zur benutzerdefinierten Google -Suchmaschine und machen Sie Folgendes:
Laden Sie die CSE -Kontextdatei istio.io auf der Registerkarte Erweitert herunter.
Fügen Sie ein neues FacetItem oben in der Datei mit der Versionsnummer der vorherigen Version hinzu. In diesem Fall wäre dies V1.6 .
Laden Sie die aktualisierte CSE -Kontextdatei auf die Website hoch.
Fügen Sie im Setup -Abschnitt eine neue Site hinzu, die das Archivverzeichnis der vorherigen Version abdeckt. In diesem Fall wäre die Site -URL istio.io/v1.6/* . Stellen Sie das Etikett dieser Site auf den Namen des oben erstellten Facettenelements (in diesem Fall V1.6 ).
Einige Tage vor der Patch -Veröffentlichung sollten die Release -Manager den DOC WG mit dem Aufbau der Veröffentlichung benachrichtigen und startet den langjährigen Qualifikationstest. Bewegen Sie zu diesem Zeitpunkt die DOC -Automatisierungstests, um die neue Version zu verwenden, um automatisierte DOC -Tests zu überprüfen.
Um zu einer neuen Version zu wechseln (stellen Sie sicher, dass Sie sich in der Release -Zweigstelle des Patchs befinden):
Run go get istio.io/istio@AXY && go mod tidy .
Erstellen Sie eine PR mit dem go.* Änderungen.
Durch das Erstellen einer neuen Patch -Version werden einige Dateien geändert:
Bearbeiten Sie data/args.yml und ändern Sie das Feld full_version in "AXY" . Dies ist nur für einen Patch der current Version benötigt.
Vervollständigen Sie den Release-Hinweis für die Veröffentlichung, indem Sie den Markdown- content/en/news/releases/AXx/announcing-AXY/index.md bearbeiten. Hier beschreiben Sie die Änderungen in der Veröffentlichung. Bitte sehen Sie sich andere vorhandene Dateien an, z. B. Inhalt und Layout.
Run make update_ref_docs um die neuesten Referenzdokumente zu erhalten. Normalerweise wird dies nur für einen Patch der current Version benötigt. Bei Bedarf in einer früheren Version finden Sie in Aktualisieren eines Archivs.
Wenn die archivierte Version in einem neueren Zweig (z. B. release-1.7:archive/v1.6 ) aufgrund von Änderungen in der alten Release-Zweigstelle ( release-1.6 ) aktualisiert werden muss, können Sie im master Zweig make build-old-archive-1.6.0 , der release-1.6 erneut angeht und das vorherige Archiv für das vorherige Archiv im master Zweig wieder angeht. Wenn dieses Update in iStio.io widerspiegelt werden muss, kann die PR für die current Version in den Zweig gepflückt werden.
Die Release-Streams beginnen mit release-1.6 Tests für den Testinhalt. Jeder Release testet gegen eine bestimmte ISTIO -Version/ein bestimmtes iStio -Version. Wenn das Release -Team einen Build, 1.xy , bereit für ihre langlebigen Tests hat, sollten sie zum DOCS -Team kommen, um die Tests für diesen Release -Lauf gegen den Build zu laufen.
Es gibt zwei Arten von Builds, public und private . Die normalen Entwicklungs- und Veröffentlichungsgebäude werden aus unseren öffentlichen Repos gebaut und haben Bilder in einem öffentlich zugänglichen Repository und gelten als public . Private Builds sind diejenigen, bei denen wir vor der Veröffentlichung nicht viel preisgeben können. In der Regel ist es eine Voraussetzung dafür, dass eine Veröffentlichung in zwei Wochen für CVEs stattfinden wird. Da wir vor der tatsächlichen Veröffentlichung nichts preisgeben können, befinden sich die Quelle und die erstellten Bilder in privaten Repos. Da die Quelle und die Bilder privat sind, können wir sie erst öffentlich zu ihnen bewegen, und daher gibt es keine frühzeitigen Tests der Veröffentlichung in iStio.io. Der Unterschied für private Builds besteht darin, dass die Bilder, gegen die wir testen, im public GCR.IO -Repository nie erstellt wurden. In diesem Fall verwenden wir die Docker.io -Bilder. Man kann sich fragen, warum wir die Release -Bilder von Docker.io nicht immer verwenden. Da wir public Builds testen wollen, bevor sie veröffentlicht werden, existieren die Bilder noch nicht auf Docker.io.
Für öffentliche Builds:
go get istio.io/istio@commit && go mod tidy .Für private Builds (dies erfolgt nach der Veröffentlichung des Builds):
go get istio.io/[email protected] && go mod tidy .Für beide Builds möchten wir überprüfen, ob das Hub/Tag in makefile.core.mk korrekt ist (sie ändern sich je nachdem, ob die privaten oder öffentlichen Builds verwendet werden). Suchen Sie nach dem Abschnitt ähnlich:
# If one needs to test before a docker.io build is available (using a public test build),
# the export HUB and TAG can be commented out, and the initial HUB un-commented
HUB ?= gcr.io/istio-testing
# export HUB ?= docker.io/istio
# export TAG ?= 1.7.3
Für öffentliche Builds wären die export HUB/TAG sconmentiert und haben korrekte Werte. Für private Builds oder den master -Zweig würde der Hub sich nicht in Verbindung setzen.
Erstellen und senden Sie schließlich eine PR mit den Änderungen und man kann die Testergebnisse in der PR sehen. Normalerweise verschmelzen die PR erst dann erst, wenn die Veröffentlichung veröffentlicht wird (manchmal gibt es mehrere Builds für eine Veröffentlichung).
Viele Dokumente auf der ISTIO -Website zeigen Funktionen mit Befehlen, die möglicherweise weiter funktionieren oder nicht, während sich ISTIO von der Release zu Release entwickelt. Um sicherzustellen, dass die dokumentierten Anweisungen mit möglichst geringen kontinuierlichen manuellen Tests auf dem Laufenden bleiben, haben wir ein Framework für die Automatisierung der Tests dieser Dokumente erstellt.
Jede Seite auf iStio.io, die getestet werden kann, enthält eine PAGE TEST unter dem Seitentitel. Zum Beispiel:
Ein Green Checkmark zeigt an, dass für die Seite ein automatisierter Test verfügbar ist. Die Seite ist auf dem neuesten Stand und funktioniert wie dokumentiert.
Ein graues X hingegen bedeutet, dass noch kein automatisierter Test für die Seite verfügbar ist. Wir würden es zu schätzen wissen, wenn Sie helfen möchten, eine zu erstellen! Unser Ziel ist es, schließlich einen automatisierten Test für jedes auf der Website ISTIO veröffentlichte testbare Dokument durchzuführen.
Weitere Informationen finden Sie in den Tests Readme.
Die Website wird in mehrere Sprachen übersetzt. Die Quelle der Wahrheit ist der englische Inhalt, während andere Sprachen abgeleitet werden und so etwas zurückbleiben. Jede Site-Sprache erhält eine eigene vollständige inhaltliche Inhaltsverzeichnis und eine Übersetzungstabellendatei. Sprachen werden mit ihrem internationalen 2-Buchstaben-Sprachcode identifiziert. Der Haupt-Site-Inhalt befindet sich im content/<language code> (z. B. content/en ), und die Übersetzungstabelle ist eine TOML-Format-Datei in i18n<language code>.toml (z. B. i18n/en.toml ).
Der Beginn der Übersetzung ist ziemlich einfach:
Erstellen Sie eine vollständige Kopie des content/en -Verzeichnisses für Ihre Sprache. Zum Beispiel würden Sie content/en in content/fr kopieren, wenn Sie eine französische Übersetzung durchführen.
Aktualisieren Sie alle Links in Ihrem neuen Inhaltsverzeichnis, um auf Ihr Inhaltsverzeichnis und nicht auf den englischen Inhalt zu verweisen. Wenn Sie beispielsweise eine französische Übersetzung durchführen würden, würden Sie Links wie [a doc](/docs/a/b/c) in [a doc](/fr/docs/a/b/c) ändern.
Entfernen Sie alle aliases -Richtlinien im Vordergrund aller Inhaltsseiten. Aliase werden verwendet, wenn eine Seite an einen neuen Standort verschoben wird, sodass sie nicht wünschenswert für brandneue Inhalte sind.
Erstellen Sie eine Kopie der i18n/en.toml -Datei für Ihre Sprache. Zum Beispiel würden Sie i18n/en.toml auf i18n/fr.toml kopieren, wenn Sie eine französische Übersetzung durchführen. Diese Datei enthält den Text, der von der Site -Infrastruktur für Dinge wie Menüs und anderes Standardmaterial angezeigt wird.
Bearbeiten Sie die Datei hugo.toml , um Ihre neue Sprache aufzulisten. Suchen Sie nach dem Eintrag [languages] und fügen Sie einfach einen neuen Eintrag hinzu. Dies sagt dem Hugo -Site -Generator, dass er Ihre Inhalte verarbeiten soll.
Bearbeiten Sie die scripts/lint_site.sh und suchen Sie nach check_content . Fügen Sie einen weiteren Anruf hinzu, um Ihr neues Inhaltsverzeichnis check_content . Dies stellt sicher, dass die Lining -Regeln für Ihren neuen Inhalt gelten.
Bearbeiten Sie die Datei src/ts/lang.ts und fügen Sie Ihre neue Sprache hinzu. Dadurch wird Ihre Sprache zu der Sprachschalttaste hinzufügt, die auf vorläufig verfügbar ist.
Holen Sie sich einen ISTIO -Github -Administrator, um ein neues Wartungsteam für Ihre Sprache zu erstellen. Für Französisch wären dies WG - Docs Maintainers/French .
Bearbeiten Sie die CODEOWNERS und fügen Sie Einträge für Ihre Sprache hinzu, um dem neuen Team, das Sie als Eigentum an der übersetzten Inhalts- und Übersetzungstabellendatei erstellt haben, zu geben.
Sie können dann alle diese Änderungen begehen und die Inhalte und die Übersetzungsdatei rein inkrementell übersetzen. Wenn Sie die Website erstellen, finden Sie Ihren Inhalt unter <url>/<language code> . Sobald Sie beispielsweise alles eingemeldet haben, sollten Sie in der Lage sein, Ihren Inhalt unter https://preliminary.istio.io/fr zu erreichen, wenn Sie eine französische Übersetzung durchgeführt haben.
Sobald Ihre Übersetzung abgeschlossen ist und Sie bereit sind, sie für die Welt zu veröffentlichen, müssen Sie einige andere Änderungen vornehmen:
Bearbeiten Sie die layouts/index.redir . Suchen Sie nach translated sites und fügen Sie eine Zeile für Ihre Sprache hinzu. Dies führt dazu, dass Benutzer zum ersten Mal automatisch auf den für sie geeigneten übersetzten Inhalt umgeleitet werden. Für Französisch wäre dies:
/ /fr 302 Language=fr
Bearbeiten Sie FHE layouts/partials/headers.html . Wenn Sie nach switch-lang suchen, finden Sie die Definitionen für das Sprachauswahlmenü. Fügen Sie eine Zeile für Ihre neue Sprache hinzu.
Und das war's.
Wir haben eine Reihe von Schecks, um sicherzustellen, dass eine Reihe von Invarianten gewartet werden, um die Gesamtqualität der Website zu unterstützen. Zum Beispiel lehnen wir die Überprüfung unterbrochener Links nicht aus und führen die Schreibbuch -Überprüfung durch. Es gibt einige Dinge, die kaum systematisch durch die Automatisierung überprüfen können und erfordern, dass ein Mensch in einer Weile überprüft wird, um sicherzustellen, dass alles gut läuft.
Es ist eine gute Idee, diese Liste vor jeder wichtigen Veröffentlichung der Website zu durchlaufen:
Stellen Sie sicher, dass Verweise auf die ISTIO -Repos auf GitHub nicht Hardcode -Zweignamen. Suchen Sie nach allen Verwendungen von /release-1 oder /master in allen Markdown-Dateien und ersetzen Sie diejenigen mit {{<source_branch_name>}}, die einen Versionsnamen mit Versionsanwendungen erzeugen.
Überprüfen Sie die .spellige Datei für Wörter, die dort nicht drin sein sollten. Geben Sie insbesondere Namen ein. Typamen sollten nicht im Wörterbuch sein und stattdessen mit backticks angezeigt werden. Entfernen Sie die Einträge aus dem Wörterbuch und beheben Sie alle auftretenden Zauberprüfungsfehler.
Sicherstellen, dass eine ordnungsgemäße Kapitalisierung gewährleistet ist. Dokumenttitel müssen vollständig kapitalisiert werden (z. B. "Dies ist ein gültiger Titel"), während Abschnittsüberschriften nur die Erstbriefkapitalisierung verwenden sollten (z. B. "Dies ist eine gültige Überschrift").
Stellen Sie sicher, dass vorformatierte Textblöcke, in denen Dateien aus den IStio Github -Repos verweisen, die @@ Syntax verwenden, um Links zum Inhalt zu erstellen. Siehe hier für den Kontext.
