Si quieres contribuir con código o documentación al proyecto NVDA, sigue estas pautas. También puedes hacer contribuciones que no sean de código, ayudando a procesar las incidencias entrantes en GitHub.

Cómo enviar cambios

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. Deberías esperar a que se acepte tu propuesta antes de empezar a programar. Ten en cuenta que NVAccess no aceptará cambios que no se hayan discutido previamente.

Si es un cambio pequeñito que no incluye modificaciones en diseño, discusiones sobre la implementación o experiencia de usuario (por ejemplo, arreglar un error que se ve claramente en el código o en la documentación, o un nuevo controlador para un sintetizador o pantalla braille), puedes crear un nuevo pull request sin tener que abrir una incidencia antes. Sin embargo, esto es muy raro. Para estar seguros, abre una incidencia.

Si esta es tu primera contribución, deberás hacer un fork del repositorio oficial en tu cuenta de GitHub. Cuando hagas un fork, GitHub copiará la rama master. Sin embargo, esta rama no se actualizará cuando lo haga la 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 ya has clonado tu fork de GitHub, puedes hacer algo como esto desde la línea de comandos:

#Añadir un origen remoto con el repositorio de NVDA
git remote add nvaccess https://github.com/nvaccess/nvda.git
# Descargar las ramas de NVAccess
git fetch nvaccess
# Cambiar a la rama master local
git checkout master
# configurar la rama master local para que utilice por defecto el origen remoto de NVDA
git branch -u nvaccess/master
# Actualizar la rama master local
git pull

Deberías usar una rama distinta para cada incidencia. 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. Las nuevas ramas nunca deberán crearse a partir de la rama next.

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.

Antes de abrir tu pull request, ejecuta el comando scons tests y asegúrate de que se superan todas las pruebas unitarias. Si es posible, crea un conjunto de unidades de prueba adicionales para probar tus cambios.

Cuando sea hora de enviar el código, abre un nuevo pull request haciendo referencia a la incidencia que describe tu cambio. El equipo de NVAccess pasará a revisar tu código.

Estilo del código

Codificación

Cuando los archivos Python contengan caracteres que no sean Ascii, deberán estar codificados en UTF-8. Para evitar errores con las herramientas de traducción, incluye esta línea al principio del código si lo haces:
# -*- coding: UTF-8 -*-
Deberás incluir esta línea incluso si no planeas que las cadenas se puedan traducir, o si tienen secuencias de escape que producen caracteres no Ascii, tales como \xff. Esto es particularmente importante para controladores de pantallas braille.

La mayoría de los archivos deben contener saltos de línea en formato Windows (crlf). 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”.

Nombres de identificadores

Las funciones, propiedades, variables, etc. deberían usar mayúsculas para separar palabras, pero empezar con una letra minúscula; por ejemplo, speakText.

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 .

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”)