Definiciones:

En el texto que viene a continuación, para abreviar escribiremos refiriéndonos al género masculino, pero por supuesto hacemos referencia a ambos sexos.

Autor: el significado estándar de autor, o el responsable de mantenimiento actual de un complemento.

Revisor de apoyo: un miembro del equipo de complementos de NVDA que haya demostrado habilidades técnicas, justicia, dedicación y disposición para ayudar a otras personas.

Un autor no puede actuar como revisor de apoyo si es el autor del complemento, incluso si forma parte del equipo de complementos.
Para un complemento diferente, se pueden intercambiar los roles.

Flujo de trabajo

  1. Un autor desea crear un complemento, por lo que hace fork de la plantilla de complementos proporcionada por la comunidad a su espacio personal de GitHub, y la renombra con el nombre del nuevo complemento.
  2. Él procede a desarrollar el complemento, haciendo commit y push a su repositorio personal.
  3. Cuando su complemento está listo, el autor informa a la lista de complementos, y solicita comentarios generales.
  4. En este punto, la mayor parte de los comentarios probablemente son de pruebas de los usuarios, pero puede haber algo de revisión de código con un poco de suerte.
    Por favor, ten en cuenta que la comunidad no puede garantizar la calidad o el contenido del complemento, por lo que si un usuario ejecuta el complemento sin mirar el código, es bajo tu responsabilidad.
  5. El autor procesa los comentarios, regresa al paso 2, o si tiene comentarios suficientes continúa al paso 6.
    No se espera que el autor acepte todas las solicitudes, por lo que si eres un usuario y el autor no cree que tu solicitud de características encaje con su complemento, se recuerda a usuarios y autores que actúen de forma civilizada.
    Se espera que el autor corrija y atienda todas aquellas solicitudes razonables relacionadas con recordatorios de falta de copyright, licencia o mejoras en la documentación.
  6. Asumiendo que hay suficiente interés por parte de los usuarios para que el complemento esté disponible en el sitio web de la comunidad, el autor solicita que un revisor de apoyo haga fork de su complemento a la organización nvaaddons.
  7. Por favor, recuerda que los complementos se aceptan según el criterio de los revisores de la comunidad. Todos son voluntarios, y no están obligados a hacer nada. Por supuesto, si formas parte de la comunidad y ayudas revisando el código de otras personas, la gente mostrará una buena disposición y será más probable que tu código se revise.
  8. El revisor de apoyo se asegura de que haya una licencia, información de copyright, un archivo léame, que el complemento hace lo que se supone que hace, y es adecuado en términos de seguridad.
    Se espera que el revisor de apoyo haya leído cada línea del código de la extensión global del complemento, los módulos de aplicación y otros archivos (sin incluir bibliotecas externas), para analizar riesgos de seguridad antes de hacer fork.
    En este contexto, seguridad significa: que el complemento no lee archivos inesperados del usuario del ordenador, no sube nada a Internet, y no descarga nada inesperado.
  9. El revisor de apoyo hace fork del complemento a la organización nvdaaddons.
  10. Las incidencias y las solicitudes de cambio deberían ir al autor y al repositorio del autor, y no al fork de la comunidad.
    Por supuesto, los usuarios todavía pueden continuar interactuando con el autor del complemento usando la lista de correo de complementos.
  11. Se espera que el autor del complemento añada la copia que ha hecho la comunidad de su repositorio como origen remoto, de tal forma que pueda añadir y actualizar traducciones.
  12. El revisor de apoyo podría tener que hacer las siguientes tareas en el repositorio de la comunidad después del fork:
    Eliminar cualquier rama diferente de master, añadir información sobre compilación automática, webhooks, etc.
    Añadir una regla de protección en master para que nadie haga push accidentalmente, y se necesite una solicitud de cambios con al menos un revisor (incluso administradores).
    Consulta otros pasos relacionados con el flujo de trabajo de las traducciones aquí.
    Crear una rama stable.
    Añadir reglas de protección a stable de tal forma que el sistema de traducciones pueda hacer push, pero todos los demás deban hacer una solicitud de cambios (incluso los administradores).
  13. El revisor de apoyo mezcla la rama master en stable.
  14. El revisor de apoyo dispara una liberación.
    En ella sólo se debería incrementar el número de parche (último dígito del número de versión), por ejemplo pasando de v1.0.0 a v1.0.1.
  15. Tras un periodo de tiempo, el autor del complemento desea publicar una versión nueva, y para ello hace una solicitud de cambio desde su rama master a la rama master de la copia de la comunidad.
  16. Un revisor de apoyo revisa la solicitud de cambio garantizando de nuevo la seguridad, archivo léame actualizado, etc, y puede pedir que se haga más trabajo antes de que la solicitud se acepte. Sólo deben revisarse los cambios desde la última versión.
  17. Una vez se mezcla la solicitud de cambio en master, el revisor de apoyo aumenta la revisión mayor o menor según haya indicado el autor. Por ejemplo, se podría eliminar el «-dev» de la variable de versión.
    Vuelve al paso 13.

Consideraciones

Se han tenido en cuenta las siguientes consideraciones al proponer este flujo de trabajo de complementos.

  1. Seguridad de los complementos.
    Según crece la comunidad de autores de complementos y usuarios de NVDA, queremos proporcionar una sensación de confianza en que hacemos lo correcto, de tal forma que un usuario se sienta seguro al instalar y actualizar complementos, y que estos complementos puedan instalarse en escuelas, universidades, bibliotecas públicas, etc.
    Los autores de complementos se toman nuestro trabajo voluntario en serio, y agradecemos la confianza depositada.
    Por tanto, el último paso para liberar una nueva versión lo hace la comunidad, no el autor del complemento, ya que queremos que el producto final sea plenamente fiable.
  2. Entorno de aprendizaje compartido.
    Dando críticas constructivas y sugerencias a los demás, construimos algo mejor y más fuerte, porque nadie es perfecto y aprendemos de los demás.
    Una crítica al código no es una crítica al autor, simplemente es una recomendación para mejorar el código, ya que al revisor le importa la calidad de tu código.
    Si piensas que un revisor ha pasado algo por alto al revisar el complemento de otra persona, no dudes en proporcionar tu revisión, ya que nadie tiene el monopolio a la hora de proporcionar comentarios.
  3. Reducir la sobrecarga existente de los revisores de complementos.
    En el momento de redacción de esta propuesta, hay aproximadamente 70 complementos oficiales, y gestionarlos no es algo simple ni directo.
    Por desgracia hemos acabado en una situación desastrosa, con repositorios en GitHub y BitBucket, y ciertos trabajos manuales que deben hacerse en un servidor.
    Se ha sentido que se ha invertido más tiempo en gestionar el sistema que en la interesante tarea de revisar y proporcionar comentarios, por lo que deberían automatizarse más pasos.
    Esta automatización aún no se encuentra en funcionamiento, pero si por consenso se determina que este flujo de trabajo es razonable, comenzará el trabajo en la automatización adicional.
    Con menos requisitos para un potencial revisor de complementos, con un poco de suerte habrá más revisores de la comunidad que tendrán un rol responsable y activo, ya que sólo sería necesario revisar y mezclar código, y no requiere una gran inversión de tiempo.

Temas para debates futuros.

  1. ¿Tiempo mínimo entre liberaciones?
  2. ¿Cómo se podrían (¿Deberíamos hacerlo?) acomodar las versiones de desarrollo?