Proceso de revisión de solicitudes de incorporación de cambios para los repositorios de documentos .NET

Algunos repositorios, incluidos los repositorios de .NET, no tienen habilitado el webhook "PR Merger", que combina automáticamente las solicitudes de incorporación de cambios menores. En este artículo se describe el proceso de revisión de solicitudes de incorporación de cambios para dichos repositorios. El proceso de revisión de solicitudes de incorporación de cambios se diseñó con estos objetivos:

• Publicar contenido de alta calidad de nuestro equipo, miembros del equipo de producto y miembros de la comunidad.
• Proporcionar comentarios oportunos y útiles a los autores de manera coherente
• Facilitar el debate entre autores y revisores

Los procesos continúan evolucionando a medida que los equipos innovan y cuando la plataforma crece.

Revisores

Uno de los miembros del equipo de contenido revisa cada solicitud de incorporación de cambios. Los miembros del equipo de contenido pueden solicitar una revisión de los miembros específicos del equipo de producto para comprobar la exactitud técnica. El equipo de contenido utiliza la característica de propiedad de código de GitHub para solicitar automáticamente revisiones de los miembros del equipo de contenido. Como parte de este proceso, el revisor puede etiquetar a otros miembros del equipo para revisar solicitudes de incorporación de cambios internas. Los miembros del equipo ven las revisiones solicitadas por los miembros del equipo y los miembros de la comunidad en la misma cola.

Los miembros de la comunidad pueden revisar solicitudes de incorporación de cambios y proporcionar comentarios también. Sin embargo, al menos un miembro del equipo de contenido principal debe aprobar cualquier solicitud de incorporación de cambios antes de fusionarla.

Proceso de revisión

Las revisiones siguen una de las tres rutas basándose en la solicitud de incorporación de cambios:

• Solicitudes de incorporación de cambios pequeños: estas solicitudes de cambios pequeños son correcciones de errores mínimos: errores tipográficos, vínculos rotos, pequeños cambios de código o cambios similares.
• Contribuciones importantes: las contribuciones importantes son ediciones significativas de un artículo existente, artículos nuevos o modificaciones de varios artículos.
• Trabajo en curso: los autores pueden abrir un borrador de solicitud de incorporación de cambios para crear una solicitud de incorporación de cambios marcada como aún no preparada para revisión.

El procesamiento usado por el bot Contributor License Agreement (CLA) es un buen criterio para la distinción entre contribuciones "pequeñas" y "grandes". Las solicitudes de incorporación de cambios que no requieren la firma de la CLA son probablemente "pequeñas". Las solicitudes de incorporación de cambios que requieren la CLA probablemente sean "grandes".

Solicitudes de incorporación de cambios pequeños

Los cambios en las solicitudes de incorporación de cambios pequeños se revisan para comprobar su precisión y se comprueben usando la compilación en el sitio de revisión. Como los cambios son pequeños, estas solicitudes de incorporación de cambios no desencadenan una revisión de todo el artículo.

Los revisores pueden observar otros pequeños cambios que podrían mejorar un artículo. Si esos cambios también son pequeños, se pueden sugerir como comentarios de revisión. Si los cambios sugeridos pueden desencadenar una revisión mayor, abra una incidencia y resuelva los cambios más adelante.

Cambios mayores

Las solicitudes de incorporación de cambios mayores se someten a una revisión más exhaustiva. Se comprueba todo lo siguiente:

• Que el código de ejemplo se incluye en la solicitud de incorporación de cambios, en el origen y como un archivo zip descargable.
• Que el código de ejemplo se compila y se ejecuta correctamente.
• Que el artículo describe claramente los objetivos para el lector y se cumplen esos objetivos.
• Que el artículo cumple los criterios de estilo y gramática y sigue nuestros principios de tono y voz.
• Que todos los vínculos se resuelven correctamente.

Los miembros del equipo de contenido revisarán la solicitud de incorporación de cambios y enviarán la revisión con comentarios. Si solo se solicitan cambios menores, los miembros del equipo pueden "aprobar" la solicitud de incorporación de cambios con los comentarios. El autor puede entonces revisar los comentarios y fusionar la solicitud de incorporación de cambios. La mayoría de las revisiones solicitarán cambios y, cuando se realicen, el revisor volverá a revisarlos.

Si las modificaciones requieren una revisión técnica, el revisor del equipo de contenido solicitará una revisión del miembro del equipo de producto correspondiente.

Revisión de borradores de solicitudes de incorporación de cambios

Es posible que quiera recibir comentarios antes en el proceso. Abra un borrador de solicitud de incorporación de cambios y agregue un comentario en el que solicite una revisión anticipada. Estas revisiones anticipadas se centran en la estructura del artículo: el esquema, el contenido general y los ejemplos. Estas revisiones no incluyen una comprobación exhaustiva de gramática ni de la corrección de los vínculos.

Explicación de las sugerencias

GitHub le permite escribir comentarios en los bloques de tilde triple de tipo suggestion que se muestran como diferencias y que se pueden combinar haciendo clic en un botón. En líneas cortas, GitHub realiza un buen trabajo de resaltado de los cambios. En líneas más largas, como un párrafo largo en una línea de texto, GitHub no resalta los cambios. Al escribir una sugerencia para una línea larga, observe si los cambios se resaltan claramente. Si los cambios no están resaltados, incluya comentarios fuera del bloque de sugerencias que expliquen lo que ha cambiado. Sin una explicación, los revisores posteriores o el autor de la solicitud de cambio suelen tardar mucho en averiguar cuáles son los cambios.

Respuesta a las revisiones

El autor actualiza la solicitud de incorporación de cambios para responder a los comentarios. Si el autor no está de acuerdo con el comentario, o aborda el comentario en otra solicitud de incorporación de cambios, el autor agrega un comentario explicando su cambio.

El autor @-menciona al revisor original en un comentario para solicitar una nueva revisión.

Expectativas del tiempo de respuesta

Los miembros del equipo de contenido normalmente revisarán las nuevas solicitudes de incorporación de cambios en dos días hábiles.

Una vez que se ha enviado una revisión, los autores deben intentar responder a los comentarios en una semana o menos. Es posible que los voluntarios no puedan cumplir estas expectativas debido a otros compromisos. En esos casos, los miembros del equipo preguntarán si el autor de la comunidad actualizará la solicitud de incorporación de cambios. De lo contrario, el miembro del equipo actualiza y fusiona la solicitud de incorporación de cambios para ellos.