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 - 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.
