Propuesta de tienda de complementos

La intención de esta propuesta es mejorar el proceso de extremo a extremo y la infraestructura de soporte para alojar complementos.
Este es el plan actual de NV Access, una simplificación de un plan más complicado y altamente automatizado.
La inspiración viene del repositorio de la comunidad del gestor de paquetes de Windows
Sería ideal un proceso altamente automatizado, y podemos mantener presentes esas ideas para trabajar en esa dirección.

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 usado para almacenar metadatos sobre liberaciones de complementos y APIs para acceder a estos datos.
Propósitos:
– Habilitar cualquier API, proceso, o infraestructura de apoyo necesaria para que los usuarios puedan explorar, buscar, instalar y actualizar complementos de NVDA.
– Una provisión segura y robusta de metadatos de complementos.
– No hay intención de soportar complementos de pago en esta fase.
– 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.

Acerca de la seguridad

Garantizar que el propio complemento sea seguro es un reto que no se contemplará en esta propuesta.
En vez de eso, este sistema puede garantizar que se revisan todas las actualizaciones a los metadatos de versiones de los complementos, y permite a los clientes del sistema (sitio web, NVDA) verificar que el paquete del complemento todavía coincide con lo que se revisó.

Debates pasados

• Sobre el proceso de revisión conversación en la lista de correo de complementos ha sido sobre revisar complementos.
• Si bien NV Access tiene algunas opiniones sobre el proceso de revisión, esta propuesta se ocupará primero de la mecánica del sistema en vez de las consideraciones de un revisor al mirar un complemento.
  Por ahora, nos referiremos a este paso como ‘Revisión del complemento realizada’.
  Más adelante se creará una «lista de comprobación de revisión de complementos».

No exclusividad

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á:
– Añadir un archivo a este repositorio (mediante una solicitud de cambios) que contenga metadatos sobre complementos publicados, incluyendo una URL de descarga y hash del paquete del complemento.
– Para facilitar las revisiones, alojar su complemento en GitHub en un repositorio abierto (no privado).
– Conseguir un «revisor de complementos» para revisar tu complemento y envío de metadatos, cuando este se apruebe se fusionará y estará disponible.

Si eres revisor de complementos

Como revisor de complementos, deberás:
– Mirar las solicitudes de cambio en el repositorio addon-store-submission.
– Sigue el proceso de revisión (sin documentar todavía).
– ‘Aprueba’ la solicitud de cambios, o ‘solicita cambios’ mientras proporcionas comentarios.

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

• Usar revisiones de GitHub para alojar envíos.
• Usar GitHub para almacenar los metadatos de los complementos disponibles en la tienda.
• Usar 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.
  Esto será de código abierto y extensible por la comunidad.

¿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 proporcionaron 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 addon-store-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
  • 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 addon-store-submission en GitHub

Esencialmente, este repositorio contiene metadatos sobre todas las versiones de los complementos aceptados que se incluyen en la tienda.
Los metadatos de una versión antigua de un complemento permanecen hasta que se eliminan explícitamente o se vuelven inválidos, 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 crítico.
Las versiones de los complementos se envían mediante una solicitud de cambios, añadiendo un archivo para esa versión del complemento.

Disposición

Carpeta raíz del repositorio:
– readme.md – Una guía para los envíos
– addons/publicador1/complemento1/versiónPrincipal.versiónMenor.parche.json
– addons/publicador1/complemento2/versiónPrincipal.versiónMenor.parche.json
– addons/publicador2/complemento3/versiónPrincipal.versiónMenor.parche.json

Nota: publicador.nombreComplemento será el identificador del complemento, y debe ser único y coincidir con el identificador del complemento de su manifiesto.

Ejemplo para el complemento de NV Access, ‘NVDA-OCR’: addons/nvaccess/nvda-ocr/1.6.0.json

Formato de los metadatos

Para una descripción completa del esquema, consulta _tools/addonVersion_schema.json
– Incluye un ejemplo de los contenidos del archivo.

Enviar una versión de un complemento

Requisitos previos:

• Familiaridad con GitHub
• Familiaridad con Git, incluido el trabajo con ramas.

Proceso para añadir una nueva versión de un complemento de NVDA:
1. Bifurca el repositorio addon-store-submission
2. En una nueva rama, copia el archivo _template_addon_release.json.
– Renombra o mueve el archivo a <publicador>/<nombreComplemento>/<versión>.json
– <publicador> es el nombre del desarrollador del complemento, por ejemplo «nvaccess»
– <nombreComplemento> es el nombre del complemento, por ejemplo «nv-speech-player»
– <versión> es la versión del complemento en formato principal.menor.parche. Por ejemplo: «2.4.1»
3. Crea una solicitud de cambios en el repositorio addon-store-submission
4. Se completarán los comprobadores automáticos de incidencias.
5. Se lleva a cabo una revisión (que da como resultado: pedir cambios, aprobar)
– Conducida por un revisor de complementos de NVDA.
– 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)
6. Cuando se mezcla la solicitud de cambios, el complemento aparece disponible en la tienda.

Comprobaciones durante la revisión

Muchas de ellas se pueden automatizar.
– Cada archivo modificado se ajusta al esquema
– La URL de descarga es válida
– El archivo de la URL coincide con el sha256
– El número de versión coincide con el manifiesto del complemento.
– El identificador del archivo (<publicador>.<nombreComplemento>) coincide con el campo ‘name’ del manifiesto
– El número de versión del archivo es válido y coincide con la versión en el manifiesto.

Comentarios

• Con este esquema de identificador muchos complementos tendrán que cambiar su identificador. ¿Esto hará que sea necesario mover la configuración de usuario previamente guardada a una nueva sección del archivo de configuración?

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

Detalles de generación de los datos de la API

Se configurará el servidor de NV Access para que responda a un webhook para descargar de este repositorio y ejecutar código que transforme
los datos.
Esto puede regenerar las vistas necesarias de los datos para las APIs expuestas

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 ‘addon-store-submission’.

El código correspondiente se alojará en la carpeta _tools. Esto permitirá a las partes interesadas generar la misma vista de
los datos localmente.

Visualizaciones de datos

Transformaciones requeridas de los datos:
– /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.
-Los contenidos de all.json son todos los datos (versiones de desarrollo y estables) de esta versión de la API de NVDA juntos.
– Los contenidos de cada complemento incluirán todos los detalles técnicos necesarios para que NVDA los descargue, verifique la integridad del archivo e instale.
– El archivo incluirá traducciones (si están disponibles) de los metadatos visibles.

La simplicidad de esto radica en que el servidor de NV Access puede simplemente redirigir estos archivos directamente cuando se le pregunte
«Cuáles son los complementos más recientes para NVDA con versión de API X» o «Cuál es la última versión de identificador-complemento para NVDA versión de API X».
Usar el servidor de NV Access como extremo para esto es importante en caso de que haya que cambiar la implementación o migrar
desde GitHub por cualquier motivo.

Epílogo

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».