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.
La documentación de Kubernetes sigue el proceso de revisión de código de Kubernetes.
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.
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.
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.
El autor de la PR prohíbe explícitamente las ediciones por parte de los aprobadores.
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:
| 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. |
/hold cancel | Cualquiera | Elimina la etiqueta do-not-merge/hold. |
Para ver los comandos que puedes usar en una PR, consulta la Referencia de Comandos de Prow.
En general, SIG Docs sigue el proceso de clasificación de issues de Kubernetes y utiliza las mismas etiquetas.
Este filtro de GitHub Issues encuentra los issues que podrían necesitar triaje.
Validar el issue
triage/needs-information si el issue no tiene suficiente
detalle para ser accionable o si la plantilla no está completada adecuadamente.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)
| 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. |
help o good first issue | Adecuado para alguien con muy poca experiencia en Kubernetes o SIG Docs. Consulta Etiquetas Help Wanted y Good First Issue para más información. |
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).
Si tienes preguntas sobre cómo clasificar un issue, consulta en #sig-docs en Slack o en la
lista de correo de kubernetes-sig-docs.
Para añadir una etiqueta, deja un comentario en uno de los siguientes formatos:
/<etiqueta-a-añadir> (por ejemplo, /good-first-issue)/<categoría-de-etiqueta> <etiqueta-a-añadir> (por ejemplo, /triage needs-information o /language es)Para eliminar una etiqueta, deja un comentario en uno de los siguientes formatos:
/remove-<etiqueta-a-eliminar> (por ejemplo, /remove-help)/remove-<categoría-de-etiqueta> <etiqueta-a-eliminar> (por ejemplo, /remove-triage needs-information)En ambos casos, la etiqueta ya debe existir. Si intentas añadir una etiqueta que no existe, el comando se ignorará en silencio.
Para obtener una lista de todas las etiquetas, consulta la sección de Etiquetas del repositorio del sitio web. No todas las etiquetas son utilizadas por SIG Docs.
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.
| 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. |
SIG Docs encuentra los siguientes tipos de issues con la suficiente frecuencia como para documentar cómo manejarlos.
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.
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.
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.
Puedes enviar un enlace a las actualizaciones y mantenimiento de artículos como parte del mensaje que envíes cuando cierres la PR.
Está bien hacer una excepción cuando haya una justificación relevante.
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.
Como aprobador, cuando revisas pull requests (PRs), hay varios casos en los que podrías hacer lo siguiente:
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:
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:
Aconsejar a los colaboradores evitar hacer squash
Nunca hacer squash