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 incidencia, junto con información de la relación entre tu solicitud de cambio y esta. Esto nos permite mantener la información enlazada. Si es un cambio menor o trivial, no es necesario crear una incidencia. Ante la duda, crea una. Ten en cuenta que GitHub permite cerrar automáticamente incidencias usando 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.

Estrategia de pruebas:

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 cuando fusione la solicitud de cambios.

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

Se debe revisar el código (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 diversos aspectos del cambio.

El propósito de esta lista de comprobación es garantizar que tanto el autor como el revisor han considerado cada elemento. Con un poco de suerte, prevendrá que se olviden elementos. Tras revisar la lista de comprobación, tanto el revisor como el autor deben recurrir a su mejor juicio para determinar si se deben hacer cambios adicionales. Se invita a los revisores a iniciar una conversación sobre los elementos de la lista, para proporcionar guía sobre cómo mejorar la solicitud de cambios. No todos los elementos se aplicarán en todas las situaciones. En estos casos, marcar el elemento hará saber a los revisores que se ha tenido en cuenta. Si el revisor llega a la misma conclusión que el autor, no es necesario más trabajo. La mayoría de elementos de la lista de comprobación tienen una sección en la plantilla de solicitud de cambios donde puedes añadir tus impresiones, y al hacerlo se evitan preguntas de los revisores que aseguren que ambos os entendéis, agilizando el proceso de revisión.

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

Los autores deben mantener la descripción de la solicitud de cambios actualizada.
– Incluso si en los comentarios de la solicitud se describen cambios del enfoque.
– Los desarrolladores futuros necesitan una explicación concisa del cambio.
Después de cada modificación, comprueba bien que la descripción de la solicitud de cambios es precisa.

Pruebas unitarias

  • Debate bajo el encabezado «testing strategy».
  • ¿Se describe la cobertura de las pruebas unitarias automatizadas?
  • ¿Se puede cubrir el código modificado (o ya está cubierto) con pruebas unitarias automatizadas?

Pruebas del sistema

  • Debate bajo el encabezado «testing strategy».
  • ¿Se describe la cobertura de las pruebas automatizadas de sistema?
  • ¿Se puede cubrir el código modificado (o ya está cubierto) con pruebas unitarias automatizadas?

Pruebas manuales

  • Debate bajo el encabezado «testing strategy».
  • ¿Cómo probaste manualmente el cambio?
  • Sé claro en los pasos que otro usuario puede seguir para replicar tus pruebas.
  • ¿Es apropiada para el cambio la prueba manual descrita?
  • Al describirlos claramente se ayuda a los evaluadores alfa y a futuros desarrolladores.
  • Como revisor, usa esta descripción para replicar las pruebas (si es posible).

Documentación de usuario

  • ¿Es necesario actualizar 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ísala.

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

  • Las nuevas opciones de interfaz gráfica requieren una asignación de ayuda sensible al contexto.

Experiencia de usuario planteada para todos los usuarios

  • Los usuarios de NVDA son diversos, y se apoyan en distintas partes de NVDA. Asegúrate de que los cambios se adaptan a usuarios de lo siguiente:
  • Voz
  • Braille
  • Baja visión
  • Diferentes exploradores web (Firefox, Chrome, Edge)
  • Cuando no se soporte algo de esto con el cambio, destácalo bajo el encabezado «Known issues»