Esta página está creada con la intención de servir como explicación para rellenar la plantilla de solicitud de cambios de NVDA en GitHub (en inglés)

La plantilla

Al principio de la plantilla hay un bloque de comentarios en HTML (que comienza con <!--), que apunta a la versión inglesa de esta página en la wiki, se puede dejar donde está y no aparecerá cuando se guarde la incidencia. Puedes eliminarlo sin problema, borrando todo el texto desde el principio hasta --> incluido.

Enlace al número de incidencia:

Por favor, incluye aquí el número de la incidencia. Esto ayuda a los desarrolladores a mantener la información relacionada entre sí junta. Si se trata de un cambio menor o trivial, no es necesario crear una incidencia. En caso de dudas, crea una.
Ten en cuenta que Github permite cerrar incidencias automáticamente mediante palabras clave. Por ejemplo,
si escribes closes #7777 o fixes #4242 en el cuerpo de la descripción, la incidencia mencionada se cerrará automáticamente al mezclar la solicitud de cambio en la rama master. Si tu solicitud de cambio se archiva en otra rama, como por ejemplo beta, habrá que cerrar la incidencia manualmente tras mezclar dicha solicitud.

Resumen de la incidencia:

Un breve resumen del problema que intentas resolver.

Descripción de cómo resuelve la incidencia esta solicitud de cambios:

Incluye una breve exposición indicando cómo resuelve la incidencia este cambio. Incluye también cualquier enlace o información externa que hayas usado para solucionar el problema. Esto ayuda a que otros tengan la misma base que tú y aprendan de este trabajo.

Pruebas realizadas:

Describe los pasos que seguiste para probar tus cambios. Esto debería permitir que alguien más pueda reproducir tus pruebas.

Vayamos más allá, intenta responder las siguientes preguntas:
– ¿Cómo has hecho las pruebas para asegurarte de que tus cambios funcionan como se esperan?
– ¿Te has asegurado de que hay una extensa cobertura de pruebas a través de varios sistemas operativos?
– ¿Te has planteado que pueda haber posibles regresiones (funciones o comportamientos relacionados que puedan romperse)?

Emplea esta sección como una oportunidad para intentar convencer a los desarrolladores (y a ti mismo) de que debería mezclarse el cambio que has propuesto.

A menudo es útil en el desarrollo cara a cara demostrar un cambio, bastantes fallos se descubren en ese momento cuando la otra persona pide una variación en el enfoque de las pruebas. Ya que es bastante improbable que se pueda demostrar una función de manera interactiva, una lista de pasos fácil de seguir para una «demo» permite que otros puedan hacer comprobaciones por sí mismos sin tener que entrar en demasiados detalles. También sirve como punto de partida para los miembros de la comunidad que prueban los cambios que van dentro de NVDA.

Ejemplo:

En las opciones de NVDA comprueba que:
– En la categoría teclado
– «Verbalizar caracteres al escribir» está desmarcada
– «Verbalizar palabras al escribir» está marcada

  1. Abre el bloc de notas
  2. Escribe «hola»
  3. Pulsa espacio

Se espera que se verbalice «hola».

  • Si es necesario modificar muchos ajustes de NVDA, plantéate adjuntar un archivo nvda.ini de muestra a la solicitud de cambio.
  • Si se necesita un documento complicado para hacer pruebas con una aplicación de terceros, plantéate adjuntarlo a la solicitud de cambios para que otros hagan pruebas también.

Problemas conocidos con la solicitud de cambio:

¿Hay problemas o desventajas con este enfoque? Por ejemplo: No funcionará en Python 3

Entrada en el registro de cambios:

Una entrada destinada a explicar los cambios en NVDA a los usuarios finales. La entrada que propongas se añadirá al archivo changes.t2t, que se convierte a HTML y se utiliza como documento de novedades / registro de cambios.
Consulta (user_docs/en/changes.t2t)

Ya que el archivo changes.t2t tiende a provocar conflictos, se pide a los colaboradores que no lo editen directamente, y que en su lugar añadan la entrada en la parte inferior de la descripción de la solicitud de cambios.
Un desarrollador principal actualizará el archivo al mezclar la solicitud de cambio.

Por ejemplo:

*Nuevas características*
`Added a command to announce useful thing. (#WXYZ, #ABCD)`

*Cambios*
`Old command, now also uses new useful command. (#WXYZ)`

Estas descripciones deberían seguir el formato: "{Descripción del cambio}. (#{número de incidencia})"

Puedes sugerir descripciones para varias secciones. Las secciones más comunes son:

  • Nuevas características
  • Cambios
  • Fallos solucionados

Se pueden incluir varios números de incidencia separados por comas. Si no hay número de incidencia, puedes usar el número de la solicitud de cambio.

Por ejemplo, consulta el archivo changes.t2t

Lista de comprobación de revisión del código

El código debe revisarse (mediante una solicitud de cambios en GitHub) antes de que pueda aceptarse en el proyecto.
La plantilla de solicitud de cambios (.github/PULL_REQUEST_TEMPLATE.md) solicita a los autores (y revisores) que consideren varios aspectos del cambio.

El propósito de esta lista de comprobación es asegurar que tanto el autor como el revisor han tenido en cuenta cada elemento.
Con suerte, ayuda a que no se olviden algunos elementos.
Tras revisar la lista de comprobación, el revisor y el autor deben razonar al máximo si piensan que es necesario hacer más cambios.
Se invita a los revisores a que inicien una conversación sobre los elementos de la lista, para proporcionar guiado sobre cómo mejorar la solicitud de cambios.
No todos los elementos son aplicables a todas las situaciones. En este caso, comprobar el elemento hace saber a los revisores que se ha tenido en cuenta.
Si el revisor alcanza la misma conclusión que el autor, no es necesario más trabajo.
La mayoría de elementos de la lista de comprobación disponen de una sección en la plantilla de solicitud de cambio donde puedes añadir tus impresiones. Al hacerlo, puedes evitar ciertas preguntas del revisor, y esto asegura que habláis de lo mismo y agiliza el proceso.

La descripción de la solicitud de cambios está al día.

A veces el enfoque tomado puede cambiar durante el proceso de revisión.
Sin embargo, en el futuro, los desarrolladores pueden necesitar volver a la solicitud de cambios en búsqueda de una explicación del enfoque.
Comprueba bien que la descripción de la solicitud de cambios es precisa.

Pruebas unitarias

¿Se puede cubrir el código modificado con pruebas unitarias automatizadas?
Cualquier comentario sobre esto se puede poner bajo el encabezado «testing strategy».

Pruebas del sistema

¿Se puede cubrir el código modificado con pruebas automatizadas del sistema?
Las pruebas del sistema son pruebas de extremo a extremo de NVDA.
Cualquier comentario sobre esto se puede poner bajo el encabezado «testing strategy».

Pruebas manuales

¿Es apropiada para el cambio la prueba manual descrita?
Se deberían describir con detalle los casos comprobados por el autor.
En algunos casos, los evaluadores alpha tendrán que probar el cambio, por lo que hay que describirlo bajo el encabezado «testing strategy» de la plantilla de solicitud de cambios.

Documentación de usuario

¿Se ha actualizado la documentación de usuario?

Entrada en el registro de cambios

Se ha proporcionado una entrada adecuada en el registro de cambios.
Como revisor, revísalo.

Ayuda sensible al contexto en cambios de interfaz gráfica.

Si el cambio añade una nueva opción a la interfaz gráfica, asegúrate de que se ha añadido una asignación a la ayuda sensible al contexto.