Hay diversas maneras de colaborar con el proyecto NVDA:
– Probando NVDA
– Clasificación e investigación de incidencias
– Contribuciones de documentación o código

Nota: actualmente sólo se aceptan solicitudes de cambio de mantenimiento o corrección de fallos mientras se procesa la cola existente.

Para más información, consulta: https://github.com/nvaccess/nvda/issues/11006

Pruebas

Hacer pruebas sobre las Alfa / beta / candidatas a liberación garantiza la calidad de NVDA.
Las pruebas de los usuarios y de la comunidad en general son particularmente importantes con idiomas distintos al inglés.
Hay varios enfoques que se pueden tomar para ellas:
– Uso no enfocado: simplemente utiliza NVDA como lo harías normalmente, e intenta completar tareas cotidianas.
– Pruebas enfocadas a cambios recientes: siguiendo los cambios que se han hecho en NVDA y probándolos a propósito con casos extremos.
– Prueba de regresiones: se prueban funciones antiguas y su comportamiento para buscar regresiones no intencionadas cuyo comportamiento no parezca relacionado con los cambios recientes.

Formar un grupo puede ayudar a obtener una buena cobertura, ideas sobre lo que se debe probar, y quizá aprender nuevas formas de usar NVDA.

Clasificación en investigación de incidencias:

También puedes hacer contribuciones que no sean de código, ayudando a procesar las incidencias entrantes en GitHub. Para más información, consulta los documentos relacionados con la clasificación de incidencias en nuestra web.

Contribuciones de código / documentos

Si eres nuevo en el proyecto o buscas una forma de ayudar, echa un vistazo a:
– label:goodfirstissue
– label:goodForNewDev
– label:closed/needs-new-author
– label:Abandoned

Pautas:

  • Para cualquier cosa distinta a la reparación de problemas pequeños, por favor comenta en una incidencia existente o crea una incidencia nueva exponiendo los detalles del cambio que propones.
  • Los cambios no relacionados se deben gestionar en incidencias separadas.
  • Incluye información sobre casos de uso, diseño, experiencia de usuario, etc.
  • Eso permitirá a los desarrolladores discutir los aspectos y consecuencias derivadas del cambio, y potencialmente evitará gastar tiempo inútilmente.
  • Es recomendable esperar la aceptación de tu propuesta antes de que empieces a codificar.
  • Ten en cuenta que NV Access no aceptará cambios que no se hayan discutido previamente.
  • Plantéate iniciar un debate por las listas de correo (por ejemplo NVDA Developers) para ver si hay interés.
  • Un cambio menor / trivial que no requiera definitivamente debates sobre diseño, experiencia de usuario o implementación puede ir directamente en una solicitud de cambio sin crear una incidencia antes.
  • Por ejemplo, una corrección de un error obvio de codificación o escritura o un controlador simple de síntesis o pantalla Braille
  • Esto debería ser raro.
  • Ante cualquier duda, usa una incidencia primero. Utilízala para debatir sobre las alternativas planteadas respecto a la implementación, el diseño y la experiencia de usuario. Después, da tiempo a la gente para que ofrezca retroalimentación.

Proceso de GitHub:

1. «Bifurca» el repositorio de NVDA en GitHub

Cuando bifurques el repositorio, GitHub creará una copia de la rama master.
Sin embargo, esta rama no se actualizará cuando lo haga la rama master oficial.
Para asegurarte de que tu trabajo siempre se basa en el último commit de la rama master oficial, se recomienda que vincules la copia de tu rama a la oficial en vez de la que hay en tu cuenta.
Si has clonado tu bifurcación de GitHub, puedes hacerlo desde la línea de órdenes del siguiente modo:
«`
# Añadir un origen remoto con el repositorio de NV Access.
git remote add nvaccess https://github.com/nvaccess/nvda.git

# Descargar las ramas de NV Access.
git fetch nvaccess

# Cambiar a la rama master local.
git checkout master

# configurar la rama master local para que utilice por defecto la rama master de NV Access.
git branch -u nvaccess/master

# Actualizar la rama master local.
git pull
«`

2. Usa una rama «temática» separada para cada contribución

Todo el código debería basarse en el commit más reciente de la rama master oficial que hay en el momento en que empiezas a trabajar, a no ser que el código oficial sufra cambios drásticos que afecten a tu trabajo o dependa del código de otra incidencia.
Si vas a añadir algo de lo que el usuario se vaya a dar cuenta, deberías actualizar la guía de usuario convenientemente para reflejar tu cambio.

3. Ejecuta las pruebas unitarias y de estilo

  • Ejecuta rununittests (rununittests.bat) antes de abrir tu solicitud de cambios, y comprueba que se superan todas las pruebas unitarias.
  • Si es posible para tu solicitud de cambios, plantéate crear un conjunto de pruebas unitarias para evaluar tus cambios.
  • La comprobación de estilo garantiza que tu código cumple con nuestras expectativas de estilo del código. Usa runlint nvaccess/master (runlint.bat)

4. Crea una solicitud de cambios (PR o Pull Request)

Cuando creas que una contribución está lista, o quieras recibir comentarios, abre un borrador de solicitud de cambios.
Rellena la plantilla de solicitud de cambios, incluyendo las consideraciones de la lista de comprobación.
La lista de comprobación te pide que confirmes que has pensado en todos los elementos. Si falta alguno de ellos, viene bien explicar en algún lugar de la solicitud por qué se ha descartado.
Cuando quieras una revisión, marca la solicitud como «ready for review».

5. Participa en el proceso de revisión del código

Este proceso requiere que los desarrolladores principales de NVDA entiendan el propósito del cambio, lean los cambios en el código, hagan preguntas o sugieran modificaciones.
Participa en este proceso, responde a las preguntas y debate sobre los cambios.
Ser proactivo acelerará notablemente el proceso de revisión del código.
Cuando se apruebe la solicitud de cambio se fusionará, y dicho cambio estará activo en la siguiente compilación Alpha.

6. Comentarios de los usuarios Alpha

Después de que se fusione una solicitud de cambios, estáte atento a los comentarios de los usuarios y evaluadores Alpha.
Puedes tener que continuar para solucionar fallos o tener en cuenta casos de uso imprevistos.

Estilo del código

El estilo del código está reforzado por el comprobador de conformidad Flake8, visita tests/lint/readme.md para más información.

Codificación

  • Cuando los archivos Python contengan caracteres que no sean Ascii, deberán estar codificados en UTF-8.
    • No debería haber bom Unicode al principio del archivo, ya que esto desafortunadamente rompe una de las herramientas de traducción que usamos (xgettext). En su lugar, incluye esto como primera línea del archivo (sólo si el archivo contiene caracteres no ASCII):
      # -*- coding: UTF-8 -*-
    • Deberás incluir esta línea si las cadenas del código (incluso si estas no son traducibles) contienen secuencias de escape que producen caracteres no Ascii, tales como "\xff". Esto es particularmente importante para controladores de pantallas braille. El responsable del fallo es Gettext, como se puede ver en https://github.com/nvaccess/nvda/issues/2592#issuecomment-155299911.
  • La mayoría de los archivos deben contener saltos de línea en formato crlf de Windows. Este es un proyecto hecho exclusivamente para Windows, y no se puede usar en sistemas operativos derivados de Unix.

Indentado

  • La indentación se debe hacer con tabuladores (uno por nivel) y no con espacios.
  • Al dividir una instrucción en varias líneas, indéntala con uno o más niveles. No uses alineación vertical del tipo “alinear con el corchete de la línea superior”.
    • Sé consciente de que esto necesita un salto de línea después de abrir un paréntesis, corchete o llave si pretendes dividir la instrucción en varias líneas.
    • En la lista de parámetros de la definición de funciones, da un margen doble para diferenciar los parámetros del cuerpo de la función.

Nombres de identificadores

  • Usa nombres descriptivos
    • nombra las constantes para evitar «números mágicos» y da una pista sobre la intención u origen del valor. Pregúntate ¿qué representa?
  • Las funciones, propiedades, variables, etc. deberían usar mayúsculas para separar palabras, pero empezar con una letra minúscula; por ejemplo, speakText.
  • Funciones booleanas o variables
    • deberían intentar usar la forma positiva del idioma (para evitar dobles negativos como shouldNotDoSomething = False)
    • comienza con una «palabra de pregunta» para dar una pista sobre su naturaleza booleana. Ejemplos: shouldX, isX, hasX
  • El caso anterior también se aplica para las clases, pero en vez de empezar en minúscula lo hacen en mayúscula; por ejemplo, BrailleHandler.
  • Las constantes siempre deben estar en mayúscula, separando las palabras con guiones bajos. Por ejemplo, LANGS_WITH_CONJUNCT_CHARS.
  • Los manejadores de eventos tienen el prefijo «event_», y tienen la forma «event_ACTION» o «event_OBJECT_ACTION», donde OBJECT hace referencia al tipo de clase a la que se refiere la acción.
  • Puntos de extensión:
    • Action: lleva el prefijo pre_ o post_ para especificar que se notifica a los manejadores antes o después de que la acción tenga lugar.
    • Decider: lleva el prefijo should_ para mostrarlo como una pregunta. Por ejemplo, should_doSomething
    • Filter: por determinar. lo ideal es que siga el mismo estilo que los otros, y comunicar si el filtro ocurre antes o después de la acción. Sería estupendo tener también un esquema de nombres que lo diferencie de los otros.

Cadenas traducibles

  • Todas las cadenas que se puedan mostrar al usuario deberían marcarse como traducibles usando la función _(). Por ejemplo, en vez de poner "text review" pondríamos en su lugar _("text review").
    Todas las cadenas traducibles deberían estar precedidas por un comentario en inglés para traductores que describa claramente su propósito. Por ejemplo:
# Translators: The name of a category of NVDA commands.
SCRCAT_TEXTREVIEW = _("Text review")
  • Se pueden dividir las cadenas traducibles largas en múltiples líneas, aprovechando la ventaja que ofrece la unión implícita de líneas entre paréntesis de Python. Los comentarios para traductores pueden ocupar varias líneas también. Por ejemplo:
self.copySettingsButton = wx.Button(
    self,
    label=_(
        # Translators: The label for a button in general settings to copy
        # current user settings to system settings (to allow current
        # settings to be used in secure screens such as User Account
        # Control (UAC) dialog).
        "Use currently saved settings during sign-in and on secure screens"
        " (requires administrator privileges)"
    )
)