-
Notifications
You must be signed in to change notification settings - Fork 0
Documento del Proyecto
Este proyecto ha consistido en el desarrollo de una API con todo el programa de las jornadas InnoSoft. Además se ha implementado el registro de usuarios y staff de forma que queden registrados en la plataforma y puedan acceder a la misma; las ponencias y ponentes, de forma que se obtenga toda la información que se pueda necesitar de los mismos; y la posibilidad de que los usuarios se puedan apuntar a las ponencias desde el sistema. Además, para hacer más llevadero el tema de la asistencia se ha implementado un sistema de validación de la asistencia mediante código QR.
(debe dejar enlaces a evidencias que permitan de una forma sencilla analizar estos indicadores, con gráficas y/o con enlaces)
| Miembro del equipo | Horas | Commits | LoC | Test | Issues | Incremento |
|---|---|---|---|---|---|---|
| Cote Medina, Carlos | HH | XX | YY | ZZ | II | Descripción breve |
| Pantión Loza, Moisés | 40++ | 23++ | 892 | 14 | 12 | Modelo de Asistencia, test de Programa y Modelos, TravisCI |
| Pantoja Bas, Miquel Ángel | 82++ | 25++ | 758++ | 11 | 14 | Custom command, App de Registro, Permisos, custom user,test de registro y de carga, App Programa y participación en otros incrementos |
| Barba Roque, Enrique | HH | XX | YY | ZZ | II | Descripción breve |
| Gracia Barroso, Adrián | HH | 8 | 490 | 23 | 11 | Tests de vistas de participación, creación de asistencias, swagger e importación de datos desde excel |
| TOTAL | tHH | tXX | tYY | tZZ | tII | Descripción breve |
La tabla contiene la información de cada miembro del proyecto y el total de la siguiente forma:
- Commits: solo contar los commits hechos por miembros del equipo, no lo commits previos
- LoC (líneas de código): solo contar las líneas producidas por el equipo y no las que ya existían o las que se producen al incluir código de terceros
- Test: solo contar los test realizados por el equipo nuevos
- Issues: solo contar las issues gestionadas dentro del proyecto y que hayan sido gestionadas por el equipo
- Incremento: principal incremento funcional del que se ha hecho cargo el miembro del proyecto
Aunque no nos hemos integrado con ningún equipo como tal, si que nos hemos puesto a colaborar con ciertos miembros del staff de las jornadas InnoSoft. Además, tenemos la suerte de que contamos con dos miembros del staff en nuestro propio equipo:
- Comité de logística (Barba Roque, Enrique): coordinador del comité de logística.
- Comité de programa (Cote Medina, Carlos): integrante del comité de programa.
Esta organización ha sido bastante importante a la hora de obtener información sobre el funcionamiento interno de las jornadas, ya que de esta forma hemos podido tener de primera mano (especialmente con nuestros dos miembros que pertenecen a las jornadas) información relevante que nos ha permitido desarrollar la idea principal de forma rápida y sabiendo lo que se podía hacer y lo que no para posteriormente, proceder con el desarrollo.
Se explicará el sistema desarrollado desde un punto de vista funcional y arquitectónico. Se hará una descripción tanto funcional como técnica de sus componentes y su relación con el resto de subsistemas. Habrá una sección que enumere explícitamente cuáles son los cambios que se han desarrollado para el proyecto.
Para este proyecto, dado que hemos realizado una API, hemos desarrollado la parte programática, el back-end, y hemos omitido las vistas ya que no entraba en nuestro alcance. Además hemos creído que puede ser conveniente para que el año que viene un equipo pueda seguir desarrollando a partir de este proyecto para convertir la API en un sistema web completo.
Dicho esto, para explicar el funcionamiento del proyecto se va a dividir la explicación en las tres aplicaciones que tiene:
Registro: La aplicación de registro (o funcionalidad/feature de registro) es tal y lo que indica su nombre, un registro como cualquier otro. Sin embargo hemos decidido priorizar el UVUS antes que el nombre de usuario, de forma que al ser único pueda servir como ID.
Además, un usuario se puede registrar tanto como usuario normal como moderador/parte del staff de las jornadas. Esto es así porque hemos pensado que esta API no solo puede ser útil de cara a usuarios externos sino que a los mismos miembros de las jornadas InnoSoft les puede servir, tanto para publicar información como para llevar registro de asistencia.
Por lo tanto, un usuario que quiera hacer uso del sistema se registraría mediante un administrador del sistema, ya que solo pueden registrarse personas matriculadas en la asignatura de EGC. Dicho administrador sería el encargado de registrar al usuario en el sistema mediante llamadas a la API con sus correspondientes datos. De esta forma ya podría acceder a la función de inscripción a ponencias, por lo que este registro sería el primer paso.
Programa: La aplicación de programa es la primera que se pensó a la hora de desarrollar el proyecto, ya que trata el acceso a la información de las ponencias y los ponentes que las realizan, siendo este el principal motivo de desarrollo de la API. Posteriormente, debido a la simpleza del proyecto, decidimos ampliarlo con las otras aplicaciones que vienen descritas hasta convertirse en lo que es hoy.
Como he dicho, la función de esta aplicación no es otra sino la de poder obtener toda la información de las ponencias (titulo, horario, ponente, etc) así como de los ponentes que las realizan, todo esto pensado para que se pueda usar en otros servicios web de eventos.
Esto tiene dos funcionalidades posibles: o bien como usuario quiero ver información de las ponencias y por lo tanto, mediante llamadas a la API consigo dicha información (actualmente en formato JSON debido a la falta de una vista); o bien consumo dicha información mediante la integración de la API en mi servicio web de forma que presente una vista para los usuarios y añada de esta forma una funcionalidad a mi aplicación.
Participación: Por último, tenemos la aplicación de participación. Esta aplicación relaciona las otras dos y ofrece una herramienta que creemos que será de gran ayuda para el staff de las jornadas: verificación de asistencia mediante QR.
Primero, una vez hay un usuario y una ponencia registradas, dicho usuario puede inscribirse a esa ponencia para dejar por escrito que piensa (o quiere) asistir a dicha charla, pero como hemos visto este año, el recuento de la asistencia (especialmente en tiempos de pandemia donde las jornadas han de realizarse telemáticamente) tiene dos problemas:
- Es un proceso bastante tedioso y que hay que realizar a mano
- Es algo complicado ya que no siempre se puede saber con certeza si alguien de verdad está pendiente o si tiene la charla de fondo mientras hace cualquier otra cosa.
Respecto al segundo problema no podemos hacer gran cosa, pero para intentar resolver el primero hemos pensado en un sistema de verificación de asistencia mediante QR. Funciona de la siguiente forma:
Una vez el usuario se haya inscrito en la ponencia, el día de la ponencia se generará un código QR único para cada usuario. Será entonces cuando el moderador que responsable de este proceso deberá escanear el código QR para verificar su asistencia a la charla, quedando un registro en el sistema y por lo tanto, permitiendo llevar un control de forma más sencilla. Además se han añadido las posibilidades tanto de mostrar las asistencias a las que ha asistido un usuario como la de mostrar todos los asistentes que ha tenido una ponencia, facilitando así el recuento.
Su uso sería el siguiente entonces: un usuario ya registrado en el sistema se inscribe a una ponencia y el día de dicha ponencia, un moderador escanea el código QR que le facilitará el usuario, confirmando así su asistencia.
- Un usuario (antes de estar registrado) quiere acceder a información de las ponencias para ver a cuál le interesa asistir, por lo que accede a dicha información mediante:
- Peticiones a la API
- Webs externas que hayan hecho uso de la API y muestren dicha información
- Una vez haya consumido dicha información y ya sepa las charlas a las que desea asistir, se pone en contacto con el administrador (si es que no se registran a todos los matriculados de forma automática) para que realice el registro en el sistema.
- Después de haberse registrado puede acceder a la lista de ponencias para proceder a inscribirse a las que desee.
- Por ultimo, el día de la ponencia ha de asistir a la charla y verificar su asistencia mediante el escaneo del código QR que le facilitara el moderador de la ponencia. En caso de que no se escanee el código, no se verificará la asistencia y por lo tanto será como si no hubiese asistido.
- Finalmente, un miembro del staff de las jornadas puede acceder a la lista de asistentes de una ponencia o bien listar las ponencias a las que ha asistido un usuario para realizar recuento.
En paralelo con la descripción funcional, procedemos ahora a proporcionar la descripción técnica de nuestra API a través de las tres aplicaciones que la componen.
Permisos presentes en la aplicación: existen permisos de acceso que ofrecen granularidad al acceso de las funcionalidades de la API que van relacionadas con el grupo al que pertenece cada usuario registrado que realiza una petición. Estos grupos son Administrador, Moderador, Staff y Participante.
En primer lugar, tenemos la app de registro que cuenta con un único modelo que es un usuario que hemos creado de forma personalizada utilizando AbstractUser puesto que estábamos conformes con los atributos existente en el modelo de usuario presente en django por defecto, pero queríamos cambiar el username field para que se identificara con el uvus. La lógica de esta aplicación suministra las siguientes funcionalidades: Listar los usuarios, registrar, actualizar y eliminar un usuario. La lógica implementada requiere autorización mediante Token, por lo que todas aquellas peticiones que se realicen sin suministrar un Token no serán atendidas, además se restringe el acceso a las funcionalidades anteriormente mencionadas de la siguiente forma: para listar un usuario, bastará con ser un usuario administrador, moderador o staff. Para registrar, actualizar o eliminar un usuario deberá ser un usuario perteneciente al grupo administrador. A su vez, existe una funcionalidad que emplea Djoser para la recuperación del Token que nos permite realizar la autenticación proporcionando un uvus y una contraseña que correspondan con los de un usuario registrado actualmente en el sistema.
En segundo lugar, tenemos la app de programa, que presenta los modelos de Ponencia y Ponente. Estos modelos, hacen referencia al evento que se produce en las jornadas innosoft y a las personas encargadas de llevarlos y proporcionar su contenido respectivamente. Dada una ponencia, podemos saber el nombre de la ponencia, los ponentes que la ofrecen, la descripción de la misma, la fecha, el lugar y la categoría a la que pertenece. Dado un ponente, podemos saber sus nombres y apellidos, su teléfono y su correo electrónico. La lógica de esta aplicación nos permite visualizar un ponente, estemos o no registrados en el sistema, crear un nuevo ponente, actualizarlo o eliminarlo, solamente si somos administradores y de la misma forma para una ponencia.
En tercer lugar, tenemos la app de participación que cuenta con un modelo de asistencia. Este modelo relaciona a un usuario con una ponencia a la que decide asistir, y posee un atributo que confirma si esa asistencia ha sido validada o no. A su vez, cada asistencia posee un código autogenerado y encriptado. Este código es ofrecido al usuario a través de la API mediante una imagen QR codificada en Base64. Al leer este QR se obtiene ese código autogenerado, el cual utilizará el staff de las jornadas para introducirlo en la API y, junto con sus credenciales de staff, validarán la asistencia del usuario. Se utiliza un valor autogenerado, y no un identificador numérico normal y corriente, con el fin de evitar que un usuario corriente escanee el qr, se de cuenta de que es el identificador de su asistencia, y intente abusar del sistema.
A continuación se contará lo transcurrido a lo largo del diseño y desarrollo del proyecto, exponiendo las distintas versiones de diseño que han existido y como estas han ido evolucionando hasta el software que ha sido desarrollado finalmente.
En primer lugar, hemos comenzado con un Brain Storming para plantear una idea de proyecto a desarrollar, con eso obtuvimos la idea de desarrollar un sistema de conteo de asistencias, así como de registro de ponentes y ponencias. A modo de base para el desarrollo decidimos dividir todo el trabajo en 4 aplicaciones independientes entre si, estas son:
Asistencia: en esta aplicación se permitía a los alumnos inscritos a las diferentes ponencias generar un código QR a modo de identificación para su usuario para esa ponencia. Por otro lado, permitía a un moderador escanear los códigos QR anteriormente mencionados que muestren los alumnos al entrar a la ponencia, y así registrar su asistencia en la base de datos.
Autenticación: en esta aplicación se permitía el registro por parte de un administrador, y el inicio de sesión de los usuarios, haciendo uso de su UVUS como identificador único para su usuario.
Inscripción: en esta aplicación se permitía a los usuarios registrarse en una ponencia con su usuario, de manera que en la base de datos quedaban relacionados el usuario con la ponencia.
Programa: en esta aplicación se registraban las ponencias que se iban a realizar, incluyendo su horario, fecha y una breve descripción de su contenido, y además de esto su ponente, con algunos datos básicos para poder identificar a la persona.
Además, durante el Brain Storming inicial se decidió que el sistema sería una API que incluiría la función de generación de imágenes QR para la confirmación de la asistencia entre otras muchas más.
Más tarde, tras empezar con los primeros commits y pensar con más detenimiento el sistema a seguir, se decidió eliminar una de las cuatro aplicaciones y redefinir el sistema completo, con ello quedaron las siguientes 3 aplicaciones:
Participación: las anteriores aplicaciones “Asistencia” e “Inscripción” quedan fusionadas en esta aplicación ya que estaban altamente relacionadas la una con la otra. Tras realizar esta fusión queda que la aplicación dispone de las funcionalidades necesarias para que un usuario se inscriba en una ponencia, la funcionalidad respectiva a la generación de códigos QR para los alumnos asistentes a las diferentes ponencias, y la funcionalidad correspondiente al escaneo por parte de un moderador de los anteriormente mencionados códigos QR para la confirmación de su asistencia.
Programa: esta aplicación no varía con respecto a su anterior versión.
Registro: esta aplicación es correspondiente a la aplicación “Autenticación”, posee exactamente las mismas funcionalidades que fueron mencionadas antes pero se decidió renombrarla debido a que su anterior nombre generaba confusión.
Tras realizar estos cambios se pudo continuar con el desarrollo de la API sin ningún problema con respecto al diseño.
En un principio se comenzó a realizar los documentos necesarios para la creación del proyecto en la plataforma Google Drive, en la que poseíamos una carpeta compartida con todos los miembros del grupo de manera que fuera accesible para todos y se pudiera trabajar en el documento de manera simultánea, pero más tarde se decidió mover los documentos a la pestaña wiki de nuestro repositorio de GitHub. Debido a la necesidad de conteo de palabras para saber si la cantidad de texto era adecuada para cada uno de los apartados y por las dificultades existentes en esta plataforma para la redacción simultanea por parte de dos miembros de un documento, se decidió usar la herramienta Word para desarrollar el apartado que se desea modificar y una vez se deje de trabajar se añadirá a la wiki todo el contenido desarrollado de una vez para no interactuar con las adiciones a la página de los otros miembros.
Para poder administrarnos de forma sencilla y eficaz necesitábamos un tablero donde recopilar las tareas que debían abordar cada uno de los integrantes del grupo, hemos decidido usar el tablero de la pestaña projects de GitHub, en ella hemos dividido el proyecto en las tareas que hemos visto convenientes y estas han sido asignadas de manera aleatoria a los integrantes del grupo, este tablero posee varias columnas indicando el estado de la tarea, los estados disponibles son los siguientes:
To do: este estado corresponde a las tareas que pueden o no haber sido asignadas aún y que aún no han sido comenzadas por nadie.
In progress: este estado corresponde a las tareas que, tras haber sido asignadas, han comenzado su desarrollo pero aún no han sido finalizadas.
Stuck: este estado corresponde a las tareas que han sido comenzadas y tras un periodo de desarrollo sin ningún tipo de avance destacable ha sido anotado como atascado y espera la contribución de otro miembro del grupo para poder continuar.
To check: este estado corresponde a las tareas que han sido finalizadas y comprobadas por el correspondiente desarrollador, pero que aún debe ser comprobada por segunda vez por una segunda persona para ser validada.
Done: este estado corresponde a las tareas que han sido finalizadas y validadas por otro integrante del proyecto.
El tablero anteriormente mencionado debe ser actualizado a medida que se desarrolla el proyecto, así como modificado según vayan surgiendo cambios en el diseño del proyecto. Será responsabilidad del grupo al completo mantener el tablero actualizado a su propio desarrollo y a los cambios en el diseño que surjan en las reuniones.
También era necesario disponer de un repositorio en el que poder compartir y descargar código entre los miembros del equipo por lo que decidimos usar los repositorios de GitHub, en este hemos definido una estrategia tanto de ramas como de commits.
La estrategia de ramas consistía en la disposición de varias ramas según la tarea que tuvieran que hacer:
Main: en esta rama se encontraría el código inicial, y una vez el proyecto estuviera terminado y pulido se subiría la versión final del producto.
Develop: esta rama fue creada a partir de Main, y sería actualizada a medida que las distintas ramas que parten de esta fueran siendo finalizadas, una vez terminadas todas las ramas inferiores se pulirían errores y se subiría a Main.
Dev-: las ramas siguiendo esta estructura serían ramas de desarrollo creadas a partir de Develop, y en estas los desarrolladores crearían el código necesario para completar su tarea, además de los correspondientes módulos de testing necesarios para la comprobación correcta del código producido. Tras cumplir lo dicho anteriormente, la rama estaría lista para ser unida a la rama Develop.
La estrategia de commits consiste en el uso de un dialecto común para poder saber en que consiste cada commit realizado por los otros integrantes del grupo o con los de uno mismo. Esta consistiría en la siguiente estructura “tipo(objeto): descripción corta”. El tipo sería el objetivo del commit, principalmente se usarán los tipos “feat”(feature, código desarrollado para cumplir una de las tareas asignadas), “fix”( reparación de código en mal estado) o “test”(código desarrollado para la comprobación del correcto funcionamiento del código).
Para comunicarnos entre nosotros usamos Telegram debido a su comodidad, además de esto, realizamos reuniones semanales para discutir los avances realizados, ayudar a las personas que se encuentran atascadas y, normalmente, trabajar en grupo. Para las reuniones, debido a la situación en la que nos encontramos por la pandemia mundial del Covid-19, usamos la aplicación Discord, en la que podemos hacer llamadas grupales y compartir pantalla para poder exponer información o problemas a los compañeros y poder comunicarnos de manera eficaz.
El entorno de desarrollo que se ha utilizado por parte del equipo ha sido Visual Studio Code con la extensión para Python (v2020.12.424452561) con la versión de python 3.8 tanto para sistemas operativos Windows 10 como Ubuntu 20.04. Para no tener problemas entre las dependencias de este proyecto y las dependencias de otros proyectos en desarrollo presentes en nuestras máquinas utilizamos un entorno virtual, en el que instalamos todas las dependencias proveyendo un nivel superior de encapsulación. Para la gestión del código fuente utilizamos la herramienta git. Una vez trabajando en Visual studio Code se debe ejecutar el siguiente comando para seleccionar la versión de Python presente en nuestro entorno virtual:
Ctrl + Shift + P- Escribir select python interpreter y seleccionar el ejecutable de la versión de Python que se esté utilizando en el entorno virtual.
Frecuentemente surgen problemas con pylint relacionadas con Visual Studio Code que se solucionan de la siguiente manera:
Ctrl + Shift + P- Se busca el siguiente fichero
Preferences: Open Settings (JSON) - Dentro de ese fichero se añade la siguiente línea :
"python.linting.pylintArgs": ["--generate-members"]
Actualmente se utiliza una base de datos sqlite3. Para poder acceder a la base de datos y realizar operaciones se puede realizar de dos maneras distintas, una interactiva mediante el uso de DB Browser o por terminal mediante el uso del siguiente comando que nos permite acceder al terminal para aplicar transacciones sobre la base de datos sqlite:
python manage.py dbshell
Una vez dentro podemos realizar diferentes transacciones como por ejemplo la siguiente para cambiar el nombre de las tablas después de haber realizado un rename de una app:
UPDATE django_content_type SET app_label='<NewAppName>' WHERE app_label='<OldAppName>';ALTER TABLE <oldAppName>_modelName RENAME TO <newAppName>_modelName;UPDATE django_migrations SET app='<NewAppName>' WHERE app='<OldAppName>';
A parte de la utilización del lenguaje de programación python, se han utilizado las siguientes dependencias que quedan presentes en el fichero requirements:
- Django con v3.1.1 que es el framework de desarrollo utilizado y Django rest framework con versión v3.12.2 que es un toolkit para la creación de Web APIs.
- Para la autenticación y protección de los contenidos presentes en la API se ha utilizado django rest auth y djoser, con las versiones v0.9.4 y v2.1.0 respectivamente, permitiéndonos crear una API que utiliza Token para la autenticación facilitando de esta manera que la API sea stateless.
- Para ver el coverage de la aplicación utilizamos Codacy y para ello es necesario utilizar la dependencia coverage con la versión v5.3.
- Para una de las aplicaciones que componen el la API trabaja con códigos qr, por este motivo necesitamos las siguientes dependencias pycryptodome, qrcode y Pillow con las versiones v3.9.9, v6.1 y v8.0.1 respectivamente.
- Finalmente, contamos con una dependencia para el control del campo phone del modelo de Ponentes que es django phone field con la versión v1.8.1 y la dependencia drf-yasg para realizar la documentación de la API utilizando Swagger con la versión v1.20.0 .
Los pasos para instalar el sistema desarrollado para innosoft API son los siguientes:
- En primer lugar, ejecutar el siguiente comando para instalar todas las dependencias del sistema:
pip install -r requirements.txt
A continuación, se debe ejecutar el script de setup presente en la app de registro dentro del directorio de management/commands que por dentro ejecuta una serie de comandos. En primer lugar, prepara las migraciones de registro y las aplica. A continuación, se invoca un comando customizado, el group.py, que se encarga de crear los grupos necesarios por defecto que son los de administrador, moderador, staff y participante. Posteriormente, se ejecuta un migrate de los elementos por defecto, y se crean y aplican las migraciones de las aplicaciones de participación y programa. Para acabar, se ejecuta otro comando customizado que se encarga de crear nuestro usuario administrador, una vez finalizado este comando se lanza el proyecto en local.
Una vez que se ha lanzado el proyecto, es necesario el uso de la herramienta de Postman para comprobar el uso de la API y para poder realizar las diferentes peticiones.
En esta sección abordaremos cual ha sido nuestro plan de gestión de incidencias a la hora de abordar este proyecto.
Enunciemos pues cuales son los pasos para seguir a la hora de realizar la gestión de incidencias que se producen internamente dentro de nuestro grupo de desarrollo, en definitiva, cual sería el flujo de la gestión de la incidencia.
En primer lugar, se debe detectar la incidencia lo antes posible y así minimizar el alcance de las consecuencias de la misma. Las incidencias son reportadas inmediatamente son detectadas a través de varios canales: Telegram y Discord. De esta forma, garantizamos con certeza el día que fue detectada y que todos los miembros que componen el grupo de desarrollo se encuentran al tanto de la detección de dicha incidencia. Si la incidencia tuviera relación con algún commit se debería reflejar en el registro de que commit se trata proporcionando su identificador.
En segundo lugar, se debe registrar la incidencia de forma individual incluyendo la mayor cantidad de información disponible para así disponer de datos que puedan ayudar en si resolución. El registro contiene información de vital importancia sobre la incidencia, tales como si hay un commit relacionado con la misma, el estado, el tipo de incidencia que es, la prioridad, una descripción detallada, el día que se abrió, quien informó de su existencia, a quien se le asigna su resolución y la cantidad de días que ha estado abierto hasta su resolución. Estos últimos datos se deben cumplimentar a lo largo del ciclo de vida de la incidencia por diferentes miembros del equipo.
En tercer lugar, el miembro adecuado debe categorizar la incidencia ya que categorizarla y describir de que tipo es la incidencia nos permite en primer lugar clasificarlos, nos permite priorizar los problemas y nos proporciona también un seguimiento preciso de los diferentes incidentes ya que una vez que clasificamos los diferentes incidentes surgen patrones que nos permitirán cuantificar con qué frecuencia pueden darse nuevos incidentes y señalar tendencias.
En cuarto lugar, procederemos a priorizar las incidencias, para ello, debemos evaluar si un incidente puede ser solucionado de forma inmediata o si es necesario de la intervención de otro miembro del equipo. La prioridad de un incidente estará determinada, como ya hemos comentado, por el impacto que pueda suponer a los diferentes miembros de desarrollo, por tanto, el impacto lo entendemos como la medida del alcance del daño potencial que el incidente puede provocar.
Por tanto, definiremos que los incidentes graves, por ejemplo, deben ser solucionados en un tiempo menor debido a su impacto, de esta forma los priorizaremos por encima de otros incidentes. Por el contrario, los incidentes con baja prioridad serán aquellos que no supongan un impacto fuerte al desempeño de los diferentes miembros. Finalmente, los incidentes de prioridad media suponen un impacto, afectan a algunos miembros e interrumpen el trabajo hasta cierto punto.
Finalmente, una vez que ya hemos identificado, definido el tipo, asignado una prioridad de resolución y esta debidamente registrado podemos pasar a la resolución de la incidencia.
Una vez que empezamos a resolver la incidencia, debemos realizar un diagnóstico inicial de la misma. Una vez realizado el diagnóstico inicial es importante investigar y una vez que sabemos y se confirma que la hipótesis inicial del incidente se confirma ya podemos pasar a la resolución. Una vez encontremos la solución para la incidencia, esta debe ser aplicada realizando las pruebas necesarias para asegurar que la solución aplicada sea óptima y quede resuelta.
Cuando ya hayamos resuelto la incidencia, podremos pasar a la fase de cierre del incidente. Dentro de esta fase, actualizaremos el registro reflejando el nuevo estado y los días que ha ocupado para su resolución.
-
Prioridad de la incidencia: Definiremos la escala de la prioridad de los incidentes en graves, medios y bajos atendiendo siempre al tipo de incidencia que se trate a la hora de determinar la prioridad en la resolución de los mismos.
-
Estado de la incidencia: Definiremos el estado de la incidendia en abierta o cerrada, para referirnos si se trata de una incidencia que todavía no ha sido atendida y resuelta y para aquellas que ya han sido resueltas respectivamente.
-
Tipo de incidencia: Definiremos los incidentes en cuatro tipos. Incidentes críticos, incidentes altos, incidentes medios e incidentes bajos. Para definir de qué tipo es cada incidencia, nos basaremos en la cantidad de miembros del equipo que se vean afectados y el nivel de interrupción que esté causando dicho incidente. Este campo servirá para definir la prioridad que se le otorgue a una incidencia.
-
Roles asignados a la gestión de la incidencia: Definiremos los roles que intervienen en el proceso de resolución de la incidencia, entendiendo el rol encargado de solventarla, el encargado de documentarla y el que la ha detectado.
Las nuevas incidencias se deben registrar utilizando la siguiente plantilla:
| #Incidencia | Commit relacionado | Estado | Tipo | Prioridad | Descripción | Abierto el día | Informado por | Asignado a | Fecha de resolución | Cantidad de días abierto |
|---|---|---|---|---|---|---|---|---|---|---|
En nuestro caso, no nos encontramos directamente con incidencias externas recibidas por otros grupos puesto que no nos coordinamos con otros grupos que estén realizando algún tipo de incremento en un subsistema de Decide ya que nuestro desarrollo parte de cero y solamente dependemos exclusivamente de coordinarnos con los comités de las jornadas innosoft. La coordinación con dichos comités ha sido fluida debido al hecho que dos miembros de nuestro grupo de desarrollo pertenecen a dichos comités con una posición relevante en los mismos.
| #Incidencia | Commit relacionado | Estado | Tipo | Prioridad | Descripción | Abierto el día | Informado por | Asignado a | Fecha de resolución | Cantidad de días abierto |
|---|---|---|---|---|---|---|---|---|---|---|
| 6 | fix: Arreglada llamada a Codacy en django.yaml | Cerrada | Incidencia media | Media | Cuando se realiza una pull request o un merge en la rama develop se ejecuta el workflow de pruebas y se realiza el coverage de Codacy pero se produce el error (TabError: inconsistent use of tabs and spaces in indentation) | 7 Diciembre de 2020 | Miguel Ángel Pantoja | Enrique Barba | 8 de Diciembre de 2020 | 1 día |
La herramienta que hemos utilizado para gestionar las incidencias ha sido un tablero de Trello , además dichas incidencias también han sido registradas siguiendo las plantillas anteriormente mencionadas en la wiki de este repositorio.
Para la gestión del código fuente de la aplicación, se ha creado un repositorio de Git en Github (https://github.com/enriquebarba97/innosoft_api).
Este repositorio contiene las siguientes ramas de trabajo principales:
- main: Esta rama contiene la versión liberada más reciente de la aplicación. Su contenido solo se actualiza tras una release.
- develop: Es la rama que contiene la versión de desarrollo más reciente. Esta rama no debe contener trabajo sin terminar, ni funcionalidades o código a medias.
Para incorporar nuevas funcionalidades, herramientas o arreglar bugs se ha establecido un flujo de trabajo. Los pasos a seguir para incorporar cambios al proyecto son los siguientes:
- Se crea una rama a partir de develop, siguiendo el esquema tipo-nombre, dónde el nombre es la funcionalidad o elemento afectado de la aplicación, y el tipo es uno de los siguientes:
- dev para desarrollo de una nueva funcionalidad.
- fix para la reparación de errores.
- test para la modificación de tests.
- dep para la inclusión de herramientas de deployment
- Se desarrolla la funcionalidad en esta rama.
- Se crea un pull request a la rama develop una vez la tarea está terminada. Tras resolver los conflictos que puedan surgir, este pull request debe ser revisado y aprobado por al menos una persona del equipo, tras lo cual se puede mergear a la rama base.
Para garantizar que este flujo se cumpla, se ha configurado el repositorio de Github para que la rama develop este protegida, de manera que no se puedan subir commits directamente a ella, y que los pull request realizados a esta rama no puedan ser mergeados hasta que exista una revisión por parte de un miembro del equipo que lo apruebe.
Adicionalmente, al realizar un pull request a la rama develop, se empiezan a ejecutar los tests de integración continua (tests unitarios de Django y análisis de Codacy). Por norma general, no se debe mergear el pull request si los tests unitarios de Django no pasan satisfactoriamente. Sin embargo, en algunos casos, se ha observado cierta inestabilidad en los servidores de Codacy, lo cual puede provocar que, al intentar enviar los datos de cobertura de código, el workflow de Github Actions devuelva un fallo general, aunque los tests unitarios hayan tenido éxito. Así, cuando se detecte un error en el workflow de Github Actions, se debe comprobar si el problema ha sido el mencionado anteriormente y, si es así, se permitirá mergear el pull request.
También se define el procedimiento para realizar los commit. Un commit debe suponer una unidad de trabajo completa. Esto es, los commit deben contener la implementación completa de una funcionalidad, o la corrección de un bug. Los commit no deben tener código sin terminar o no funcional.
Para escribir los mensajes de los commit se sigue el siguiente formato:
<tipo>(<alcance>): <asunto>
<cuerpo>Resumen del mensaje (primera línea):
- Tipo
- feat (nueva funcionalidad)
- fix (arreglar errores)
- docs (cambios a la documentación)
- style (reparación de formato, sin cambios en el propio código)
- refactor (refactorización del código)
- test (añadir tests faltantes, refactorizar tests, sin cambios en el código )
- chore (cambios menores en el sistema de archivos y configuraciones, sin cambios en el código)
- Alcance: elemento afectado por el commit. Opcional, puede omitirse en caso de que los cambios sean difíciles de asignar a un solo componente, o estos tengan efecto a nivel global o a gran parte del sistema.
- Asunto: Pequeño resumen de los cambios realizados en el commit, de no más de 15 palabras
Cuerpo: Una explicación más extensa de los cambios introducidos en el commit
A continuación se expone un ejemplo de flujo de trabajo. Supongamos que queremos añadir una funcionalidad calculadora al componente de calculo de la aplicación.
- Se crea una rama nueva llamada dev-calculadora.
- Se trabaja sobre esta rama, realizando commits que contengan unidades de trabajo completas. Por ejemplo:
feat(calculo): Desarrollo de suma y resta
Creadas las funciones de suma y resta, asi como sus tests unitariosfeat(calculo): Desarrollo de multiplicacion y division
Creadas las funciones de multiplicacion y division, asi como sus tests unitariosTras haber acabado de implementar la funcionalidad calculadora, se crea un pull request a la rama de develop. Entonces, un miembro del equipo realizará una revisión del código. Si encontrase elementos que deberían se cambiados, se escribirá en los comentarios del pull request para notificar al autor. Tras implementar los cambios que se consideren oportunos, y una vez que no haya ningún otro problema con los elementos añadidos, se aprobará el pull request y se mergeara con la rama de develop
Se ha establecido también un procedimiento estándar para realizar una release del programa:
- Crear una rama release-version, donde version es el número de versión a liberar.
- Sobre esta rama se creará un tag con el número de versión, y una release de Github apuntando a esta etiqueta y con la información necesaria sobre la versión.
- Mergear la rama release-version en main y en develop. De esta forma, siempre tendremos en la rama main la versión oficial más reciente del proyecto.
Para gestionar la integración continua del proyecto, se comenzó utilizando el servicio Github Actions. Esta decisión se tomó a partir de diversos motivos:
- En primer lugar, desconocíamos el servicio anteriormente, y como utilizamos Github a diario, pensamos que sería buena idea familiarizarnos con los otros servicios que ofrecen, y esta era la oportunidad perfecta.
- Por otro lado consideramos que era mas adecuado desde un punto de vista de optimización, ya que Github Actions poseería una integración mas nativa con el repositorio que otras herramientas de integración continua.
Sin embargo, se acabó sustituyendo el servicio de Github Actions por el de Travis CI a petición del profesor. La finalidad de ambas herramientas era la misma: la automatización de los tests de forma automática. Ésto se llevaba en dos ocasiones diferentes: cuando se realizaba alguna modificación en el código, para asegurar que la modificación no afecta negativamente al resto del producto, y cuando se mergearan dos ramas distintas, para comprobar si la unión de ambas ramas, ya fuera automática o manual, no habia supuesto ningún problema en el resto del código. Pese a la integración a posteriori de Travis CI, se mantuvo a su vez la configuración de Github Actions, ya que, como supusimos, finalizaba múcho más rápido que la contraparte de Travis CI, lo cual nos permitía tomar ciertas decisiones mas rápidamente.
Una vez realizados los tests automáticos, sus resultados eran analizados por la herramienta de Codacy. Con esto, obteníamos diversas métricas con la cual asegurar que el código desarrollado, los cambios realizados o las distintas ramas integradas eran de calidad, facilitaban su legibilidad y mantenibilidad, y lo más importante, cumplía las expectativas y la funcionalidad esperada.
Para asegurar la calidad del producto desarrollado, se utilizaron las medidas ofrecidas por las herramientas previamente mencionadas. Si alguna de las medidas salía de los valores aceptables, se asignaba una nueva incidencia con el fin de arreglar el código. Esas medidas son las siguientes:
-
Porcentaje de tests pasados: en primer lugar, cualquier modificación realizada en el código debía pasar todos los tests creados hasta entonces. Esta medida, indicada por el servicio de Travis CI, fue la más importante durante el desarrollo, ya que, al contrario que el resto de medidas que podrían arreglarse un poco más tarde, que la modificación no pase todos los tests por completo es indicio de que la modificación rompe parte o totalidad del producto, lo cual es inadmisible. Medido en, como su nombre indica, el porcentaje de tests pasados frente al número de tests totales, su mínimo aceptable se estableció en 100%, es decir, todos los tests pasados correctamente.
-
Cobertura de los tests: Mientras que el porcentaje de tests pasados nos afirma que las modificaciones realizadas, y el producto en general, cumplen sus funciones, la cobertura de los tests nos confirma si realmente los tests comprueban todo el código del proyecto. Pese a que todos los tests pasen satisfactoriamente, si la cobertura de los tests es baja, existe una probabilidad de que parte del código inexplorado por los tests contengan errores fatales. Por este motivo, y gracias a que el alcance del proyecto es bastante reducido, se definió un mínimo de cobertura, medido en el porcentaje de líneas de código cubiertas por tests frente al número total de líneas de código, del 90%.
-
"Issues" en el código: desde excepciones no manejadas correctamente hasta imports no utilizados. Esta métrica, justo después de la de nº de tests pasados, fue la que nos resulta más útil a la hora de elaborar un código limpio y de calidad. Medido en un porcentaje, contrastado con la media de la industria que es del 20%, nosotros decidimos ser mas permisivos y subirlo a un máximo del 35%.
-
Complejidad del código: la complejidad de código supone una medida muy importante, sobretodo en el ámbito de la asignatura. Nos permite controlar la complejidad, y con ella, la legibilidad, de nuestro código. Ésto derivará en un código entendible y, lo más importante, fácil de mantener. Medido en porcentaje de archivos del proyecto complejos, el objetivo fue de mantener la medida en el 0%.
-
Duplicación del código: Medido en el porcentaje de archivos con algún tipo de duplicación frente al numero total de archivos, esta medida también asegura la mantenibilidad y fácil lectura del código del proyecto. Sin embargo, debido a la pequeña envergadura del mismo, fue de las medidas menos estrictas, estableciendo un máximo aceptable del 20%.
Por otro lado, la plataforma nos ayudaba con el análisis de los Bad Smells, ciertas características o estructuras en el código que sugieren un mal diseño o implementación del código. Estos bad smells, pese a parecer bastante inocentes a simple vista, se van apilando uno sobre otro, y en proyectos de mayor envergadura o un tiempo de desarrollo mayor, cuanto más se tarde en detectarlos, mayor repercusión tendrán en el proyecto.
En nuestro proyecto aparecieron todo tipo de bad smells, los cuales fuimos puliendo a medida que avanzaba el desarrollo. De entre todos, los que más destacaron fueron:
- Imports sin utilizar: mientras que desarrollabamos gran parte de la funcionalidad del producto, importabamos todos los ficheros que suponíamos nos harían falta en algún momento. Esto sin embargo no siempre fue así, y estos imports sobrantes no siempre fueron eliminados como es debido.
- Requisito de Docstrings: para un proyecto personal, o con un equipo muy pequeño, puede llegar a considerarse aceptable el no documentar los métodos del código. Sin embargo, teniendo en mente la mantenibilidad del producto, ya sea por nosotros mismos o por un grupo externo, documentar todo el código es un deber, aunque cabe decir que fue el bad smell que menos nos encontramos.
- Bloques de código repetido: para facilitar la legibilidad del código, se deben evitar todo lo posible los bloques de código repetido, ya sea por tener la misma funcionalidad o la misma estructura. Principalmente nos surgieron por el segundo motivo: la estructura. La definición de los distintos tipos de permisos de Django y sus grupos asociados poseen todos la misma estructura, pero deben ser definidos uno por uno.
Se explicarán los procesos, técnicas y herramientas para la gestión de la construcción e integración continua del proyecto. Evite poner información de las herramientas en sí que se pueda encontrar en fuentes bibliográficas o internet. Si es del caso haga referencia a ellas. Céntrese en los aspectos particulares de su proyecto en concreto:
- Proceso de integración continua que usa
- Herramientas que está usando para dar soporte a ese proceso
- Cuáles son los (al menos) 5 indicadores de calidad de los builds que ha utilizado para guiar su proceso. De detalles sobre este aspecto.
Gestión de liberaciones, despliegue y entregas (1.500 palabras aproximadamente) - QUIEN SE ENCARGUE DE DEPLOYMENT
Las liberaciones del proyecto (las versiones del producto listas para el despliegue) seguirán la estructura siguiente: versión X.y, siendo "X" las distintas entregas planificadas, las cuales suponen un gran incremento en el proyecto frente a la anterior, y siendo "y" las modificaciones que se realicen al proyecto entre una iteración y otra.
Dicho esto, este esquema de versionado no se aplicará hasta alcanzada la versión 1.0, la cual está programada para la entrega M3 del día 18 de Enero de 2021. Esto se debe a que nuestro proyecto, a diferencia de aquellos que extienden Decide, posee una funcionalidad mínima durante el comienzo del desarrollo, al menos hasta lo que constaría como la versión 1.0. Si fuera necesario, se asignarían las versiones 2.0 y 3.0 a los entregables M4 y M5 respectivamente.
Licencia Proceso con un apartado explícito de cómo ha elegido la licencia de software para su proyecto
Django Local
En primer lugar, la forma más sencilla de desplegar el proyecto innosoft-api es en una máquina local. Antes que nada, necesitamos el código del proyecto, por lo que clonamos el repositorio.
git clone https://github.com/enriquebarba97/innosoft_api.git .
Se recomienda el uso de un entorno virtual de Python, pero no es estrictamente necesario. Para crear y utilizar un entorno virtual de Python, el procedimiento es el sigueinte:
python -m venv ./entorno_virtual
source ./entorno_virtual
Una vez activado, si se desea, el entorno virtual, empezamos actualizando la herramienta Pip, la cual utilizaremos despues para instalar los requisitos del proyecto.
pip install --upgrade pip
Instalamos los requisitos del proyecto, definidos en el archivo requirements.txt.
pip install -r ./innosoft-api/requirements.txt
Para mayor comodidad, accedemos al directorio en el que se encuentra el archivo manage.py, a través del cual prepararemos y desplegaremos nuestra aplicación.
cd ./innosoft-api/innosoft-api
Una vez en el directorio, primero ejecutamos el comando personalizado setup, el cual prepara la base de datos, realiza las migraciones correspondientes y crea el superuser con uvus:"admin" y contraseña:"admin".
python ./manage.py setup
Por último, ejecutamos el comando de Django runserver, el cual desplegará la aplicación en localhost:8000.
python ./manage.py runserver
Heroku
Heroku es una plataforma en la que se nos permite desplegar aplicaciones en la web de forma gratuita. Para comenzar, se debe crear un proyecto en Heroku. Una vez creado, se puede vincular el repositorio en GitHub al proyecto de Heroku. Ésto nos permite decirle a Heroku, mediante un archivo Procfile, los dynos que forman nuestro proyecto. A su vez, podemos programar despliegues de actualización después de cada commit, los cuales esperan a que finalicen las herramientas de integración continua para no entrar en conflicto.
Docker
Para el despliegue de la aplicación mediante Docker, primero se deben seguir los pasos indicados en la wiki para instalar Docker (Guía). Una vez completados y, al igual que en el despliegue en loca, haber clonado el repositorio, se debe acceder al directorio docker.
cd ./innosoft-api/docker
En este directorio se encuentran todos los archivos relacionados con el despliegue del contenedor en Docker. Para ejecutar este despliegue, basta con ejecutar el siguiente comando:
docker-compose up
Esto creara la imagen del proyecto y con ella, lanzará un contenedor. Una vez el despliegue se haya completado, se podrá acceder a la aplicación de forma idéntica que en el despliegue en local. Para detener el despliegue, se deberá utilizar el siguiente comando.
docker-compose down
Esto detendrá el contenedor, pero no se perderán los datos almacenados en la aplicación.
se presentará un ejercicio con una propuesta concreta de cambio en la que a partir de un cambio que se requiera, se expliquen paso por paso (incluyendo comandos y uso de herramientas) lo que hay que hacer para realizar dicho cambio. Debe ser un ejercicio ilustrativo de todo el proceso de evolución y gestión de la configuración del proyecto.
La propuesta de cambio que se presenta en esta sección es la siguiente:
Queremos que el código QR de verificación que se genera para el proceso de las asistencias incluyan, además del id del usuario y el id de la ponencia, un número que se genere de forma aleatoria.
Para poder ejecutar este cambio primeramente se debería crear una incidencia en Trello siguiendo el enlace provisto en la sección "Gestión de Incidencias" dentro de este mismo documento y seguir el proceso definido en la misma. Pongamos que el cambio ha sido propuesto por Miguel Ángel y se lo ha asignado a Enrique. En este caso la incidencia vendría recogida tal que:
| Incidencia | Commit relacionado | Estado | Tipo | Prioridad | Descripción | Abierto el día | Informado por | Asignado a | Fecha de resolución | Cantidad de días abierto |
|---|---|---|---|---|---|---|---|---|---|---|
| 19 | cambio: QR code | Abierta | Incidencia leve | Baja | Se desea añadir un numero aleatorio al código del QR | 17 Enero de 2021 | Miguel Ángel Pantoja | Enrique Barba | Pending | Pending |
(Aunque la incidencia se deja recogida en Trello, para representarlo en GitHub lo hacemos con esta tabla)
A continuación, Enrique (la persona a la que se le ha asignado la incidencia) debería realizar un pull de la rama develop y crearse una rama llamada cambio-propuesto en su repositorio local:
git checkout develop
git pull
git checkout -b cambio-qrA continuación, una vez creada la rama en local sobre la que trabajar, procedemos a realizar el cambio. Como queremos generar un número aleatorio, necesitaremos la librería 'random' y se tendría que importar añadiendo, en el fichero models.py dentro de la aplicación de Asistencia (innosoft_api > innosoft_api > participacion > models.py ) la siguiente línea:
import random
Luego habría que generar el número aleatorio, en nuestro caso queremos que sea un número entre 1 y 999, por lo que la línea de código sería la siguiente:
random.randint(1,999)
Solo queda añadir dicho número al código, por lo que habría que modificar la actual línea 26 de ese fichero models.py de la siguiente forma:
uncoded_string = "Usuario%s Ponencia%s Random%d" % (self.usuario.pk, self.ponencia.pk, random.randint(1,999))
COMPROBAR QUE HA FUNCIONADO COTE
Una vez que hemos comprobado que nuestro cambio se ha realizado como queremos, tendríamos que realizar un commit a nuestra rama en local añadiendo los archivos modificados. Además, el commit debe llevar un mensaje siguiendo los estándares definidos en el apartado "Gestión del código fuente", por lo que los comandos a ejecutar serían los siguientes:
git pipo TODOUna vez realizado el commit, debemos de hacer un push para que los cambios queden subidos en la rama correspondiente en remoto. Esto se hace de la siguiente forma:
git pipo TODOPor último, Enrique debe de crear un pull-request para que otro miembro del equipo se encargue de comprobar que todo funciona correctamente. Para crear el pull request:
git pipo TODODigamos que Adrián se va a encargar de hacer la revisión del cambio. Para ello el tendría que descargarse la rama cambio-qr en su repositorio local tal que:
git pipo TODOUna vez con la rama en local, comprueba que el cambio funciona como se espera. En caso negativo, si el fallo se soluciona de forma fácil y rápida, será él quien se encargue de arreglarlo, realizar un commit y un push. En caso de que el error sea más complejo, ha de informar a Enrique sobre el fallo que hay y será Enrique el encargado de solucionar el error realizando otro commit sobre la rama cambio-qr. Una vez arreglado el fallo (o si el cambio se realizó de manera correcta y funcionaba como se esperaba desde el principio), Adrián realiza una review al pull-request de forma que se quede listo para el mergeo en la rama que corresponda, en este caso, develop.
el review se hace con consola?Por último, será otro miembro del equipo (para nuestro ejemplo, ponemos a Carlos) quien se encargue tanto de dar la última revisión (por encima) al código modificado como de arreglar los conflictos de merge en caso necesario:
git pipo TODOUna vez mergeado a develop, otro miembro del equipo (en nuestro ejemplo, ponemos a Moisés) será el encargado de descargar la última versión de la rama a la que se han mergeado los cambios (en este caso develop) y comprobar que todo funciona correctamente. Por último, Enrique (la persona que se ha encargado de realizar el cambio) tendrá que editar la incidencia para dejarla cerrada tal que:
| Incidencia | Commit relacionado | Estado | Tipo | Prioridad | Descripción | Abierto el día | Informado por | Asignado a | Fecha de resolución | Cantidad de días abierto |
|---|---|---|---|---|---|---|---|---|---|---|
| 19 | cambio: QR code | Cerrada | Incidencia leve | Baja | Se desea añadir un numero aleatorio al código del QR | 17 Enero de 2021 | Miguel Ángel Pantoja | Enrique Barba | 17 Enero de 2021 | 0 |
Tras haber acabado la realización del proyecto, podemos concluir que nos ha ayudado a experimentar el desarrollo "realista" de una aplicación, teniendo que investigar el funcionamiento del sistema sobre el que queremos trabajar, entendiendo sus funciones y sus anteriores decisiones de diseño y, posteriormente, aplicando nuestra propia funcionalidad, todo dentro del marco ya establecido sobre el que tenemos que movernos.
Además, nos ha ayudado a pensar en futuro, ya que al mismo tiempo que estabamos desarrollando el proyecto, pensábamos en posibles mejoras que podrían añadirse y que se comentan más abajo, proponiendose como trabajo para el siguiente curso.
En un apartado más colaborativo, hemos adquirido experiencia en el ámbito de trabajar en grupo de forma simultánea. El uso de Git es indispensable hoy en día y a más miembros haya en un grupo trabajando a la vez, más problemas pueden suceder, por lo que hay que saber tratar con esta herramienta. Hemos tenido que investigar comandos de git que desconocíamos y nos hemos familiarizado con el uso de Git por consola, algo que nos va a resultar bastante útil ya que, aunque algo menos amigable que GitHub, GitDesktop u otras herramientas similares, es bastante más personalizable y se entiende mejor qué es lo que se está realizando en todo momento, por lo que nos llevamos bastante información nueva que nos va a servir para todos los futuros proyectos que realicemos.
Dado que nuestro proyecto ha consistido en desarrollar una API, como trabajo para el siguiente curso proponemos el desarrollo de la interfaz visual y todo el apartado de fron-end, de forma que con ambas partes se pueda realizar una herramienta bastante útil para el desarrollo de las jornadas InnoSoft.
Además, sería interesante el insertar un lector de código QR en la vista para que se pueda abrir desde el móvil a la hora de regular las asistencias de las ponencias.