istio.io
1.0.0
| Sitio | Estado |
|---|---|
| istio.io | |
| preliminar.istio.io | |
| Archive.istio.io |
Este repositorio contiene el código fuente para istio.io y preliminar.istio.io.
Consulte el archivo Istio ReadMe principal para conocer el proyecto Istio general y cómo ponerse en contacto con nosotros. Para aprender cómo puede contribuir a cualquiera de los componentes de Istio, consulte las pautas de contribución de Istio.
Para aprender a editar y construir el contenido de este repositorio, consulte las páginas de creación y edición.
Istio mantiene dos variaciones de su sitio público.
Istio.io es el sitio principal, que muestra documentación para la versión actual del producto. istio.io/archive contiene instantáneas de la documentación para lanzamientos anteriores del producto. Esto es útil para los clientes que todavía usan estas versiones anteriores.
preliminar.istio.io contiene la documentación actualizada activamente para la próxima versión del producto.
El usuario puede navegar trivialmente entre las diferentes variaciones del sitio utilizando el menú Gear en la parte superior derecha de cada página. Ambos sitios están alojados en Netlify.
Los cambios en la documentación se comprometen principalmente con la rama maestra de Istio.io. Los cambios comprometidos con esta rama se reflejan automáticamente en preliminar.istio.io.
El contenido de Istio.io está tomado de la última rama de lanzamiento-xxx. La rama específica que se utiliza está determinada por la configuración del proyecto Istio.io Netlify.
La verificación de las actualizaciones de la rama maestra actualizará automáticamente preliminar.istio.io, y solo se reflejará en istio.io la próxima vez que se cree una versión, que puede ser varias semanas en el futuro. Si desea que algunos cambios se reflejen inmediatamente en Istio.io, debe verificar sus cambios tanto en la rama maestra como en la rama de lanzamiento actual (nombrado release-<MAJOR>.<MINOR> como release-1.7 ).
Este proceso puede ser atendido automáticamente por nuestra infraestructura. Si envía un PR a la rama maestra y anota el PR con la etiqueta cherrypick/release-<MAJOR>.<MINOR> , tan pronto como su PR se fusione en Master, se fusionará en la rama de liberación especificada.
Estos son los pasos necesarios para crear una nueva versión de documentación. Supongamos que la versión actual de Istio es 1.6 y desea introducir 1.7 que ha estado en desarrollo.
Corre make prepare-1.7.0 , y eso es todo. Esto atraerá los últimos documentos de referencia de la nueva rama de origen ISTIO en la carpeta content/en/docs/reference .
Para una carrera en seco antes del lanzamiento oficial, ejecute make release-1.7.0-dry-run , que solo creará una nueva rama release-1.7-dry-run y no tocará ninguna otra rama.
El día del lanzamiento, Run make release-1.7.0 . Este objetivo de marca cambiará algunas variables en master y release-1.6 , y creará una nueva rama release-1.7 para la nueva versión.
Vaya al proyecto Istio.io en Netlify y haga lo siguiente:
Cambie la rama que se construye a partir de la rama de la versión anterior a la nueva rama de lanzamiento, en este caso, release-1.7 (o release-1.7-dry-run según corresponda).
Seleccione la opción para activar una reconstrucción inmediata y una redistribución.
Una vez que se realice el despliegue, explore istio.io y asegúrese de que todo se vea bien.
Vaya al motor de búsqueda personalizado de Google y haga lo siguiente:
Descargue el archivo de contexto Istio.io CSE desde la pestaña Avanzada.
Agregue un nuevo FACETItem en la parte superior del archivo que contiene el número de versión de la versión anterior. En este caso, esto sería V1.6 .
Cargue el archivo de contexto CSE actualizado al sitio.
En la sección Configuración, agregue un nuevo sitio que cubra el directorio de archivo de la versión anterior. En este caso, la URL del sitio sería istio.io/v1.6/* . Establezca la etiqueta de este sitio en el nombre del elemento facetado creado anteriormente ( V1.6 en este caso).
Unos días antes del lanzamiento del parche, los gerentes de lanzamiento deben notificar al Doc WG que la versión se construye y está comenzando su prueba de calificación de larga duración. En este momento, mueva las pruebas de automatización de doc para usar la nueva versión para verificar los pases de pruebas de documentos automatizados.
Para pasar a una nueva versión (asegúrese de estar en la rama de lanzamiento del parche):
Ejecutar go get istio.io/istio@AXY && go mod tidy .
Crea un PR con el go.* Cambios.
Crear una nueva versión de parche implica modificar algunos archivos:
Editar data/args.yml y cambiar el campo full_version a "AXY" . Esto solo se necesita para un parche de la versión current .
Complete la nota de lanzamiento para la versión editando el content/en/news/releases/AXx/announcing-AXY/index.md . Aquí es donde describe los cambios en el lanzamiento. Mire otros archivos existentes, por ejemplo, contenido y diseño.
Ejecute make update_ref_docs para obtener los últimos documentos de referencia. Normalmente, esto solo se necesita para un parche de la versión current . Si es necesario en una versión anterior, consulte Actualizar un archivo.
Si la versión archivada en una rama más nueva (p. Ej., release-1.7:archive/v1.6 ) debe actualizarse debido a los cambios en la rama de la versión anterior ( release-1.6 en este caso), puede ejecutar make build-old-archive-1.6.0 en la rama master , que volverá a release-1.6 y lo sustituirá para el archivo anterior en la rama master . Si esta actualización debe reflejarse en Istio.io, el PR puede ser recogido a la rama para la versión current .
Las transmisiones de lanzamiento que comienzan con release-1.6 contienen pruebas para el contenido de prueba. Cada lanzamiento prueba contra una versión/confirmación de Istio particular. Cuando el equipo de lanzamiento tiene una construcción, 1.xy , lista para sus pruebas de larga duración, deberían venir al equipo de documentos para que las pruebas de esa publicación sean ejecutadas contra la construcción.
Hay dos tipos de compilaciones, public y private . Las compilaciones normales de desarrollo y lanzamiento se construyen a partir de nuestros reposuras públicas y tienen imágenes en un repositorio de acceso público y se consideran public . Las construcciones Private son aquellas en las que no podemos revelar mucho antes del lanzamiento. Por lo general, es un aviso anticipado de que se realizará un lanzamiento en dos semanas para CVE. Como no podemos revelar nada antes del lanzamiento real, la fuente y las imágenes construidas están en reposos privados. Como la fuente y las imágenes son privadas, en realidad no podemos movernos a ellas hasta que sean lanzados públicamente y, por lo tanto, no hay pruebas tempranas del lanzamiento en Istio.io. La diferencia para las construcciones private es que las imágenes con las que probamos nunca se crearon en el repositorio public de GCR.io, por lo que en ese caso usamos las imágenes Docker.io. Uno puede preguntar por qué no siempre usamos las imágenes de lanzamiento de Docker.io. Como queremos probar las construcciones public antes de que sean lanzadas, las imágenes aún no existen en Docker.io.
Para construcciones públicas:
go get istio.io/istio@commit && go mod tidy .Para construcciones privadas (esto se hace después de la lanzamiento de la construcción):
go get istio.io/[email protected] && go mod tidy .Para ambas construcciones, queremos verificar que el Hub/Etiqueta sea correcto en Makefile.Core.MK (cambian según si usan las compilaciones privadas o públicas). Busque la sección similar a:
# 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
Para las construcciones públicas, el export HUB/TAG no estaría sin comodidad y tendrá valores correctos. Para construcciones privadas, o para la rama master , el Hub no se comentaría.
Finalmente, cree y envíe un PR con los cambios y uno puede ver los resultados de la prueba en el PR. Normalmente, el PR realmente no se fusionará hasta que se lance el lanzamiento (a veces hay múltiples compilaciones para un lanzamiento).
Muchos documentos en el sitio ISTIO demuestran características utilizando comandos que pueden continuar funcionando a medida que Istio evoluciona de la versión a la liberación. Para garantizar que las instrucciones documentadas se mantengan al día con la menor cantidad de pruebas manuales continuas posible, hemos creado un marco para automatizar las pruebas de estos documentos.
Cada página de istio.io que se puede probar incluye una indicación PAGE TEST en el título de la página. Por ejemplo:
Una marca de verificación verde indica que una prueba automatizada está disponible para la página. La página está actualizada y funciona como se documenta.
Una X gris, por otro lado, significa que todavía no hay una prueba automatizada disponible para la página. ¡Agradecemos si desea ayudar a crear uno! Nuestro objetivo es eventualmente tener una prueba automatizada para cada documento comprobable publicado en el sitio de Istio.
Consulte el ReadMe de las pruebas para obtener más información.
El sitio se traduce en varios idiomas. La fuente de la verdad es el contenido inglés, mientras que otros idiomas se derivan y, por lo tanto, tienden a quedarse atrás ligeramente. Cada idioma del sitio obtiene su propio directorio de contenido totalmente autónomo y archivo de tabla de traducción. Los idiomas se identifican utilizando su código de idioma internacional de 2 letras. El contenido del sitio principal se encuentra en content/<language code> (por ejemplo content/en ), y la tabla de traducción es un archivo Toml-format en i18n<language code>.toml (por ejemplo, i18n/en.toml ).
Comenzar con la traducción es bastante simple:
Cree una copia completa de content/en Directory para su idioma. Por ejemplo, copiaría content/en a content/fr si estuviera haciendo una traducción al francés.
Actualice todos los enlaces en su nuevo directorio de contenido para apuntar a su directorio de contenido en lugar del contenido en inglés. Por ejemplo, si estuviera haciendo una traducción al francés, cambiaría enlaces como [a doc](/docs/a/b/c) a [a doc](/fr/docs/a/b/c) .
Elimine todas las directivas de aliases en la materia frontal de todas las páginas de contenido. Los alias se usan al mover una página a una nueva ubicación, por lo que no son deseables para contenido nuevo.
Cree una copia del archivo i18n/en.toml para su idioma. Por ejemplo, copiaría i18n/en.toml a i18n/fr.toml si estuviera haciendo una traducción al francés. Este archivo contiene el texto que muestra la infraestructura del sitio para cosas como menús y otro material estándar.
Edite el archivo hugo.toml para enumerar su nuevo idioma. Busque la entrada [languages] y simplemente agregue una nueva entrada. Esto le dice al generador del sitio Hugo que procese su contenido.
Edite los scripts/lint_site.sh y busque check_content . Agregue otra llamada a check_content para su nuevo directorio de contenido. Esto asegura que las reglas de pelusa se apliquen a su nuevo contenido.
Edite el archivo src/ts/lang.ts y agregue su nuevo idioma. Esto agregará su idioma al botón de alternancia de idioma que está disponible en preliminar.istio.io y lo hará para que su idioma sea compatible en el menú de selección de idiomas.
Obtenga un administrador de Istio Github para crear un nuevo equipo de mantenimiento para su idioma. Para el francés, esto sería WG - Docs Maintainers/French .
Edite los CODEOWNERS de archivos y agregue entradas para su idioma para dar al nuevo equipo que ha creado la propiedad sobre el archivo de la tabla de contenido y traducción traducido.
Luego puede cometer todos estos cambios y puede comenzar a traducir el contenido y el archivo de traducción de manera puramente incremental. Cuando cree el sitio, encontrará su contenido en <url>/<language code> . Por ejemplo, una vez que haya registrado todo, debería poder llegar a su contenido en https://preliminary.istio.io/fr si estaba haciendo una traducción al francés.
Una vez que su traducción esté completa y esté listo para publicarla en el mundo, hay algunos otros cambios que debe hacer:
Edite los layouts/index.redir . Busque translated sites y agregue una línea para su idioma. Esto hará que los usuarios vengan al sitio por primera vez que se redirigan automáticamente al contenido traducido adecuado para ellos. Para el francés, esto sería:
/ /fr 302 Language=fr
Editar layouts/partials/headers.html . Busque switch-lang y encontrará las definiciones para el menú de selección de idiomas. Agregue una línea para su nuevo idioma.
Y eso es todo.
Tenemos una serie de cheques para garantizar que se mantengan varios invariantes para ayudar a la calidad general del sitio. Por ejemplo, no permitimos verificar en enlaces rotos y hacemos la verificación de hechizos. Hay algunas cosas que son difíciles de verificar sistemáticamente a través de la automatización y, en cambio, requieren que un humano revise en mucho tiempo para garantizar que todo esté funcionando bien.
Es una buena idea ejecutar esta lista antes de cada lanzamiento importante del sitio:
Asegúrese de que las referencias a los Repos de Istio en GitHub no tengan en cuenta los nombres de ramas. Busque cualquier uso de /release-1 o /master en todos los archivos de Markdown y reemplace aquellos con {{<fuente_branch_name>}} en su lugar, que produce un nombre de rama apropiado para la versión.
Revise el archivo .spelling de palabras que no deberían estar allí. Los nombres de tipo en particular tienden a arrastrarse aquí. Los nombres de tipo no deben estar en el diccionario y, en su lugar, deben mostrarse con backticks . Elimine las entradas del diccionario y corrija cualquier error de verificación de hechizos que surjan.
Asegurar una capitalización adecuada. Los títulos de documentos deben estar completamente capitalizados (por ejemplo, "este es un título válido"), mientras que los encabezados de sección deben usar solo la capitalización de la primera letra (por ejemplo, "este es un encabezado válido").
Asegúrese de que los bloqueos de texto preformanados que hacen referencia a los archivos del Istio GitHub Repos usen la sintaxis @@ para producir enlaces al contenido. Vea aquí para el contexto.
