La intención de esta propuesta es mejorar de principio a fin el proceso y la infraestructura de soporte de los complementos.
Este es el plan actual de NV Access.
Sin embargo, antes de empezar a trabajar en él nos gustaría recibir comentarios de la comunidad de complementos, particularmente autores y revisores de complementos, ya que serán los más afectados.

El objetivo principal de todo esto es habilitar una «Tienda de complementos de NVDA», accesible desde dentro del propio NVDA.
En esta propuesta, la palabra «tienda» se usa para referirse al sistema que permite a los usuarios adquirir complementos, no hay intención de soportar complementos de pago.
Este sistema de «tienda» incluye cualquier sitio web, API, proceso, o infraestructura de apoyo para que los usuarios puedan explorar, buscar, instalar y actualizar complementos de NVDA.

Se han dado muchas consideraciones en esta propuesta para crear una tienda de complementos de NVDA más segura y robusta.
Aunque poco se puede hacer para garantizar que es seguro ejecutar un complemento, podemos asegurar que se ven todas las versiones, y que los usuarios ejecutan el complemento que creen que están ejecutando.
El proceso está pensado paraser tan transparente como sea posible, y que el estado actual de la tienda o el estado de envío de un complemento nuevo o actualizado pendiente de revisión sean simples de entender (para los desarrolladores).
El proceso debería dar la capacidad a autores y revisores de aprender y mejorar la tarea de revisar complementos.

Gran parte de la conversación reciente en la lista de correo de complementos ha sido sobre la revisión de complementos.
Aunque NV Access tiene opiniones al respecto, puede ser más productivo centrarse primero en los pasos del proceso.
Por ahora, nos referiremos a este paso como ‘Revisión realizada’.
Más adelante, se sugiere un hilo para ponerse deacuerdo en una «lista de comprobación de revisión de complementos».
Con la infraestructura adecuada, se pueden automatizar muchas comprobaciones y reducir la carga de los revisores.

Esta propuesta no tiene la intención de impedir que los autores de complementos desarrollen, publiquen y distribuyan complementos fuera de esta tienda.
NVDA todavía permitirá la instalación local desde un archivo .nvda-addon.

Si eres autor de complementos

Con esta propuesta, si un autor de complementos desea enviar su complemento para que sea visible en la tienda deberá:
– Alojar su complemento en GitHub en un repositorio abierto (no privado).
– Crear una incidencia en el repositorio addon-store-submission para cada versión del complemento que quiera publicar.
– Pegar en la descripción de la incidencia un enlace al commit o a la liberación de GitHub.
– Esperar a que se revise y se acepte o participar en las acciones de revisión y volver a enviar la nueva versión.

Si eres revisor de complementos

Como revisor de complementos, deberás:
– Mirar las solicitudes de cambio en el repositorio addon-store-submission.
– Estas incluirán un enlace al complemento que se revisa.
– Sigue el proceso de revisión (sin documentar todavía por aquí).
– Aprueba la solicitud de cambios, o solicita cambios mientras proporcionas comentarios y la cierras.
– Al aprobar la solicitud de cambio, pulsa el botón Merge para finalizar el proceso.

Consideraciones

  • Debería ser fácil localizar y conocer el estado de los envíos y revisiones.
  • Hacer posible la automatización de muchos pasos del proceso, ahorrando tiempo a los revisores.
  • Una vez enviada, la versión de un complemento jamás debería cambiar. Nada de cambiar el complemento en un servidor externo, debe ser actualizado en la tienda mediante el proceso de envío.
  • Se debe permitir a los autores revocar fácilmente una versión si es defectuosa o ya no recibe soporte. No debería presentarse más en la tienda, evitando así la instalación por parte de nuevos usuarios.
  • Se debe dar soporte a varias versiones de un complemento, en base a la versión de NVDA.
    • Ejemplo: versión del complemento 1.2.5 para NVDA 2019.3 y versión del complemento 1.3.2 para NVDA 2020.1
  • Se debe dar soporte en la tienda a los complementos en desarrollo, por ejemplo:
    • Complementos que se desarrollan con NVDA alpha/beta.
    • Complementos que necesitan comentarios de los usuarios desde el principio.
    • Los usuarios finales pueden elegir «Mostrarme complementos en desarrollo».

Descripción general

Se usan revisiones de GitHub para alojar envíos.
Se usa GitHub para almacenar los metadatos de los complementos disponibles en la tienda.
Se usan las acciones de GitHub (u otras integraciones) para automatizar la construcción del almacén de datos, y tantas comprobaciones de la revisión como sea posible. Todo esto será de código abierto y la comunidad podrá extenderlo.

¿Por qué revisiones de GitHub?

  • Gran parte del ecosistema de desarrollo de NVDA ya está basado en GitHub.
  • Maneja todo el CRUD (Creación, lectura, actualización y eliminación) de los usuarios, maneja la autenticación, y se puede determinar la relación entre un usuario y el repositorio de un complemento y sus permisos en ese repositorio. ¿Es realmente el propietario o un responsable de mantenimiento?
  • GitHub incorpora un sistema de revisiones que permite proponer cambios y debatir sobre ellos. Se puede utilizar para los envíos a la tienda y el proceso de revisión.
  • Las solicitudes de cambio de GitHub proporcionan una vista atómica del envío hacia la tienda.
  • Las partes interesadas pueden observar las solicitudes de cambio que les importan sin estar sujetas al ruido de otras solicitudes de cambio que no les importan.
  • El resultado de la solicitud de cambios es claro (abierta / mezclada / cerrada).
  • GitHub nos permite gestionar permisos para aceptar revisiones con más facilidad.

Infraestructura

  • Repositorio NVDA-Addon-submission en GitHub
    • Para autores y revisores de complementos.
    • Donde se envían las nuevas versiones de los complementos
    • Donde tienen lugar las revisiones de los envíos
  • Repositorio NVDA-Addon-store-data en GitHub
    • Para almacenamiento de metadatos de los complementos «de la tienda»
    • Este repositorio actúa como una base de datos back-end, pero es más transparente.
    • Como las necesidades son simples, serán suficientes algunas «vistas» preconfiguradas de los datos.
  • Servidor de NV Access – para proporcionar el punto de acceso para los metadatos de «complementos disponibles»
    • Aunque técnicamente no es necesario, proporciona una buena separación de la implementación.
      Si quisiéramos modificar nuestro mecanismo de almacenamiento, no se romperían las versiones anteriores de NVDA.

Repositorio NVDA-Addon-submission en GitHub

En esencia, este repositorio almacena referencias a todas las versiones aceptadas de los complementos que se han incluido en la tienda. Una referencia a una versión antigua de un complemento permanece hasta que se elimina explícitamente o se vuelve inválida, permitiendo su entrega a versiones antiguas de NVDA, o como respaldo si se revoca una versión más nueva porque se detecta un fallo.
Las versiones de los complementos se envían mediante una solicitud de cambios, añadiendo el commit de esa versión a un archivo que describe el repositorio en GitHub del complemento.

Disposición

Carpeta raíz del repositorio:
readme.md – Una guía para los envíos
addons/autor1/repo1.commits
addons/autor1/repo2.commits
addons/autor2/repo3.commits

Ejemplo de un complemento de NV Access, ‘NVDA-OCR’: addons/nvaccess/nvda-ocr.commits

Los contenidos de un archivo .commits constan de una lista (separada por saltos de línea) de hashes SHA de Git, uno por cada commit que podría estar disponible en la tienda.
Se ha diseñado este formato tan simple intencionadamente para maximizar la facilidad de edición, y minimizar el riesgo de corrupción del formato.
Se usan commits en vez de tags porque los tags pueden cambiarse después de su creación, y una colisión SHA es bastante difícil de provocar.
Esto es importante para eliminar la posibilidad de que un autor malicioso modifique su complemento tras la revisión, evitando el proceso de revisión.

Enviar una versión de un complemento

Requisitos previos:
– El complemento debe alojarse en un repositorio público en GitHub
– El commit que se enviará debe ser un archivo *.nvda-addon de NVDA válido si se comprime y renombra.

Proceso:
1. Se crea una solicitud de cambios en el repositorio NVDA-Addon-submission
– En ella se añade o elimina el SHA del commit (de la versión enviada) al archivo addons/autor/repo.commits adecuado.
– Consulta la sección Creación de la solicitud de envío que hay más adelante
2. Un bot añade un comentario en la solicitud de cambios con enlaces a las versiones del complemento que se añaden o eliminan
– Nota: la URL de este enlace puede ser construida desde ‘autor’, ‘repo’ y ‘commit’ de las líneas añadidas o eliminadas.
– Esto permite que el revisor examine el código en línea o descargue el complemento, consulta el encabezado «Ejemplo de mensaje de bot para una solicitud de cambios en NVDA-Addon-submission» para ver un mensaje de ejemplo.
3. Se lleva a cabo una revisión (que da como resultado: pedir cambios, mezclar o cerrar)
– Un bot puede realizar ciertas comprobaciones automatizadas o proporcionar información útil, consulta ‘Ideas de revisión automatizada’ más abajo
– Se hace una revisión manual siguiendo alguna lista de comprobación de revisión publicada (para que todo el mundo sepa qué puede esperar)
– Se pueden decidir más adelante los procesos automatizados y humanos, ya resolveremos estos detalles sobre la marcha para mejorar el proceso
4. Cuando se mezcla la solicitud de cambios, el complemento aparece disponible en la tienda.

Creación de la solicitud de envío

Para simplificar la implementación inicial de este proceso, la solicitud de cambios deberá crearse manualmente, más adelante se podrá automatizar, de tal forma que un autor sólo tenga que pegar un enlace en una nueva incidencia.

Se crea una nueva solicitud de cambios en el repositorio NVDA-Addon-submission.
1. Busca o crea un archivo: addons/autor/repo.commits
– Ejemplo: addons/nvaccess/nvda-ocr.commits
– Donde ‘autor’ es el nombre de usuario u organización a la que pertenece el repositorio de GitHub del complemento. Por ejemplo: para nvda-ocr es nvaccess
– Donde ‘repo’ es el nombre del repositorio. Por ejemplo: nvda-ocr
– Nota: crear el archivo significa que este es un envío completamente nuevo
2. Para enviar una nueva versión, añade el SHA del commit al archivo
3. Para las versiones del complemento que no estén soportadas, elimina el SHA del commit.
Esto se podría hacer con el editor web, aunque los usuarios de lectores de pantalla pueden sentirse más cómodos haciendo los cambios localmente con un editor de su elección.

Debido a que esto requiere que los autores de complementos hagan fork del repositorio NVDA-Addon-submission, la situación se vuelve un poco engorrosa.
Para agilizar este proceso, se podrían usar incidencias de GitHub.
– El autor del complemento escogería entre dos plantillas de incidencia:
– «Añadir versión de complemento»
– «Eliminar versión de complemento»
– En la plantilla, pegarían un enlace al commit o al tag que debería añadirse o eliminarse.
– La automatización crea automáticamente la solicitud de cambios y cierra la incidencia.
– Nota: en este enfoque sí es seguro usar un tag de Git, ya que se puede determinar el identificador del commit desde el tag. A continuación, se usa el commit en la solicitud de cambios y el resto del proceso no varía.

Ideas de revisión automatizada

Varias sugerencias de ideas para la revisión automatizada con el fin de agilizar el proceso.
– Comprobar la validez del manifest
– Proporcionar enlaces a diffs relevantes
– Comprobar si el usuario de GitHub que envía la solicitud de cambios es un responsable de mantenimiento de la versión del complemento que se envía.
– Plantearse usar integración continua (Appveyor) para comprobar que el complemento se instala limpiamente:
– Instalar NVDA (la versión más reciente soportada por el complemento)
– Instalar el complemento
– Reiniciar NVDA y comprobar si hay errores

Comentarios

Este enfoque requiere que el repositorio de un complemento sea un complemento válido (e instalable) una vez se comprima. Muchos complementos necesitan pasos adicionales en su construcción.
– ¿Se pueden usar las acciones de GitHub para ejecutar estos pasos y producir un resultado de compilación certificable?
– Si se puede certificar el código de un commit, y el código de las acciones de GitHub que producen el complemento, ¿significa que el complemento en sí está certificado?
– Si esto es así, se puede proporcionar la acción de GitHub junto a la plantilla de complemento.

Otras notas

  • Utilizando un repositorio de GitHub y un proceso basado en solicitudes de cambios, git blame y git log se pueden emplear para obtener más contexto sobre los complementos listados en la tienda. Por ejemplo:
    • Cuándo se aceptó el complemento
    • Qué pinta tuvo la revisión
    • Con qué frecuencia se aceptan actualizaciones de este complemento
  • GitHub permite asignar revisiones a revisores

Repositorio NVDA-Addon-store-data de GitHub

Contiene metadatos de complementos aceptados en la tienda.

Al usar un repositorio separado para el almacenamiento de datos se separan conceptos, se da mayor flexibilidad para gestionar permisos, y se facilita la verificación de cambios (por ejemplo en una solicitud de cambios o mediante automatización), y se simplifica el historial de commits (no hay commits automatizados del tipo «Se actualiza el almacén de datos»)

Los detalles exactos de implementación de este repositorio no se exponen a los usuarios, ya que por un lado tenemos al repositorio NVDA-Addon-submission alimentando con datos, y por otro está el servidor de NV Access recuperando y proporcionando datos a NVDA o a una tienda basada en web.
Esto significa que cambiar la disposición o la implementación de este repositorio no causará daños colaterales al proceso y se puede actualizar de forma independiente.
Aunque los detalles de este repositorio realmente no importan demasiado, no es necesario que sean muy concretos en este momento. Sin embargo, se proporciona una breve visión general del plan actual.

Descripción

Para cada versión de NVDA, los metadatos de cada complemento más reciente (con número de versión más alto) se añaden automáticamente, basándose en los datos de ‘NVDA-Addon-submission’.

Disposición

Carpeta raíz del repositorio:
/Versión de API de NVDA/addon-1-ID/release.json
/Versión de API de NVDA/addon-1-ID/pre-rel.json
/Versión de API de NVDA/addon-2-ID/release.json
/Versión de API de NVDA/all.json

Notas:
– ‘Versión de la API de NVDA’ será algo como ‘2019.3’, habrá una carpeta para cada versión de la API de NVDA.
– Los archivos pre-rel.json y release.json contienen la información necesaria para una entrada de la tienda.
En esencia, sería la URL de descarga del complemento (un zip del commit), y el resto de contenidos del manifiesto del complemento. Por supuesto, incluyendo descripciones traducidas en el manifiesto se puede crear una tienda de complementos multiidioma, aunque posiblemente no sea el objetivo de esta propuesta.
-Los contenidos de all.json son todos los datos (versiones de desarrollo y estables) de esta versión de la API de NVDA juntos.

La simplicidad de esto radica en que el servidor de NV Access puede simplemente reenviar estos archivos directamente al preguntarle «cuáles son los últimos complementos para la versión X de la API de NVDA» o «Cuál es la última versión de addon-id para la versión X de la API de NVDA». Usar el servidor de NV Access como un extremo para esto es importante en caso de que haya que cambiar la implementación o migrar fuera de GitHub por alguna razón.

Cómo llegan los datos

Con el objetivo de simplificar la explicación, se omitirán optimizaciones y detalles menores en esta descripción.

Se crea una acción de GitHub para responder a un nuevo commit en el repositorio NVDA-Addon-submission. Por cada commit de cada archivo *.commits del repositorio NVDA-Addon-submission, se recupera el manifiesto del complemento.

Se buscan los manifiestos que soporten cada versión de la API de NVDA.
Para cada versión de la API, se conserva el manifiesto del complemento de las versiones estables y de desarrollo más recientes (basándose en el número de versión).

Los archivos de manifiesto recuperados se usan para reconstruir los datos del repositorio y hacer commit.

Ejemplo de mensaje de bot en una solicitud de cambio de NVDA-Addon-submission.

Añadida versión.
- [Explorar código](https://github.com/nvaccess/nvda-ocr/tree/632d037dae906cd582ff4995628aa3fbaacd84e9)
- [Descargar zip](https://github.com/nvaccess/nvda-ocr/archive/632d037dae906cd582ff4995628aa3fbaacd84e9.zip)

Soporte para versiones de desarrollo de complementos

Será necesaria una actualización del manifiesto del complemento. Aunque en la propuesta se contempla, no estará en el ámbito del trabajo inicial.

Referencias inválidas de complementos

Al construir el almacén de datos, cualquier referencia a commits que no existen (repositorio eliminado, historial reescrito, etc.) obviamente se excluirán, ya que el manifiesto no se puede descargar. Aunque no es de alta prioridad, se debería implementar un mecanismo para actualizar el repositorio ‘NVDA-Addon-submission’ de tal forma que se eliminen estas referencias inválidas.

Terminología: versión de complemento frente a liberación de complemento

Ya que en esta propuesta se da soporte a los complementos en desarrollo, se ha intentado evitar el uso del término «liberación de complemento» en favor de «versión de complemento».