istio.io
1.0.0
| Site | Statut |
|---|---|
| Istio.io | |
| préliminaire.istio.io | |
| archive.istio.io |
Ce référentiel contient le code source pour Istio.io et preliminary.istio.io.
Veuillez consulter le fichier principal Istio Readme pour en savoir plus sur le projet global ISTIO et comment nous contacter. Pour savoir comment vous pouvez contribuer à l'un des composants Istio, veuillez consulter les directives de contribution ISTIO.
Pour apprendre à modifier et à construire le contenu de ce repo, veuillez vous référer à la création et à la modification des pages.
Istio maintient deux variations de son site public.
Istio.io est le site principal, montrant la documentation de la version actuelle du produit. Istio.io/archive contient des instantanés de la documentation pour les versions précédentes du produit. Ceci est utile pour les clients qui utilisent toujours ces versions plus anciennes.
Preliminary.istio.io contient la documentation activement mise à jour pour la prochaine version du produit.
L'utilisateur peut naviguer trivialement entre les différentes variations du site à l'aide du menu Gear en haut à droite de chaque page. Les deux sites sont hébergés sur Netlify.
Les changements de documentation sont principalement attachés à la branche principale d'Istio.io. Les modifications engagées dans cette branche se reflètent automatiquement sur préliminaire.istio.io.
Le contenu d'Istio.io est tiré de la dernière branche de version-xxx. La branche spécifique utilisée est déterminée par la configuration du projet Istio.io Netlify.
La vérification des mises à jour de la branche maître mettra automatiquement à jour Preliminary.istio.io, et ne sera reflétée que sur Istio.io la prochaine fois qu'une version sera créée, ce qui peut être plusieurs semaines à l'avenir. Si vous souhaitez que certaines modifications soient immédiatement reflétées sur Istio.io, vous devez vérifier vos modifications à la fois en branche maître et à la branche de version actuelle (nommé release-<MAJOR>.<MINOR> comme release-1.7 ).
Ce processus peut être pris en charge automatiquement par notre infrastructure. Si vous soumettez un PR à la branche Master et annotez le PR avec l'étiquette cherrypick/release-<MAJOR>.<MINOR> , alors dès que votre PR sera fusionné, il sera fusionné dans la branche de version spécifiée.
Voici les étapes nécessaires pour créer une nouvelle version de documentation. Supposons que la version actuelle d'Istio est 1.6 et que vous souhaitez introduire 1.7 qui a été en cours de développement.
Run make prepare-1.7.0 , et c'est tout. Cela saisira les derniers documents de référence de la nouvelle branche Istio Source dans le dossier content/en/docs/reference .
Pour une course sèche avant la sortie officielle, make release-1.7.0-dry-run , qui ne créera qu'une nouvelle branche release-1.7-dry-run et ne touchera aucune autre branche.
Le jour de la sortie, Run make release-1.7.0 . Cette cible Make modifiera certaines variables dans master et release-1.6 et créera une nouvelle branche release-1.7 pour la nouvelle version.
Accédez au projet Istio.io sur Netlify et procédez comme suit:
Changez la branche qui est construite à partir de la succursale de la version précédente vers la nouvelle branche de la version, dans ce cas, release-1.7 (ou release-1.7-dry-run le cas échéant).
Sélectionnez l'option pour déclencher une reconstruction immédiate et un redéploiement.
Une fois le déploiement terminé, parcourez Istio.io et assurez-vous que tout semble bon.
Accédez au moteur de recherche personnalisé Google et procédez comme suit:
Téléchargez le fichier de contexte Istio.io CSE à partir de l'onglet Avancé.
Ajoutez un nouveau FACETITEM en haut du fichier contenant le numéro de version de la version précédente. Dans ce cas, ce serait V1.6 .
Téléchargez le fichier de contexte CSE mis à jour sur le site.
Dans la section Configuration, ajoutez un nouveau site qui couvre le répertoire des archives de la version précédente. Dans ce cas, l'URL du site serait istio.io/v1.6/* . Définissez l'étiquette de ce site sur le nom de l'élément de facette créé ci-dessus ( V1.6 dans ce cas).
Quelques jours avant la version du patch, les gestionnaires de version doivent informer le DOC WG que la version est construite et commence son test de qualification de longue date. À l'heure actuelle, déplacez les tests d'automatisation de DOC pour utiliser la nouvelle version pour vérifier les passes de tests DOC automatisées.
Pour passer à une nouvelle version (assurez-vous que vous êtes dans la branche de libération du patch):
Run go get istio.io/istio@AXY && go mod tidy .
Créez un PR avec le go.* Modifie.
La création d'une nouvelle version de patch consiste à modifier quelques fichiers:
Modifiez data/args.yml et modifiez le champ full_version en "AXY" . Ceci n'est nécessaire que pour un patch de la version current .
Terminez la note de version de la version en modifiant le content/en/news/releases/AXx/announcing-AXY/index.md . C'est là que vous décrivez les changements dans le communiqué. Veuillez consulter d'autres fichiers existants, par exemple le contenu et la mise en page.
Exécutez make update_ref_docs pour obtenir les derniers documents de référence. Normalement, cela n'est nécessaire que pour un patch de la version current . Si nécessaire dans une version antérieure, voir la mise à jour d'une archive.
Si la version archivée dans une succursale plus récente (par exemple, release-1.7:archive/v1.6 ) doit être mise à jour en raison des modifications de l'ancienne branche de version ( release-1.6 dans ce cas), vous pouvez exécuter make build-old-archive-1.6.0 dans la branche master , qui reviendra release-1.6 et le remplacera pour la branche master précédente. Si cette mise à jour doit être reflétée dans Istio.io, le PR peut être sélectionné en cerise dans la branche pour la version current .
Les flux de version commençant par release-1.6 contiennent des tests pour le contenu de test. Chaque publication teste une version / engagement ISTIO particulier. Lorsque l'équipe de sortie a une construction, 1.xy , prête pour ses tests de longue durée, ils devraient venir dans l'équipe DOCS pour que les tests pour cette version commencent à fonctionner contre la construction.
Il existe deux types de constructions, public et private . Les versions normales de développement et de version sont construites à partir de nos références publiques et ont des images dans un référentiel accessible au public et sont considérés comme public . Les constructions Private sont celles où nous ne pouvons pas révéler beaucoup avant la libération. En règle générale, il s'agit d'un avis préalable qu'une libération se produira dans deux semaines pour CVE. Étant donné que nous ne pouvons rien révéler avant la version réelle, la source et les images construites sont dans des références privées. Comme la source et les images sont privées, nous ne pouvons pas réellement y emménager jusqu'à ce qu'ils soient publiquement libérés, et il n'y a donc pas de test précoce de la version dans Istio.io. La différence pour les versions private est que les images contre lesquelles nous testons n'ont jamais été créées dans le référentiel public GCR.IO, donc dans ce cas, nous utilisons les images Docker.io. On peut demander pourquoi nous n'utilisons pas toujours les images de version de docker.io. Comme nous voulons tester les versions public avant leur sortie, les images n'existent pas encore sur docker.io.
Pour les constructions publiques:
go get istio.io/istio@commit && go mod tidy .Pour les constructions privées (ceci est fait après la libération de la construction):
go get istio.io/[email protected] && go mod tidy .Pour les deux builds, nous voulons vérifier que le hub / tag est correct dans makefile.core.mk (ils changent en fonction de l'utilisation des versions privées ou publiques). Recherchez la section similaire à:
# 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
Pour les versions publiques, le export HUB/TAG serait non émis et aurait des valeurs correctes. Pour les constructions privées, ou la branche master , le centre serait non en pavé.
Enfin, créez et soumettez un PR avec les modifications et on peut voir les résultats du test dans le PR. Normalement, le PR ne fusionnera pas avant la sortie de la version (parfois il y a plusieurs versions pour une version).
De nombreux documents sur le site Istio montrent des fonctionnalités utilisant des commandes qui peuvent continuer ou non à fonctionner à mesure que Istio évolue de la version à la libération. Pour garantir que les instructions documentées restent à jour avec le moins de tests manuels continus possible, nous avons créé un cadre pour automatiser les tests de ces documents.
Chaque page sur Istio.io qui peut être testée comprend une indication PAGE TEST sous le titre de la page. Par exemple:
Une vérification verte indique qu'un test automatisé est disponible pour la page. La page est à jour et fonctionne comme documentée.
Un X gris, en revanche, signifie qu'il n'y a pas encore de test automatisé pour la page. Nous l'apprécierons si vous souhaitez aider à en créer un! Notre objectif est éventuellement de mettre en place un test automatisé pour chaque document testable publié sur le site Istio.
Voir les tests Readme pour plus d'informations.
Le site est traduit en plusieurs langues. La source de vérité est le contenu anglais, tandis que d'autres langues sont dérivées et ont donc tendance à être légèrement en retard. Chaque langue du site obtient son propre répertoire de contenu entièrement autonome et fichier de table de traduction. Les langues sont identifiées à l'aide de leur code de langue international à 2 lettres. Le contenu du site principal est situé dans content/<language code> (par exemple content/en ), et la table de traduction est un fichier Toml-Format dans i18n<language code>.toml (par exemple i18n/en.toml ).
Le début de la traduction est assez simple:
Créez une copie complète du répertoire content/en pour votre langue. Par exemple, vous copiez content/en en content/fr si vous faisiez une traduction française.
Mettez à jour tous les liens de votre nouveau répertoire de contenu pour pointer vers votre répertoire de contenu plutôt que le contenu anglais. Par exemple, si vous faisiez une traduction française, vous modifieriez des liens tels que [a doc](/docs/a/b/c) à [a doc](/fr/docs/a/b/c) .
Supprimez toutes les directives aliases dans le front-modèle de toutes les pages de contenu. Les alias sont utilisés pour déplacer une page vers un nouvel emplacement, ils ne sont donc pas souhaitables pour un tout nouveau contenu.
Créez une copie du fichier i18n/en.toml pour votre langue. Par exemple, vous copiez i18n/en.toml à i18n/fr.toml si vous faisiez une traduction française. Ce fichier contient le texte affiché par l'infrastructure du site pour des choses comme les menus et d'autres matériaux standard.
Modifiez le fichier hugo.toml pour répertorier votre nouvelle langue. Recherchez l'entrée [languages] et ajoutez simplement une nouvelle entrée. Cela indique au générateur de site Hugo de traiter votre contenu.
Modifiez le fichier scripts/lint_site.sh et recherchez check_content . Ajoutez un autre appel à check_content pour votre nouveau répertoire de contenu. Cela garantit que les règles de liaison s'appliquent à votre nouveau contenu.
Modifiez le fichier src/ts/lang.ts et ajoutez votre nouvelle langue. Cela ajoutera votre langue au bouton de basculement de la langue qui est disponible sur préliminaire.istio.io et le fera afin que votre langue soit prise en charge dans le menu de sélection des langues.
Obtenez un administrateur Istio GitHub pour créer une nouvelle équipe de mainteader pour votre langue. Pour le français, ce serait WG - Docs Maintainers/French .
Modifiez les CODEOWNERS de fichiers et ajoutez des entrées pour votre langue afin de donner à la nouvelle équipe que vous avez créée de propriété sur le fichier de table de contenu et de traduction traduit.
Vous pouvez ensuite commettre toutes ces modifications et vous pouvez commencer à traduire le contenu et le fichier de traduction de manière purement incrémentielle. Lorsque vous créez le site, vous trouverez votre contenu sur <url>/<language code> . Par exemple, une fois que vous avez tout vérifié, vous devriez pouvoir accéder à votre contenu à https://preliminary.istio.io/fr si vous faisiez une traduction française.
Une fois votre traduction terminée et que vous êtes prêt à le publier dans le monde, il y a quelques autres modifications que vous devez apporter:
Modifiez les layouts/index.redir . Recherchez translated sites et ajoutez une ligne pour votre langue. Cela amènera pour la première fois les utilisateurs sur le site pour être automatiquement redirigé vers le contenu traduit qui leur est adapté. Pour le français, ce serait:
/ /fr 302 Language=fr
Modifier les layouts/partials/headers.html . Recherchez switch-lang et vous trouverez les définitions du menu de sélection des langues. Ajoutez une ligne pour votre nouvelle langue.
Et c'est tout.
Nous avons mis en place un certain nombre de contrôles pour garantir un certain nombre d'invariants afin d'aider la qualité globale du site. Par exemple, nous interdisons la vérification des liens cassés et nous vérifions les orthographiques. Il y a certaines choses qui sont difficiles à vérifier systématiquement dans l'automatisation et nécessitent plutôt un humain pour examiner dans un certain temps pour s'assurer que tout se passe bien.
C'est une bonne idée de parcourir cette liste avant chaque version majeure du site:
Assurez-vous que les références aux références Istio sur GitHub ne sont pas des noms de branche Hardcode. Recherchez toutes les utilisations de /release-1 ou /master dans tous les fichiers Markdown et remplacez-les par {{<source_branch_name>}}, qui produit un nom de branche adapté à la version.
Passez en revue le fichier .Spelling pour les mots qui ne devraient pas y être. Les noms de type en particulier ont tendance à se glisser ici. Les noms de type ne doivent pas être dans le dictionnaire et doivent plutôt être affichés avec backticks . Retirez les entrées du dictionnaire et corrigez toutes les erreurs de vérification de l'orthographe qui émergent.
Assurer une capitalisation appropriée. Les titres de documents doivent être entièrement capitalisés (par exemple, "Ceci est un titre valide"), tandis que les en-têtes de section doivent utiliser uniquement la capitalisation de première lettre (par exemple "Ceci est un titre valide").
Assurez-vous que les blocs de texte préformatés qui référencent les fichiers des repos Istio GitHub utilisent la syntaxe @@ pour produire des liens vers le contenu. Voir ici pour le contexte.
