Kubernetes es posible gracias a la participación de la comunidad y la
documentación es vital para facilitar el acceso al proyecto.
Cualquiera puede contribuir en el proyecto de Kubernetes, tanto si acabas de
descubrir la plataforma como si lleves años involucrado. Tampoco importa si
eres desarrollador, usuario final o alguien que simplemente no soporta ver
errores tipográficos. ¡Cualquier contribución será bien recibida!
Para conocer más formas de involucrarse en la comunidad de Kubernetes o de
aprender sobre nosotros, visite la sección comunidad de Kubernetes.
Para obtener información cómo escribir documentación de Kubernetes,
consulte la guía de estilo.
Tipos de contribuidores
Kubernetes Member, un miembro de la organziación de Kubernetes que ha
firmado el CLA y contribuido al projecto.
Puedes consultar más información en el documento sobre los requisitos para ser
miembro de Kubernetes en el documento Community membership.
SIG Docs reviewer, un revisor del grupo de interés de documentación es
un miembro de la organización Kubernetes que tiene interés en revisar las
pull requests relacionadas con el site y la documentación. Para poder ser
revisor, un aprobador de SIG Docs debe añadirlo al grupo adecuado de GitHub y
al fichero OWNERS del contenido que está interesado en revisar.
SIG Docs approver, un aprobador del grupo de interés de documentación
es un miembro de la organización de Kubernetes con buena reputación y que ha
mostrado una compromiso continuado con el proyecto.
Un aprobador se responsabiliza de mergear las pull requests y publicar
contenido en nombre de la organización Kubernetes. Los aprobadores también
pueden representar a SIG Docs en la comunidad de Kubernetes en general.
Algunas de las responsabilidades de un aprobador de SIG Docs, como por ejemplo
coordinar una release, requieren un compromiso de tiempo significativo.
Cómo contribuir
La siguiente lista está organizada por el nivel de implicación con la comunidad,
desde las contribuciones que cualquiera puede hacer hasta las que requieren un
compromiso con el equipo de documentación y estar familiarizado con los procesos
de SIG Docs. Contribuir consistentemente a lo largo del tiempo puede ayudarte a
comprender algunas de las herramientas y decisiones organizativas que se han ido
tomando a lo largo del proyecto.
La lista no contiene todas las formas de contribución posibles, está pensada
para proporcionar un punto de partida.
Si quieres empezar a contribuir a la documentación de Kubernetes esta página y su temas enlazados pueden ayudarte a empezar. No necesitas ser un desarrollador o saber escribir de forma técnica para tener un gran impacto en la documentación y experiencia de usuario en Kubernetes! Todo lo que necesitas para los temas en esta página es una Cuenta en GitHub y un navegador web.
Si estas buscando información sobre cómo comenzar a contribuir a los repositorios de Kubernetes, entonces dirígete a las guías de la comunidad Kubernetes
Lo básico sobre nuestra documentación
La documentación de Kubernetes esta escrita usando Markdown, procesada y
desplegada usando Hugo. El código fuente está en GitHub accessible en git.k8s.io/website/.
La mayoría de la documentación en castellano está en /content/es/docs. Alguna de
la documentación de referencia se genera automática con los scripts del
directorio /update-imported-docs.
Puedes clasificar incidencias, editar contenido y revisar cambios de otros, todo ello
desde la página de GitHub. También puedes usar la historia embebida de GitHub y
las herramientas de búsqueda.
No todas las tareas se pueden realizar desde la interfaz web de GitHub, también
se discute en las guías de contribución a la documentación
intermedia y
avanzada
Participar en la documentación de los SIG
La documentación de Kubernetes es mantenida por el Special Interest Group (SIG) denominado SIG Docs. Nos comunicamos usando un canal de Slack, una lista de correo
y una reunión semana por video-conferencia. Siempre son bienvenidos nuevos
participantes al grupo. Para más información ver
Participar en SIG Docs.
Guías de estilo
Se mantienen unas guías de estilo con la información sobre las elecciones que cada comunidad SIG Docs ha realizado referente a gramática, sintaxis, formato del código fuente y convenciones tipográficas. Revisa la guía de estilos antes de hacer tu primera contribución y úsala para resolver tus dudas.
Los cambios en la guía de estilos se hacen desde el SIG Docs como grupo. Para añadir o proponer cambios añade tus comentarios en la agenda para las próximas reuniones del SIG Docs y participe en las discusiones durante la reunión. Revisa el apartado avanzado para más información.
Plantillas para páginas
Se usan plantillas para las páginas de documentación con el objeto de que todas tengan la misma presentación. Asegúrate de entender como funcionan estas plantillas y revisa el apartado Uso de plantillas para páginas. Si tienes alguna consulta, no dudes en ponerte en contacto con el resto del equipo en Slack.
Hugo shortcodes
La documentación de Kubernetes se transforma a partir de Markdown para obtener HTML usando Hugo. Hay que conocer los shortcodes estándar de Hugo, así como algunos que son personalizados para la documentación de Kubernetes. Para más información de como usarlos revisa Hugo shortcodes personalizados.
Múltiples idiomas
La documentación original está disponible en múltiples idiomas en /content/. Cada idioma tiene su propia carpeta con el código de dos letras determinado por el estándar ISO 639-1. Por ejemplo, la documentación original en inglés se encuentra en /content/en/docs/.
Para más información sobre como contribuir a la documentación en múltiples idiomas revisa "Localizar contenido"
Si te interesa empezar una nueva localización revisa "Localization".
Registro de incidencias
Cualquier persona con una cuenta de GitHub puede reportar una incidencia en la documentación de Kubernetes. Si ves algo erróneo, aunque no sepas como resolverlo, reporta una incidencia. La única excepción a la regla es si se trata de un pequeño error, como alguno que puedes resolver por ti mismo. En este último caso, puedes tratar de resolverlo sin necesidad de reportar una incidencia primero.
Cómo reportar una incidencia
En una página existente
Si ves un problema en una página existente en la documentación de Kubernetes ve al final de la página y haz clic en el botón Abrir un Issue. Si no estas autenticado en GitHub, te pedirá que te identifiques y posteriormente un formulario de nueva incidencia aparecerá con contenido pre-cargado.
Utilizando formato Markdown completa todos los detalles que sea posible. En los lugares en que haya corchetes ([ ]) pon una x en medio de los corchetes para representar la elección de una opción. Si tienes una posible solución al problema añádela.
Solicitar una nueva página
Si crees que un contenido debería añadirse, pero no estás seguro de donde debería añadirse o si crees que no encaja en las páginas que ya existen, puedes crear un incidente. También puedes elegir una página ya existente donde pienses que pudiera encajar y crear el incidente desde esa página, o ir directamente a https://github.com/kubernetes/website/issues/new/ y crearlo desde allí.
Cómo reportar correctamente incidencias
Para estar seguros que tu incidencia se entiende y se puede procesar ten en cuenta esta guía:
Usa la plantilla de incidencia y aporta detalles, cuantos más es mejor.
Explica de forma clara el impacto de la incidencia en los usuarios.
Mantén el alcance de una incidencia a una cantidad de trabajo razonable. Para problemas con un alcance muy amplio divídela en incidencias más pequeñas.
Por ejemplo, "Arreglar la documentación de seguridad" no es una incidencia procesable, pero "Añadir detalles en el tema 'Restringir acceso a la red'" si lo es.
Si la incidencia está relacionada con otra o con una petición de cambio puedes referirte a ella tanto por la URL como con el número de la incidencia o petición de cambio con el carácter # delante. Por ejemplo Introducido por #987654.
Se respetuoso y evita desahogarte. Por ejemplo, "La documentación sobre X apesta" no es útil o una crítica constructiva. El Código de conducta también aplica para las interacciones en los repositorios de Kubernetes en GitHub.
Participa en las discusiones de SIG Docs
El equipo de SIG Docs se comunica por las siguientes vías:
Únete al Slack de Kubernetes y entra al canal #sig-docs o #kubernetes-docs-es para la documentación en castellano. En Slack, discutimos sobre las incidencias de documentación en tiempo real, nos coordinamos y hablamos de temas relacionados con la documentación. No olvides presentarte cuando entres en el canal para que podamos saber un poco más de ti!
Participa en la video-conferencia semanal de SIG Docs, esta se anuncia en el canal de Slack y la lista de correo. Actualmente esta reunión tiene lugar usando Zoom, por lo que necesitas descargar el cliente Zoom o llamar usando un teléfono.
Para mejorar contenido existente crea una pull request(PR) después de crear un fork. Estos términos son específicos de GitHub. No es necesario conocer todo sobre estos términos porque todo se realiza a través del navegador web. Cuando continúes con la guía de contribución de documentación intermedia entonces necesitarás un poco más de conocimiento de la metodología Git.
Nota:
Desarrolladores de código de Kubernetes: Si estás documentando una nueva característica para una versión futura de Kubernetes, entonces el proceso es un poco diferente. Mira el proceso y pautas en Documentar una característica así como información sobre plazos.
Si ves algo que quieras arreglar directamente, simplemente sigue las instrucciones más abajo. No es necesario que reportes una incidencia (aunque de todas formas puedes).
Si quieres empezar por buscar una incidencia existente para trabajar puedes ir https://github.com/kubernetes/website/issues y buscar una incidencia con la etiqueta good first issue (puedes usar este atajo). Lee los comentarios y asegurate de que no hay una petición de cambio abierta para esa incidencia y que nadie a dejado un comentario indicando que están trabajando en esa misma incidencia recientemente (3 días es una buena regla). Deja un comentario indicando que te gustaría trabajar en la incidencia.
Elije que rama de Git usar
El aspecto más importante a la hora de mandar una petición de cambio es que rama usar como base para trabajar. Usa estas pautas para tomar la decisión:
Utiliza master para arreglar problemas en contenido ya existente publicado, o hacer mejoras en contenido ya existente.
Utiliza una rama de versión (cómo dev-release-1.36 para la versión release-1.36) para documentar futuras características o cambios para futuras versiones que todavía no se han publicado.
Utiliza una rama de características que haya sido acordada por SIG Docs para colaborar en grandes mejoras o cambios en la documentación existente, incluida la reorganización de contenido o cambios en la apariencia del sitio web.
Si todavía no estás seguro con que rama utilizar, pregunta en #sig-docsen Slack o atiende una reunión semanal del SIG Docs para aclarar tus dudas.
Enviar una petición de cambio
Sigue estos pasos para enviar una petición de cambio y mejorar la documentación de Kubernetes.
En la página que hayas visto una incidencia haz clic en el icono del lápiz arriba a la derecha.
Una nueva página de GitHub aparecerá con algunos textos de ayuda.
Si nunca has creado un copia del repositorio de documentación de Kubernetes te pedirá que lo haga.
Crea la copia bajo tu usuario de GitHub en lugar de otra organización de la que seas miembro. La copia generalmente tiene una URL como https://github.com/<username>/website, a menos que ya tengas un repositorio con un nombre en conflicto con este.
La razón por la que se pide crear una copia del repositorio es porque no tienes permisos para subir cambios directamente a rama en el repositorio original de Kubernetes.
Aparecerá el editor Markdown de GitHub con el fichero Markdown fuente cargado. Realiza tus cambios. Debajo del editor completa el formulario Propose file change. El primer campo es el resumen del mensaje de tu commit y no debe ser más largo de 50 caracteres. El segundo campo es opcional, pero puede incluir más información y detalles si procede.
Nota:
No incluyas referencias a otras incidencias o peticiones de cambio de GitHub en el mensaje de los commits. Esto lo puedes añadir después en la descripción de la petición de cambio.
Haz clic en Propose file change. El cambio se guarda como un commit en una nueva rama de tu copia, automáticamente se le asignará un nombre estilo patch-1.
La siguiente pantalla resume los cambios que has hecho pudiendo comparar la nueva rama (la head fork y cajas de selección compare) con el estado actual del base fork y la rama base (master en el repositorio por defecto kubernetes/website). Puedes cambiar cualquiera de las cajas de selección, pero no lo hagas ahora. Hecha un vistazo a las distintas vistas en la parte baja de la pantalla y si todo parece correcto haz clic en Create pull request.
Nota:
Si no deseas crear una petición de cambio puedes hacerlo más delante, solo basta con navegar a la URL principal del repositorio de Kubernetes website o de tu copia. La página de GitHub te mostrará un mensaje para crear una petición de cambio si detecta que has subido una nueva rama a tu repositorio copia.
La pantalla Open a pull request aparece. El tema de una petición de cambio es el resumen del commit, pero puedes cambiarlo si lo necesitas. El cuerpo está pre-cargado con el mensaje del commit extendido (si lo hay) junto con una plantilla. Lee la plantilla y llena los detalles requeridos, entonces borra el texto extra de la plantilla. Deja la casilla Allow edits from maintainers seleccionada. Haz clic en Create pull request.
Enhorabuena! Tu petición de cambio está disponible en Pull requests.
Después de unos minutos ya podrás pre-visualizar la página con los cambios de tu PR aplicados. Ve a la pestaña de Conversation en tu PR y haz clic en el enlace Details para ver el test deploy/netlify, localizado casi al final de la página. Se abrirá en la misma ventana del navegado por defecto.
Espera una revisión. Generalmente k8s-ci-robot sugiere unos revisores. Si un revisor te pide que hagas cambios puedes ir a la pestaña FilesChanged y hacer clic en el icono del lápiz para hacer tus cambios en cualquiera de los ficheros en la petición de cambio. Cuando guardes los cambios se creará un commit en la rama asociada a la petición de cambio.
Si tu cambio es aceptado, un revisor fusionará tu petición de cambio y tus cambios serán visibles en pocos minutos en la web de kubernetes.io.
Esta es solo una forma de mandar una petición de cambio. Si eres un usuario de Git y GitHub avanzado puedes usar una aplicación GUI local o la linea de comandos con el cliente Git en lugar de usar la UI de GitHub. Algunos conceptos básicos sobre el uso de la línea de comandos Git
cliente se discuten en la guía de documentación intermedia.
Revisar peticiones de cambio de documentación
Las personas que aún no son aprobadores o revisores todavía pueden revisar peticiones de cambio. Las revisiones no se consideran "vinculantes", lo que significa que su revisión por sí sola no hará que se fusionen las peticiones de cambio. Sin embargo, aún puede ser útil. Incluso si no deja ningún comentario de revisión, puede tener una idea de las convenciones y etiquetas en una petición de cambio y acostumbrarse al flujo de trabajo.
Por defecto el único filtro que se aplica es open, por lo que no puedes ver las que ya se han cerrado o fusionado. Es una buena idea aplicar el filtro cncf-cla: yes y para tu primera revisión es una buena idea añadir size/S o size/XS. La etiqueta size se aplica automáticamente basada en el número de lineas modificadas en la PR. Puedes aplicar filtros con las cajas de selección al principio de la página, o usar estos atajos solo para PRs pequeñas. Los filtros son aplicados con AND todos juntos, por lo que no se puede buscar a la vez size/S y size/XS en la misma consulta.
Ve a la pestaña Files changed. Mira los cambios introducidos en la PR, y si aplica, mira también los incidentes enlazados. Si ves un algún problema o posibilidad de mejora pasa el cursor sobre la línea y haz click en el símbolo + que aparece.
Puedes entonces dejar un comentario seleccionando Add single comment o Start a review. Normalmente empezar una revisión es la forma recomendada, ya que te permite hacer varios comentarios y avisar a propietario de la PR solo cuando tu revisión este completada, en lugar de notificar cada comentario.
Cuando hayas acabado de revisar, haz clic en Review changes en la parte superior de la página. Puedes ver un resumen de la revisión y puedes elegir entre comentar, aprobar o solicitar cambios. Los nuevos contribuidores siempre deben elegir Comment.
Gracias por revisar una petición de cambio! Cuando eres nuevo en un proyecto es buena idea solicitar comentarios y opiniones en las revisiones de una petición de cambio. Otro buen lugar para solicitar comentarios es en el canal de Slack #sig-docs.
## Escribir un artículo en el blog
Cualquiera puede escribir un articulo en el blog y enviarlo para revisión. Los artículos del blog no deben ser comerciales y deben consistir en contenido que se pueda aplicar de la forma más amplia posible a la comunidad de Kubernetes.
Para enviar un artículo al blog puedes hacerlo también usando el formulario Kubernetes blog submission form, o puedes seguir los siguientes pasos.
Revisa el formato Markdown en los artículos del blog existentes en el repositorio website.
Escribe tu artículo usando el editor de texto que prefieras.
En el mismo enlace que el paso 2 haz clic en botón Create new file. Pega el contenido de tu editor. Nombra el fichero para que coincida con el título del artículo, pero no pongas la fecha en el nombre. Los revisores del blog trabajarán contigo en el nombre final del fichero y la fecha en la que será publicado.
Cuando guardes el fichero, GitHub te guiará en el proceso de petición de cambio.
Un revisor de artículos del blog revisará tu envío y trabajará contigo aportando comentarios y los detalles finales. Cuando el artículo sea aprobado, se establecerá una fecha de publicación.
Envía un caso de estudio
Un caso de estudio destaca como organizaciones están usando Kubernetes para resolver problemas del mundo real. Estos se escriben en colaboración con el equipo de marketing de Kubernetes que está dirigido por la CNCF.
Cuando entiendas mejor las tareas mostradas en este tema y quieras formar parte del equipo de documentación de Kubernetes de una forma más activa lee la guía intermedia de contribución.
2 - Revisar cambios
Esta sección describe cómo revisar el contenido.
2.1 - Revisar pull requests
Cualquiera puede revisar una pull request de documentación. Visita la sección de pull requests
en el repositorio del sitio web de Kubernetes para ver las PRs abiertas.
Revisar pull requests de documentación es una excelente manera de presentarte a la comunidad de Kubernetes.
Te ayuda a conocer la base de código y a construir confianza con otros colaboradores.
Comenta sobre los aspectos positivos de las PRs, no solo sobre los cambios necesarios.
Sé empático y consciente de cómo puede ser recibida tu revisión.
Asume buena intención y haz preguntas aclaratorias.
Si eres un colaborador experimentado, considera trabajar en pareja (pairing) con nuevos colaboradores cuyo trabajo requiera cambios extensos.
Proceso de revisión
En general, revisa las pull requests en cuanto a contenido y estilo en español (o inglés según el idioma objetivo). La Figura 1 resume los pasos del
proceso de revisión. A continuación se detallan los pasos.
flowchart LR
subgraph fourth[Iniciar revisión]
direction TB
S[ ] -.-
M[Añadir comentarios] --> N[Revisar cambios]
N --> O[Nuevos colaboradores deben elegir Comment]
end
subgraph third[Seleccionar PR]
direction TB
T[ ] -.-
J[Leer descripción y comentarios]--> K[Previsualizar cambios en el build de Netlify]
end
A[Revisar lista de PRs abiertas]--> B[Filtrar PRs abiertas por etiqueta]
B --> third --> fourth
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,J,K,M,N,O grey
class S,T spacewhite
class third,fourth white
Filtra las PRs abiertas usando una o todas las siguientes etiquetas:
cncf-cla: yes (Recomendado): Las PRs enviadas por colaboradores que no hayan firmado el CLA
no se pueden fusionar. Consulta Firmar el CLA
para más información.
language/es (Recomendado): Filtra únicamente las PRs en idioma español.
size/<tamaño>: Filtra las PRs por un determinado tamaño. Si eres nuevo, comienza con PRs más pequeñas.
Además, asegúrate de que la PR no esté marcada como trabajo en progreso (work in
progress). Las PRs que utilizan la etiqueta work in progress aún no están listas para su revisión.
Una vez que hayas seleccionado una PR para revisar, comprende el cambio mediante los siguientes pasos:
Lee la descripción de la PR para entender los cambios realizados y lee los issues vinculados.
Lee los comentarios dejados por otros revisores.
Haz clic en la pestaña Files changed para ver los archivos y las líneas modificadas.
Previsualiza los cambios en la vista previa creada por Netlify desplazándote hasta la sección de comprobaciones de construcción
(build checks) en la parte inferior de la pestaña Conversation.
Aquí tienes una captura de pantalla (muestra el sitio de escritorio de GitHub; si estás revisando
en una tableta o teléfono inteligente, la interfaz web de GitHub es ligeramente diferente):
Para abrir la vista previa, haz clic en el enlace Details de la línea deploy/netlify en la
lista de comprobaciones.
Ve a la pestaña Files changed para comenzar tu revisión.
Haz clic en el símbolo + al lado de la línea que deseas comentar.
Completa los comentarios que tengas sobre la línea y haz clic en Add single comment (si solo tienes un comentario) o Start a review (si tienes múltiples comentarios por hacer).
Al finalizar, haz clic en Review changes en la parte superior de la página. Aquí puedes añadir
un resumen de tu revisión (¡y dejar algunos comentarios positivos para el colaborador!).
Utiliza siempre la opción "Comment".
Evita hacer clic en el botón "Request changes" al finalizar tu revisión. Si deseas bloquear una PR para que no se fusione antes de realizar cambios adicionales, puedes dejar un comentario "/hold".
Menciona la razón por la que estás aplicando la retención (hold) y opcionalmente especifica las condiciones bajo las cuales tú u otros revisores pueden removerla.
Evita hacer clic en el botón "Approve" al finalizar tu revisión. La mayoría de las veces se recomienda dejar un comentario "/approve".
Lista de verificación para la revisión
Al revisar, utiliza lo siguiente como punto de partida.
Idioma y gramática
¿Hay errores evidentes de idioma o gramática? ¿Existe una mejor manera de redactar algo?
Concéntrate en el idioma y la gramática de las partes de la página que el autor está cambiando. A menos que el autor tenga la intención clara de actualizar la página completa, no tiene la obligación de corregir todos los problemas de la página.
Cuando un PR actualiza una página existente, debes concentrarte en revisar las partes que se están actualizando. Ese contenido modificado debe revisarse para comprobar su precisión técnica y editorial.
Si encuentras errores en la página que no se relacionan directamente con lo que el autor intenta solucionar, debe tratarse como un issue separado (comprueba primero que no exista un issue previo al respecto).
Ten cuidado con las pull requests que mueven contenido. Si un autor renombra una página o combina dos páginas, nosotros (Kubernetes SIG Docs) generalmente evitamos pedirle que corrija cada pequeño detalle gramatical u ortográfico dentro del contenido movido.
¿Hay palabras complicadas o arcaicas que se puedan reemplazar por una palabra más simple?
¿Se utilizan palabras, términos o frases que puedan reemplazarse por una alternativa no discriminatoria?
¿La elección de palabras y sus mayúsculas cumplen con la guía de estilo?
¿Hay oraciones largas que podrían ser más cortas o menos complejas?
¿Hay párrafos largos que funcionarían mejor como una lista o una tabla?
Contenido
¿Existe contenido similar en otra parte del sitio de Kubernetes?
¿El contenido enlaza excesivamente a sitios externos, a proveedores individuales o a documentación que no es de código abierto?
Documentación
Algunas comprobaciones a considerar:
¿Este PR cambió o eliminó el título de una página, un slug/alias o un enlace de anclaje? Si es así,
¿Hay enlaces rotos como resultado de este PR? ¿Existe otra opción, como cambiar el título de la página
sin modificar el slug?
¿Los cambios se muestran correctamente en la vista previa de Netlify? Presta especial atención a las listas, bloques de código, tablas, notas e imágenes.
Infraestructura del sitio web
Para cambios que involucren el entorno de trabajo del sitio web (como actualizaciones de Hugo o del tema Docsy),
los Revisores deben pedir al autor de la PR que confirme que el sitio se construye sin errores en modo de producción, o verificarlo ellos mismos.
Esto es necesario porque las vistas previas automatizadas de Netlify pueden no detectar errores específicos en la transformación de recursos
o en la resolución de rutas que solo se activan durante una compilación de producción completa.
Los revisores pueden verificar la compilación utilizando uno de los siguientes métodos:
Basado en contenedores (recomendado): Garantiza la paridad del entorno sin necesidad de tener Hugo instalado localmente.
Nota:
El objetivo predeterminado container-serve se ejecuta en modo de desarrollo.
Para una compilación equivalente a producción, edita temporalmente el archivo Makefile y cambia
--environment development por --environment production en el objetivo container-serve, luego ejecuta:
make container-image
make container-serve
Hugo local mediante Make: Utiliza el objetivo del Makefile existente para una compilación de producción. Ten en cuenta que esto realiza una compilación completa y es más lento que servir el sitio.
make production-build
Comando directo de Hugo: La forma más rápida de realizar la compilación de producción sin servir el sitio.
hugo --gc --minify --templateMetrics --environment production
Verifica la salida
Una compilación exitosa mostrará una tabla de resumen:
| EN | ZH-CN | JA | ...
---+------+-------+-----+
Pages | 2601 | 2148 | 747 | ...
Built in 95753 ms
Environment: "production"
Si la compilación falla, verás registros explícitos de ERROR;
una falla como la de un shortcode o la transformación de un recurso se verá así:
ERROR render of "page" failed: "/src/layouts/shortcodes/cve-feed.html:3:14":
execute of template failed: template: shortcodes/cve-feed.html:3:14:
failed to transform "scss/main.scss" (text/x-scss): SCSS processing failed
Revisa la vista previa de Netlify para ver cómo se renderiza la falla en el sitio.
Si la compilación de producción falla, la PR no debe fusionarse hasta que el autor
solucione los errores de plantilla o transformación.
Blog
Los comentarios iniciales sobre las publicaciones del blog son bienvenidos a través de Google Docs o HackMD. Solicita aportes con anticipación desde el canal de Slack #sig-docs-blog.
Asegúrate de conocer también los artículos perdurables (evergreen)
y cómo decidir si un artículo es perdurable.
Los artículos de blog pueden contener citas directas y
estilo indirecto. Evita sugerir una nueva redacción para
cualquier cosa que se atribuya a alguien o que sea parte de un diálogo que haya ocurrido, incluso si consideras que la gramática del hablante original no era correcta.
Para estos casos, intenta también respetar la puntuación sugerida por el autor del artículo, a menos que sea evidentemente errónea.
Como proyecto, solo marcamos los artículos de blog como mantenidos (evergreen: true en el front matter) si el proyecto Kubernetes
está dispuesto a comprometerse a mantenerlos indefinidamente.
Algunos artículos de blog definitivamente lo merecen, y siempre marcamos nuestros anuncios de lanzamiento como perdurables (evergreen). Consulta con otros colaboradores si no estás seguro de cómo revisar sobre este punto.
La guía de contenido aplica incondicionalmente a los artículos de blog y a las PRs que los añaden. Ten en cuenta que algunas restricciones de la guía indican que solo son relevantes para la documentación; esas restricciones no aplican a los artículos de blog.
Ten cuidado con las ediciones triviales;
si ves un cambio que consideras trivial, señala esa política (sigue estando bien aceptar el cambio si realmente representa una mejora).
Anima a los autores que estén realizando correcciones de espacios en blanco a que lo hagan en
el primer commit de su PR, y luego añadan otros cambios sobre él. Esto facilita tanto las
fusiones como las revisiones. Presta especial atención a un cambio trivial que ocurra en un solo
commit junto con una gran cantidad de limpieza de espacios en blanco (y si ves eso, anima al
autor a corregirlo).
Como revisor, si identificas pequeños problemas con una PR que no son esenciales para el significado,
como errores tipográficos o espacios en blanco incorrectos, antepone nit:: a tus
comentarios. Esto le permite saber al autor que esa parte de tus comentarios no es crítica.
Si estás considerando aprobar un pull request y todos los comentarios restantes están
marcados como nit, puedes fusionar la PR de todos modos. En ese caso, a menudo es útil abrir
un issue sobre los nits restantes. Considera si puedes cumplir con los requisitos para marcar
ese nuevo issue como Good First Issue;
si puedes, son una buena fuente para nuevos colaboradores.
2.2 - Revisión para aprobadores y revisores
Los Revisores y
Aprobadores de SIG Docs realizan algunas tareas adicionales
al revisar un cambio.
Cada semana, un aprobador de documentación específico se ofrece como voluntario para clasificar y revisar pull requests.
Esta persona es el "PR Wrangler" de la semana. Consulta el
PR Wrangler scheduler
para obtener más información. Para convertirte en PR Wrangler, asiste a la reunión semanal de SIG Docs
y postúlate. Incluso si no estás en el calendario de la semana actual,
aún puedes revisar pull requests (PRs) que no estén bajo revisión activa.
Además de la rotación, un bot asigna revisores y aprobadores
para la PR en función de los propietarios (owners) de los archivos afectados.
Todo lo descrito en Revisar una pull request
aplica aquí, pero los Revisores y Aprobadores también deben hacer lo siguiente:
Usar el comando de Prow /assign para asignar un revisor específico a una PR según sea necesario. Esto es de suma importancia cuando se trata de solicitar una revisión técnica a los colaboradores del código.
Nota:
Consulta el campo reviewers en el front-matter en la parte superior de un archivo Markdown para ver quién puede
proporcionar la revisión técnica.
Asegurarse de que la PR siga las guías de Contenido
y Estilo; enlaza al autor con la parte
relevante de la(s) guía(s) si no lo hace.
Utilizar la opción Request Changes de GitHub cuando sea aplicable para sugerir cambios al autor de la PR.
Cambiar tu estado de revisión en GitHub utilizando los comandos de Prow /approve o /lgtm,
si se implementan tus sugerencias.
Hacer commits en la PR de otra persona
Dejar comentarios en la PR es útil, pero puede haber ocasiones en las que necesites hacer commits
directamente en la PR de otra persona.
No "tomes el control" de la PR de otra persona a menos que te lo pida explícitamente
o desees rescatar una PR abandonada desde hace mucho tiempo. Aunque pueda ser más rápido
a corto plazo, priva a la persona de la oportunidad de contribuir.
El proceso que utilices dependerá de si necesitas editar un archivo que
ya está dentro del alcance de la PR, o un archivo que la PR aún no ha tocado.
No puedes realizar commits en la PR de otra persona si se cumple cualquiera de las siguientes
condiciones:
Si el autor de la PR envió su rama directamente al repositorio
https://github.com/kubernetes/website/.
Solo un revisor con acceso de escritura (push access) puede realizar commits en la PR de otro usuario.
Nota:
Anima al autor a enviar su rama a su fork antes de abrir la PR la próxima vez.
El autor de la PR prohíbe explícitamente las ediciones por parte de los aprobadores.
Comandos de Prow para la revisión
Prow es
el sistema de CI/CD basado en Kubernetes que ejecuta trabajos contra las pull requests (PRs). Prow
permite comandos estilo chatbot para manejar acciones de GitHub en toda la
organización de Kubernetes, como añadir y eliminar etiquetas,
cerrar issues y asignar un aprobador. Ingresa los comandos de Prow como comentarios de GitHub
usando el formato /<nombre-del-comando>.
Los comandos de Prow más comunes que usan los revisores y aprobadores son:
Comandos de Prow para la revisión
Comando de Prow
Restricciones de Rol
Descripción
/lgtm
Miembros de la organización
Señala que has terminado de revisar una PR y estás satisfecho con los cambios.
/approve
Aprobadores
Aprueba una PR para su fusión (merge).
/assign
Cualquiera
Asigna a una persona para revisar o aprobar una PR.
/close
Miembros de la organización
Cierra un issue o PR.
/hold
Cualquiera
Añade la etiqueta do-not-merge/hold, indicando que la PR no se puede fusionar automáticamente.
Este filtro de GitHub
Issues encuentra los issues que podrían necesitar triaje.
Realizar la clasificación de un issue
Validar el issue
Asegúrate de que el issue sea sobre la documentación del sitio web. Algunos issues se pueden cerrar rápidamente respondiendo una pregunta
o dirigiendo a la persona a un recurso. Consulta la sección
Solicitudes de soporte o reportes de errores en el código para más detalles.
Evalúa si el issue tiene mérito.
Añade la etiqueta triage/needs-information si el issue no tiene suficiente
detalle para ser accionable o si la plantilla no está completada adecuadamente.
Cierra el issue si tiene tanto la etiqueta lifecycle/stale como triage/needs-information.
Añadir una etiqueta de prioridad (las Guías de Triaje de Issues
definen las etiquetas de prioridad en detalle)
Etiquetas de issues
Etiqueta
Descripción
priority/critical-urgent
Hacer esto de inmediato.
priority/important-soon
Hacer esto dentro de los próximos 3 meses.
priority/important-longterm
Hacer esto dentro de los próximos 6 meses.
priority/backlog
Aplazable indefinidamente. Hacer cuando haya recursos disponibles.
priority/awaiting-more-evidence
Marcador de posición para un issue potencialmente bueno para que no se pierda.
A tu discreción, asume la propiedad de un issue y envía una PR para él (especialmente si es rápido o se relaciona con un trabajo que ya estás realizando).
Los issues generalmente se abren y cierran rápidamente.
Sin embargo, a veces un issue está inactivo después de ser abierto.
Otras veces, un issue puede necesitar permanecer abierto durante más de 90 días.
Etiquetas de ciclo de vida de issues
Etiqueta
Descripción
lifecycle/stale
Después de 90 días sin actividad, un issue se marca automáticamente como obsoleto (stale). El issue se cerrará automáticamente si el ciclo de vida no se revierte manualmente usando el comando /remove-lifecycle stale.
lifecycle/frozen
Un issue con esta etiqueta no se volverá obsoleto después de 90 días de inactividad. Un usuario añade manualmente esta etiqueta a los issues que necesitan permanecer abiertos durante mucho más de 90 días, como aquellos con la etiqueta priority/important-longterm.
Manejo de tipos de issues especiales
SIG Docs encuentra los siguientes tipos de issues con la suficiente frecuencia como para documentar
cómo manejarlos.
Issues duplicados
Si un solo problema tiene uno o más issues abiertos, combínalos en un solo issue. Debes decidir qué issue mantener abierto (o
abrir uno nuevo), luego mover toda la información relevante y enlazar los issues relacionados.
Finalmente, etiqueta todos los demás issues que describan el mismo problema con
triage/duplicate y ciérralos. Tener un solo issue en el cual trabajar reduce la confusión
y evita el trabajo duplicado en el mismo problema.
Issues de enlaces rotos (Dead links)
Si el issue de enlace roto se encuentra en la documentación de la API o de kubectl, asígnales
/priority critical-urgent hasta que el problema se comprenda por completo. Asigna a todos los demás issues
de enlaces rotos /priority important-longterm, ya que deben corregirse manualmente.
Issues del blog
Esperamos que las entradas del Blog de Kubernetes se desactualicen
con el tiempo. Por lo tanto, solo mantenemos entradas de blog que tengan menos de un año de antigüedad.
Si un issue está relacionado con una entrada de blog que tiene más de un año,
generalmente debes cerrar el issue sin realizar la corrección.
Está bien hacer una excepción cuando haya una justificación relevante.
Solicitudes de soporte o reportes de errores en el código
Algunos issues de documentación son en realidad problemas con el código subyacente, o solicitudes de
asistencia cuando algo (por ejemplo, un tutorial) no funciona.
Para issues no relacionados con la documentación, cierra el issue con la etiqueta kind/support y un comentario
que dirija al solicitante a los canales de soporte (Slack, Stack Overflow) y, si es
relevante, al repositorio para presentar un issue por errores en las características (kubernetes/kubernetes
es un excelente lugar para comenzar).
Respuesta de muestra a una solicitud de soporte:
Este problema parece más una solicitud de soporte y menos
un problema específico de la documentación. Te animo a llevar
tu pregunta al canal `#kubernetes-users` en el
[Slack de Kubernetes](https://slack.k8s.io/). También puedes buscar
en recursos como
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
para obtener respuestas a preguntas similares.
También puedes abrir issues para la funcionalidad de Kubernetes en
[https://github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
Si se trata de un problema de documentación, vuelve a abrir este issue.
Respuesta de muestra a un reporte de error de código:
Esto parece más un problema con el código que un problema con
la documentación. Por favor, abre un issue en
[https://github.com/kubernetes/kubernetes/issues](https://github.com/kubernetes/kubernetes/issues).
Si se trata de un problema de documentación, vuelve a abrir este issue.
Squashing
Como aprobador, cuando revisas pull requests (PRs), hay varios casos
en los que podrías hacer lo siguiente:
Aconsejar al colaborador que combine (squash) sus commits.
Hacer squash de los commits por el colaborador.
Aconsejar al colaborador que aún no haga squash.
Evitar el squash.
Aconsejar a los colaboradores que hagan squash: Es posible que un nuevo colaborador no sepa que debe hacer
squash de sus commits en sus pull requests (PRs). Si este es el caso, aconséjale que lo haga, proporciónale enlaces a
información útil y ofrécele ayuda
si la necesita. Algunos enlaces útiles:
GitHub Workflow, incluyendo diagramas, para desarrolladores.
Hacer squash de commits por los colaboradores: Si un colaborador tiene dificultades para hacer
squash de sus commits o hay presión de tiempo para fusionar una PR, puedes realizar el
squash por él:
En la PR, si el colaborador permite que los mantenedores gestionen la PR, puedes hacer
squash de sus commits y actualizar su fork con el resultado. Antes de hacer squash,
aconséjale que guarde y envíe (push) sus últimos cambios a la PR. Después de hacer
squash, aconséjale que traiga (pull) el commit combinado a su clon local.
Puedes hacer que GitHub realice el squash de los commits utilizando una etiqueta para que Tide / GitHub
realice el squash, o haciendo clic en el botón Squash commits cuando fusiones la PR.
Aconsejar a los colaboradores evitar hacer squash
Si un commit hace algo defectuoso o no recomendable, y el último commit revierte este
error, no hagas squash de los commits. Aunque la pestaña "Files changed" en la PR en
GitHub y la vista previa de Netlify se vean bien, fusionar esta PR podría crear conflictos de
rebase o merge para otras personas. Intervén como creas conveniente para evitar ese
riesgo para otros colaboradores.
Nunca hacer squash
Si estás lanzando una localización o publicando la documentación para una nueva versión
y estás fusionando una rama que no proviene del fork de un usuario, nunca hagas squash
de los commits. No hacer squash es esencial porque debes mantener el historial de
commits de esos archivos.
3 - Cómo escribir documentación
Los temas de esta sección proporcionan información sobre como escribir,
formatear y organizar el contenido de la documentación de Kubernetes.
También se explican las funciones, templates, variables y otras configuraciones
de Hugo utilizadas para generar y dar formato a
kubernetes.io.
4 - Documentación de referencia
Gran parte de la documentación de referencia de Kubernetes se genera a
partir del propio código fuente de Kubernetes utilizando scripts.
Los temas de esta sección documentan cómo generar este tipo de contenido.
5 - Contribuir a la documentación de Kubernetes en español
¡Bienvenido(a)!
En esta página encontrarás información sobre convenciones utilizadas en la documentación en castellano y un glosario de términos con sus traducciones.
