En el siguiente documento se presenta un conjunto de pautas que deberían seguir tanto los desarrolladores actuales de complementos como aquellos que potencialmente pueden serlo:

General

  1. Usa la plantilla de complemento que se encuentra en https://github.com/nvdaaddons/addonTemplate
  2. El nombre del complemento no debería contener palabras tales como «nvda», «plugin», «appmodule», «globalPlugin» en su composición, el usuario no debería tener que preocuparse de detalles de la implementación.
  3. El nombre del complemento debería tener la forma «nombre», o «primeroSegundo», o «primero_segundo»
    ejemplos: «word», «dropbox», «extendedWinamp», «resourceMonitor» o «resource_monitor». El sistema automatizado no soporta guiones en el nombre.
  4. Asegúrate de que tu complemento se libera bajo la licencia GPL o una equivalente compatible con ella, ya que el propio NVDA es GPL y el alojamiento de los complementos corre a cargo de NVDA.

Versionado

  1. Usa el formato de revisión mayor punto menor, ejemplo: 1.0, 1.1, etc. Un versionado basado en fecha como 2016.1 o 16.07 también sirve (lo que se denomina una entrega continua).
  2. Cuando se añadan funciones nuevas, actualiza la revisión mayor: 2.0, 3.0, etc. Para versiones basadas en fecha, simplemente elige una como versión mayor.
  3. Al liberar una versión que sólo incluya actualización de traducciones, actualiza la revisión menor: 3.1, 3.2, etc. Asegúrate de que los nuevos idiomas se mencionan en el mensaje de un commit. No hay necesidad de añadirlos al archivo readme.md.
  4. Añade un tag a cada versión en git, y recuerda que los cambios de tags (etiquetas) se envían de una forma especial al repositorio al hacer push.

Proceso de liberación

  1. Después de liberar la nueva versión de un complemento, si sabes que harás cambios a la nueva versión mayor y la anterior, usa una rama separada de mantenimiento para la versión vieja (1.x, 2.x, etc.) y manda tus commits a esta rama. Luego, mézclalos con la rama de la versión nueva. Si se usa un sistema de entrega continua o versiones basadas en fecha, realiza el desarrollo desde master.
  2. Después de crear una versión estable (y generar el paquete de instalación del complemento), actualiza el número de versión para indicar que está en desarrollo la siguiente versión, ejemplo: 3.1-dev. Por tanto, ten en cuenta que el número de versión en este caso debería ser 3.0 durante unos pocos minutos, y debería cambiarse a 3.1-dev para indicar que hay un desarrollo en curso.
  3. Una versión estable (tales como 1.0, 2.0, 2.1, etc.) debería publicarse como tal sólo si no se ha informado de fallos graves en las últimas dos semanas después del commit más reciente. Un complemento (o la versión de un complemento) bajo desarrollo activo y para el que se hacen commits regularmente debería listarse como un complemento en desarrollo para que los usuarios hagan pruebas.
  4. Las versiones estables no deben hacerse con menos de dos semanas de diferencia, para que los traductores puedan trabajar en ellas, a menos que se solucione un fallo crítico y de altísima prioridad.
  5. Informa de la disponibilidad de esta nueva versión en distintas listas de correo de NVDA, como la lista de complementos.
  6. Si es posible, los creadores de complementos deberían utilizar el flujo de trabajo oficial de NVDA para gestionar sus traducciones. Para más información, consulta el artículo hacer un complemento traducible mediante el sistema de traducciones de la comunidad.

Estilo del código

  1. Haz el indentado o bien con cuatro espacios, o con un tabulador. La segunda opción es la más recomendada.
  2. Todos los mensajes presentados al usuario deberían ser traducibles (salvo excepciones), si somos los creadores del mensaje.
  3. Los mensajes que contengan varios comodines ‘%s’ o ‘%d’ o siguen el formato:
    «%(name)s .. %(name2)s» deberían reescribirse como:
    _(«{name1} .. {name2}»).format(name1=v1, name2=v2)
  4. Los mensajes traducibles deberían tener un comentario para traductores para explicar dónde o cuándo se presentarán al usuario, para que los traductores puedan probar el resultado de su traducción fácilmente al instalar el complemento. Si la cadena traducible es similar a alguna contenida en los mensajes principales de NVDA, indícalo también.
  5. Si tu complemento necesita guardar cualquier ajuste de configuración:
    • no uses:
      config_file = os.path.join(config.getUserDefaultConfigPath(),»addonName.ini»)
    • usa en su lugar:
      config_file = os.path.join(globalVars.appArgs.configPath,»addonName.ini»)
  6. A menos que haya una buena razón para lo contrario, se recomienda usar config.conf para que los ajustes del complemento (especialmente si lleva extensiones globales) estén disponibles al usar perfiles de configuración.
  7. Cuando trabajes en una nueva característica importante o modifiques una existente, crea o utiliza ramas distintas a la rama master, ya que ayudan en el proceso de mezcla y revisión de código (a través de solicitudes de cambio) y a encontrar fallos fácilmente.

Documentación y órdenes de teclado

  1. Si añades nuevas órdenes de teclado como parte de tu complemento, consulta la referencia rápida de órdenes de NVDA y las órdenes de otros complementos oficiales de la comunidad antes de asignarlas.
  2. Para NVDA 2013.3 o posterior: si quieres categorizar tus órdenes de teclado (para una identificación más sencilla y que el usuario pueda cambiarlas), asigna una categoría existente en NVDA (si tu complemento mejora partes de NVDA como una orden nueva para abrir un diálogo de preferencias), o bien crea nuevas categorías si es necesario (si el complemento ofrece otras características como el soporte para funciones avanzadas de un programa).
  3. Por favor, ofrece un archivo readme.md en el que se listen los cambios entre versiones, atajos de teclado (si los hay), notas de uso y otra información relevante. Inspírate en cualquiera de los complementos oficiales ya existentes.
  4. Los archivos addon/doc/*/readme.md no deberían traducirse a mano y enviarse al repositorio, sino que deberían generarse y enviarse desde el sistema oficial de traducciones.
  5. Si traduces un complemento a tu idioma y lo envías a Git, por favor notifícaselo al responsable de traducción de NVDA en tu idioma para que no se duplique el trabajo. En cualquier caso, siempre es mejor mantener las traducciones en el sistema oficial de traducciones.

Revisiones al compartir un complemento

  1. Si todavía no lo has hecho, suscríbete a la lista de complementos situada en groups.IO.
  2. Solicita una revisión básica (licencia y derechos de autor, documentación, experiencia de usuario básica, seguridad, etc.). Al hacerlo, asegúrate de proporcionar el enlace al código fuente del complemento, junto con instaladores, si los hay.
  3. Si se supera la revisión básica, puedes declarar el complemento estable o esperar un tiempo para resolver comentarios expuestos durante la revisión antes de liberar una versión estable. Si decides esperar, tienes la opción de liberar una versión de desarrollo para que se hagan pruebas más extensas.
  4. Si la revisión no se supera, se te pedirá que sigas las instrucciones de los revisores. Una vez soluciones sus comentarios, pide a tu revisor que haga la revisión una vez más. Esto se hace hasta que el complemento supere la revisión básica, pero es extraño.
  5. Si tu complemento supera la revisión básica, puedes pedir una revisión más profunda. Esta implica mirar los mensajes del complemento, compatibilidad con los controles del motor de interfaz gráfica, fallos potenciales y demás. Es decisión tuya reaccionar a los comentarios de la revisión en profundidad y solucionarlos cuando tengas tiempo.