Autor: José Manuel Delicado

Última actualización: 15 de agosto de 2023

Índice

Introducción

Tradicionalmente, para poder publicar un complemento en la web de la comunidad internacional de NVDA, ha sido necesario superar una revisión básica realizada por sus miembros. En dicha revisión se evaluaban cuatro principios clave: licencia y copyright, documentación, experiencia de usuario y seguridad. Recientemente, con la llegada de la tienda de complementos integrada en NVDA, este proceso de revisión ha pasado a ser opcional. Esto no significa que por ello sea menos importante. La revisión de un complemento sigue siendo un proceso esencial para garantizar su calidad y proponer mejoras.
En esta guía, se enumeran una serie de criterios que tanto los desarrolladores de complementos como los revisores pueden seguir para evaluar o mejorar la calidad de un complemento dado. Los criterios se agrupan en los cuatro principios heredados de la comunidad internacional, y añaden otros tres que consideramos de especial relevancia.

A quién va dirigido este documento

  • Revisores: un revisor puede ser cualquier miembro de la comunidad que decida revisar un complemento. No tiene por qué manejar todos los conceptos que se describen más adelante, y puede limitarse a revisar sólo aquellas áreas donde se sienta cómodo. Una revisión puede ser llevada a cabo por varios revisores.
  • Desarrolladores que quieran mejorar la calidad de sus complementos.
  • Propietarios de directorios de complementos que deseen puntuar la calidad de los mismos o establecer un umbral mínimo de entrada.

Umbral mínimo de entrada en la comunidad de NVDA en español

Si quieres que tu complemento aparezca en nuestro catálogo de complementos, debes superar los siguientes criterios, como mínimo: 1.5, todos los de la sección 2, 5.15 y todos los de la sección 7.

El complemento se ajusta a un acuerdo de licencia que protege al mismo tiempo los derechos del desarrollador y la comunidad.

1.1. Uso de la licencia GNU General Public License, versión 2 o posterior

NVDA se ha liberado bajo la licencia GPL, que garantiza y protege las libertades sobre el software libre. Se espera que todos los complementos de la comunidad también lo hagan. Para ello, basta con publicar el código fuente del complemento, junto con un archivo en texto plano con el texto de la licencia, situado en la carpeta raíz del código y llamado COPYING.txt o LICENSE.txt.

Todo módulo perteneciente al complemento, y que no sea de terceros, deberá incluir en su parte superior una serie de comentarios Python que hagan alusión a la licencia utilizada. Un ejemplo podría ser el
que se encuentra a continuación. Dichas cabeceras deberán estar en el idioma base del complemento, generalmente inglés:

# <nombre del complemento> add-on for NVDA
# This file is covered by the GNU General Public License.
# See the file COPYING.txt for more details.
# Copyright (C) 2020 Pepe Pérez <[email protected]>

1.3. Módulos de terceros

Si el complemento incluye módulos desarrollados por terceros, estos deberán estar liberados bajo la licencia GNU General Public License o una compatible. Si un módulo se encuentra liberado bajo una licencia no compatible y su uso es indispensable para el funcionamiento del complemento, se deberá justificar adecuadamente.

1.4. Excepciones

Si un complemento ofrece módulos cuyo código fuente no se puede liberar (por ejemplo, un módulo que gestiona licencias comerciales o que contiene claves de acceso sensibles), se justificará este hecho y el complemento superará igualmente la revisión de licencia y copyright.

1.5. Bifurcaciones y modificaciones

Si un complemento deriva de otro ya existente, este hecho se refleja con claridad en la documentación, el archivo del manifiesto y el nombre del complemento.

2. Seguridad

El complemento es seguro, respeta a todos los usuarios, no tiene propósitos ocultos y no causa daños al sistema o al usuario.

2.1. Daños al sistema

El complemento no debe, en modo alguno, hacer ninguna de las acciones siguientes:

  • Corromper el sistema de archivos.
  • Borrar o cifrar datos del usuario.
  • Dañar los dispositivos del equipo.
  • Instalar programas no deseados.
  • Modificar o borrar archivos del sistema operativo, NVDA o cualquier otro software instalado en el equipo.

2.2. Privacidad

El complemento no deberá almacenar localmente ni enviar datos del usuario a servidores externos. Estos datos pueden incluir, sin limitarse a:

  • Archivos almacenados en el equipo.
  • Vídeo y audio obtenido desde dispositivos periféricos (cámara, micrófono y otros).
  • Interacciones del usuario con el sistema operativo y con el propio NVDA.
  • Datos personales, tales como nombre, apellidos, dirección postal, dirección de correo electrónico, número de teléfono o dirección IP.

En caso de que la recopilación y envío de información sea imprescindible para el funcionamiento del complemento, o ciertas funciones puedan verse afectadas si el complemento no lo hace, se deberá:

  • Solicitar consentimiento al usuario mediante algún tipo de cuadro de diálogo, indicando una forma de revocar dicho consentimiento (por ejemplo, una opción en las preferencias de NVDA). En dicho consentimiento se deberá indicar qué datos se recopilan, con qué propósito, dónde se envían y qué hacer para oponerse a su tratamiento. Esta información también deberá estar disponible en la documentación. O bien, si dichos datos no son demasiado sensibles (por ejemplo, si el complemento sólo busca una palabra en un diccionario en línea),
  • Indicar claramente en la documentación con qué datos trata el complemento, dónde se envían y el propósito del tratamiento.

2.3. Ejecución en pantallas seguras

Si un complemento ha sido diseñado expresamente para ejecutarse cuando el usuario ha iniciado sesión en Windows, dicho complemento aborta su inicialización si detecta que NVDA se está ejecutando en una pantalla segura.
Los sintetizadores de voz, controladores de pantallas Braille, complementos de asistencia remota y complementos específicos para pantallas seguras podrán ejecutarse libremente en este contexto. Los módulos de aplicación, por lo general, no se ven afectados por este requisito.

2.4. Escritura fuera del directorio de configuración de NVDA

El complemento no debe escribir fuera de las carpetas de configuración de NVDA (userConfig en copias portables, %appdata%\nvda en copias instaladas, etc.), ni en el registro de Windows. En caso de que deba hacerlo, este hecho se justificará apropiadamente en la documentación, indicando en qué ubicaciones se almacenan los datos y su propósito. Se entenderá como violación de seguridad que el complemento escriba en el directorio de configuración por defecto de NVDA, siempre que este sea distinto al que el usuario especifique por línea de comandos (en caso de que esto suceda).

2.5. Solicitud de elevación de privilegios

El complemento no solicitará privilegios de administrador al usuario, ya sea mediante el control de cuentas de usuario, o cualquier otro medio que exista para ello. En caso de que sea indispensable hacerlo, este hecho deberá reflejarse adecuadamente en la documentación.

2.6. Errores fatales de otros complementos

El complemento no provocará errores en otros complementos ya instalados en la copia de NVDA. Para ello, el complemento debe ser lo menos invasivo y lo más independiente posible. Si es indispensable que el complemento interfiera en el funcionamiento de otros complementos, este hecho se justificará en la documentación.

2.7. Errores fatales de NVDA

El complemento no provocará errores críticos que afecten al núcleo de NVDA. Si es indispensable que el complemento interfiera en el funcionamiento de NVDA, este hecho se justificará en la documentación.

2.8. Restricciones

El complemento no restringe las funciones de NVDA o de cualquier otro complemento en modo alguno. De hacerlo, este hecho deberá justificarse apropiadamente en la documentación.

2.9. Errores críticos del propio complemento

El complemento está diseñado de tal manera que puede recuperarse de todos los errores que se produzcan en su funcionamiento, sin que quede en un estado de inestabilidad y sin que sea obligatorio reiniciar NVDA.

2.10. Código de conducta

El complemento se ajusta, tanto en código fuente como en funcionamiento, a la versión más reciente del código de conducta del ciudadano y el colaborador de NV Access. Esto significa, entre otras cosas, que el complemento no discriminará a ningún usuario por su orientación sexual, raza, discapacidad, ideología política, religión o ubicación geográfica. El complemento tampoco contendrá mensajes insultantes, vejatorios o que inciten a la violencia.

3. Compatibilidad

El complemento declara la compatibilidad con las versiones de NVDA en las que puede usarse.

3.1. Especificación de versiones compatibles

En el archivo manifest.ini, el complemento indica claramente cuál es la mínima versión de NVDA necesaria para su funcionamiento, y cuál es la última con la que se ha probado. Para ello, el valor de cada parámetro sigue el formato año.versión.0, siendo el último 0 opcional. La última versión probada nunca es superior a la versión estable más reciente, a menos que se haya liberado una beta de la próxima versión.

3.2. Compatibilidad del código

El código del complemento en su totalidad, incluyendo módulos de terceros si los hubiera, es compatible con la versión de Python incluida en NVDA. Dicha versión no tiene por qué ser la más reciente del intérprete Python.

3.3. Compatibilidad con versiones antiguas

Si el complemento está pensado para ser compatible con todas las posibles versiones de NVDA, incluyendo aquellas anteriores a la 2019.3, su código deberá funcionar con las versiones de Python 2 y 3. En su manifiesto, la versión mínima especificada no deberá ser anterior a la 2019.1.

4. Documentación

El complemento está bien documentado, de tal forma que un usuario puede saber cómo utilizarlo simplemente leyendo el archivo de ayuda.

4.1. Archivos de documentación

La documentación incluida en el complemento deberá alojarse en un archivo único en formato HTML. Dicho archivo podrá incluir enlaces a recursos adicionales en línea, pero no debe contener scripts, animaciones ni cualquier elemento que implique un comportamiento dinámico de su contenido. Para facilitar la revisión, se recomienda que la documentación presente en la versión no compilada del complemento se encuentre en Markdown, o un formato compatible de texto plano con marcas que se pueda convertir a HTML.

4.2. Estructura de la documentación

Se sugiere la división de la documentación en los siguientes apartados:

  • Lista que contiene, al menos, los siguientes elementos: autor, compatibilidad con versiones de NVDA y enlaces de descarga.
  • Introducción: breve descripción de lo que hace el complemento, destacando alguna de sus funciones más llamativas.
  • Modo de uso: descripción detallada de todas las características y cómo utilizarlas. Si el complemento dispone de diálogos, se deben documentar aquí, así como las consideraciones de seguridad del punto 2.
  • Atajos de teclado: sección donde se enumeran todos los atajos de teclado del complemento, si los hay.
  • Registro de cambios: sección donde se indica qué ha cambiado desde la versión anterior. Puede contener un subapartado por cada versión.

Cada apartado puede contener subapartados.

4.3. Estilo y formato

De cara a facilitar la lectura y posible traducción a otros idiomas, se recomienda seguir las indicaciones que se muestran a continuación:

  • Se debe dejar una línea en blanco entre cada párrafo.
  • Los párrafos no deben ser muy largos. Para ello, se sugiere expresar una única idea por párrafo, en vez de varias.
  • Si se describe un proceso que consta de varios pasos, estos podrían ir en una lista numerada.
  • Si se hacen otras enumeraciones (por ejemplo, lista de idiomas que puede traducir un posible complemento), se debería emplear una lista con viñetas.
  • Se recomiendan las listas con viñetas en el registro de cambios, para enumerar los cambios de cada versión.

4.4. Ortografía y gramática

La documentación del idioma base del complemento debe estar redactada con buena ortografía y gramática, de tal forma que un potencial traductor o usuario que no hable el idioma base de forma nativa pueda comprenderla en su totalidad, ya sea empleando sus conocimientos o mediante una herramienta de traducción automática.

5. Experiencia de usuario

La mayoría de usuarios pueden utilizar el complemento independientemente de sus conocimientos, experiencia y ayudas técnicas auxiliares.

5.1. Cadenas traducibles

Toda cadena que se muestre al usuario y cuyo contenido íntegro no sea el resultado de una operación realizada por el complemento debe marcarse como traducible, a menos que sea indispensable mostrarla en el idioma base del complemento. Si un módulo contiene cadenas traducibles, deberá llamar a addonHandler.initTranslation() para que funcionen.

5.2. Prevención de errores

El complemento debe ser capaz de anticiparse y adaptarse a aquellos errores que puedan derivarse de un entorno limitado (por ejemplo, falta de conexión a Internet) o una acción inadecuada por parte del usuario (por ejemplo, uso de un formato incorrecto al introducir datos). En estos casos, se deberá comunicar el error al usuario, ya sea mediante un mensaje de NVDA o un cuadro de diálogo. No será necesario informar de aquellos errores que el desarrollador haya previsto y formen parte del flujo de ejecución (si la acción A falla, ejecuto la acción B y la operación se completa con éxito).

Si un complemento incluye cuadros de diálogo complejos, dichos diálogos deben poder abrirse desde, al menos, uno de estos lugares:

  • El menú Preferencias de NVDA.
  • El menú Herramientas de NVDA.
  • Cualquier otro diálogo proporcionado por el complemento.

Esto debe aplicarse incluso si la apertura de los diálogos se puede controlar mediante un gesto o pulsación de teclado.

5.4. Configuración

Si el complemento permite ajustar ciertos aspectos de su configuración, sus ajustes deben agregarse al diálogo Opciones de NVDA, a menos que sean tan complejos como para necesitar un diálogo propio.

5.5. Gestos de entrada

Todos los gestos de entrada del complemento, incluyendo pulsaciones de teclado, toques en la pantalla táctil o pulsaciones en la pantalla Braille, se pueden asignar y modificar desde el diálogo Gestos de entrada. Cada gesto tiene una descripción breve y clara de su propósito, y está asignado a la categoría más apropiada para él. Se debe dar prioridad a las categorías existentes proporcionadas por NVDA, y crear categorías nuevas sólo cuando sea necesario.

5.6. Reacción a cambios de configuración

El complemento incluye mecanismos para reaccionar adecuadamente ante las siguientes situaciones, según corresponda:

  • Se guarda la configuración de NVDA.
  • Se aplica la configuración guardada de NVDA.
  • Se restaura la configuración de NVDA a valores de fábrica.
  • El perfil de configuración activo cambia.

5.7. Dispositivos de salida y mensajes

Todo aquel mensaje emitido por el complemento deberá reflejarse tanto en el sintetizador de voz seleccionado como en la pantalla Braille conectada. Si el complemento emite señales acústicas, estas deberán complementarse con un mensaje en Braille adecuado. Se puede contemplar el uso de abreviaturas Braille para ciertos mensajes de voz.

5.8. Mensajes explorables

Si el complemento emite mensajes largos, estos deberán mostrarse de una de las siguientes maneras:

  • En una ventana explorable, de tal forma que el usuario pueda recorrerlos con las órdenes de navegación de una sola letra.
  • En un diálogo de mensaje, de tal forma que el usuario pueda explorarlos con el cursor de revisión y copiarlos en su totalidad pulsando control+c.

5.9. Uso de la tecla NVDA

Todos los gestos de teclado asociados a un complemento deben incluir en su composición la tecla NVDA, de tal forma que no restrinjan atajos de otras aplicaciones o del propio sistema operativo. Se podrá omitir el uso de la tecla NVDA en los siguientes escenarios:

  • Módulos de aplicación donde el atajo elegido pueda enriquecer la experiencia de usuario o complemente a una función existente asociada al mismo atajo. Ejemplo: control+n para activar y desactivar la negrita en Word.
  • Objetos personalizados, siempre que el gesto sea efectivo sólo en los objetos afectados. Por ejemplo, que NVDA diga «cortado» al pulsar control+x en un cuadro de edición.
  • Gestos de segunda capa en órdenes de doble capa.

5.10. Menmotécnicos

Todos los elementos de menú y controles de los cuadros de diálogo disponen de un atajo de teclado que mueve rápidamente el foco a ellos. Este atajo suele agregarse anteponiendo el símbolo & a la letra elegida en la etiqueta del elemento. Siempre que sea posible, cada mnemotécnico debe ser único. Los usuarios pueden detectar la presencia de menmotécnicos situándose sobre el control con el foco y escuchando la tecla rápida asociada, compuesta por alt+letra.

5.11. Operaciones bloqueantes

Toda operación realizada por un complemento que supere un umbral de tiempo perceptible por el usuario debe realizarse en un hilo de ejecución independiente. Si dicho tiempo es superior a 3 segundos en todos los escenarios, se debe mostrar un diálogo con el progreso real de la operación, o bien un diálogo de progreso indeterminado.

5.12. Recarga de complementos

El complemento deberá soportar la recarga de complementos de NVDA (NVDA+control+f3) sin que esto provoque anomalías en su funcionamiento (elementos de menú y paneles de opciones duplicados, variables residuales que jamás se vuelven a usar, etc.).

5.13. Tareas de instalación

Si el complemento realiza tareas adicionales durante su instalación y estas requieren la intervención del usuario, se deberán utilizar mensajes y preguntas sencillos, y nunca recurrir a interfaces complejas.

5.14. Tareas de desinstalación

Al desinstalar el complemento, y con el objetivo de mantener limpia la configuración de NVDA, se recomienda eliminar todas aquellas opciones y archivos creados por el propio complemento.

5.15. Capas de órdenes

Si el complemento dispone de una capa de órdenes, una de esas órdenes sirve para mostrar instrucciones sobre cómo usar la capa. Además, al menos una de las siguientes afirmaciones es cierta:

  • La capa se desactiva inmediatamente después de pulsar una de sus órdenes.
  • Una de las órdenes de la capa permite salir de ella, y está documentada adecuadamente.

6. Funcionamiento interno

El código del complemento está bien estructurado y permite anticiparse al mayor número posible de escenarios y circunstancias, tanto presentes como futuras.

6.1. Comentarios para traductores

Toda cadena marcada como traducible debe incluir, justo en la línea superior, un comentario para traductores que describa claramente el propósito de la misma. Dicho comentario no debe ser una copia íntegra de la cadena. Los comentarios para traductores comienzan con la palabra «Translators:», seguida del mensaje. Si una línea de código contiene varias cadenas traducibles, se deberá dividir en varias líneas para poder situar los comentarios apropiadamente. Dichos comentarios podrán estar redactados en inglés o en el idioma base del complemento, y extenderse a lo largo de varias líneas.

6.2. Idioma base

Todo complemento que utilice la plantilla de complementos para facilitar su compilación deberá especificar, en el archivo buildVars.py, el idioma original de su documentación, código fuente y otros recursos asociados.

6.3. Funciones del núcleo de NVDA

Siempre que sea posible, el complemento llamará a las funciones incluidas en NVDA para desempeñar sus tareas. Esto simplifica sensiblemente el código, ya que las funciones de NVDA contemplan casos de uso que, de otro modo, deberían codificarse a mano.

6.4. Almacenamiento de la configuración

Siempre que sea posible, el complemento almacenará su configuración en el objeto config.conf de NVDA, y la validará agregando la correspondiente especificación a config.conf.spec. El uso de otros formatos (archivos ini independientes, JSON o Pickle) sólo se aconseja si se deben almacenar estructuras de datos complejas.

6.5. Variables globales

Se desaconseja el uso de variables globales, a menos que sea necesario. En caso de tener que recurrir a ellas, el complemento las devolverá a su estado inicial tan pronto como sea posible.

6.6. Liberación de recursos

Toda clase que represente un controlador Braille, sintetizador de voz, módulo de aplicación, extensión global o potenciador de mejoras de la visión dispone de un método terminate que libera sus recursos asociados y elimina todo rastro de su ejecución en memoria.
El método terminate no será necesario en aquellas clases que no modifiquen la interfaz de NVDA, no dispongan de constructor ni almacenen variables en el propio objeto durante la ejecución.

6.7. Finalización de hilos

Si el complemento dispone de hilos de ejecución para realizar tareas de forma concurrente, dichos hilos jamás finalizan de forma abrupta. Se establece algún mecanismo de comunicación que indica al hilo que debe terminar.

6.8. Código Python

Salvo causa justificada, todos los módulos del complemento programados por el desarrollador deberán estar escritos en el lenguaje Python.

6.9. Reproducción de audio y síntesis de voz

Si el complemento incluye soporte para sintetizadores de voz, dichos sintetizadores no utilizan directamente los dispositivos de sonido del sistema. En su lugar, recurren al reproductor incluido en NVDA (módulo nvwave). Esto también se aplica cuando se reproducen archivos de audio en formato wav.

6.10. Uso del decorador script

Si el complemento añade gestos que el usuario puede ejecutar y declara su compatibilidad mínima con NVDA 2018.3 o una versión posterior, entonces se utiliza el decorador script en todos los módulos, en lugar del diccionario de gestos tradicional.

6.11. Inicio retardado (operaciones de red)

Si el complemento se conecta a Internet durante su fase de inicialización, dicho complemento espera a que NVDA esté totalmente cargado para realizar la conexión. Para ello, en el constructor de la clase GlobalPlugin, se debe registrar una función asociada al punto de extensión core.postNvdaStartup, que contiene el código que se conecta a la red.

6.12. Inicio retardado (todas las operaciones)

Si el complemento lleva a cabo una acción que podría verse afectada por alteraciones realizadas por otros complementos durante la fase de inicialización y está previsto que dichas alteraciones mejoren o complementen la funcionalidad prevista, entonces se retrasa la inicialización de todo el complemento hasta que NVDA se encuentre totalmente cargado.

6.13. Comprobaciones de estilo con Flake8

Si el complemento se evalúa con Flake8 utilizando el archivo de configuración de NVDA para Flake8, dicha evaluación se completa sin que se produzcan errores.

6.14. Comprobaciones de estilo con Flake8 (sin excepciones)

Si el complemento se evalúa con Flake8 utilizando el archivo de configuración de NVDA para Flake8, dicha evaluación se completa sin que se produzcan errores ni advertencias.

6.15. Tipado estático

Si el complemento es sólo compatible con versiones de Python 3.7 o posterior y se conoce de antemano el tipo de una variable, asumiendo que el tipo no va a cambiar, dicho tipo queda reflejado estáticamente en el código usando anotaciones de tipos.

6.16. Comprobación de tipado estático

Si el complemento utiliza tipado estático en todo o parte de su código, la herramienta Mypy es capaz de evaluarlo sin errores.

6.17. Esquema de versiones

El complemento utiliza un esquema de versiones de tres componentes basado en números. Dicho esquema permite que un software determine automáticamente cuál es la versión más reciente del complemento. Algunos ejemplos que se ajustan a este esquema pueden ser 3.2.5, 2023.8.15 o 20230815.0.0.

6.18. Canal de actualización

El complemento indica en su manifiesto qué canal debería usarse para buscar actualizaciones. La plantilla de complementos permite ajustar el canal en el archivo buildVars.py. Algunos ejemplos de canales son «dev» o «beta». En el caso de complementos estables, el canal debe estar vacío (updateChannel=None).

7. Almacenamiento en red

El complemento está alojado en un lugar seguro que toma medidas para prevenir eventuales daños al usuario.

7.1. Conexiones seguras

El complemento se encuentra alojado en un servidor al que se puede acceder mediante conexiones http seguras (HTTPS). Al realizar estas conexiones, el servidor proporciona un certificado SSL emitido por una autoridad certificadora de confianza, no revocado y vigente en el momento de la revisión.

7.2. Enlaces permanentes

El enlace a una versión dada de un complemento permanece activo, al menos, durante el periodo de vida útil de esa versión.

7.3. Suma de verificación

Para un enlace de descarga dado, la suma de verificación SHA256 del archivo resultante no varía a lo largo del tiempo, a menos que dicho enlace sea dinámico y se haya anunciado como tal. Por enlace dinámico se entiende un enlace que apunta a un complemento que se actualiza con mucha frecuencia, y para el que no compensa variar el método de descarga cada vez que se libera una nueva versión. Opcionalmente, se pueden emplear algoritmos más fuertes para calcular dicha suma de verificación, como SHA512.

7.4. Sin necesidad de aplicaciones de terceros

La información del complemento, así como el paquete de instalación del mismo en formato nvda-addon, es accesible empleando un navegador web, sin necesidad de utilizar aplicaciones de terceros. Por aplicaciones de terceros se entienden programas de intercambio de archivos P2P, clientes de mensajería instantánea, compresores de archivos o software específico para un sistema operativo concreto, entre otros.