1.Infraestructura.md

Primer hito: Estructura general del proyecto.

Descripción

Se trata de pensar o elegir un proyecto que se irá elaborando durante el año, creando los hitos para organizar el trabajo en el mismo. Lo esencial en este hito es entender qué tipo de proyectos se deben plantear para esta asignatura, describirlo correctamente en el repositorio en GitHub y documentar el proyecto elegido y los pasos que se van a dar en el mismo; también comenzar con las primeras especificaciones o al menos estructura general de las clases o módulos que se van a usar en el proyecto.

Prerrequisitos

Tener aprobado el hito 0 de proyecto y haber alcanzado el 80% de los objetivos del tema introductorio tras haber realizado los ejercicios propuestos.

Explicación

La metodología de esta asignatura está basada en la realización incremental, a lo largo de los hitos de la misma, de un proyecto personal de un microservicio REST o de websockets, un servidor de tareas o de streaming, que sería (en general, o podría ser) parte de una aplicación más grande. Por ello hay que empezar por el principio, escogerlo y, en su caso, los posibles compañeros con los que se pueda colaborar.

Esta colaboración se refiere más bien a otros proyectos (o microservicios) que se puedan usar desde el propio. En ningún caso se trata de desarrollar juntos un solo proyecto de la asignatura.

Algunas propuestas de proyectos están en el repositorio de la asignatura actual o en los de otros años, pero en general el estudiante podrá elegir resolver el problema que decida (y que haya incluido en el hito cero), siempre que sus funcionalidades que permita llevar a cabo todos los hitos del mismo dentro de esta asignatura y tenga entidad suficiente para ser evaluado como parte de la misma, es decir, creación de infraestructura virtual para un servicio web, desde uso de herramientas de configuración, prueba, despliegue, integración continua, herramientas de construcción, entornos virtuales y testeo. Lo importante en esta asignatura es la infraestructura (aunque el código deberá estructurarse de forma que sea testeable y desplegable, siguiendo siempre las mejores prácticas), por lo que conviene que se piense en un proyecto asequible de forma que dé tiempo a todo.

En el hito anterior se habrá hecho una descripción muy general del problema que quiere resolverse. En este tendrá que concretarse un poco más, explicando claramente qué servicios se piensan usar (bases de datos, servidores de mensajería, un sistema de ficheros específico, sistemas de log, compiladores, bibliotecas o aplicaciones externas determinadas) y, si se considera conveniente, ejemplos específicos de los mismos (es decir, qué biblioteca), pero en general no hace falta, más adelante se podrá ajustarse a las herramientas que se van a usar; simplemente se trata de que el estudiante entienda qué es un servicio web y qué se usa desde los mismos.

Se trata de describir las herramientas que se van a usar desde el microservicio, y en este caso lo esencial es que, con esta descripción, se muestre que se comprende lo que es un microservicio y qué se usa para programarlo. También el concepto de herramientas, que en general se debe entender como todo lo necesario para ejecutar un servicio determinado en la nube.

Aunque no es parte de la asignatura el llevar el proyecto completo a cabo, sí lo es construir toda la infraestructura necesaria para hacerlo, lo que se hará en el último hito. El avance en el código del proyecto se entenderá sobre todo si se ha ido construyendo un servicio web que cumpla lo que se ha dicho y esté testeado y listo para desplegar.

Un ejemplo suficiente puede ser simplemente decir que se va a crear un servicio web para gestionar un aspecto determinado de un negocio de silvicultura, así como el servicio de geolocalización de IoT del compañero McKenzie, en la misma clase.

Este hito incluirá el inicio del trabajo, cuyo objetivo final será llevarlo a cabo y desplegarlo en una infraestructura virtual. Pero un proyecto debe estar claramente especificado, porque sin especificaciones claras no hay tests claros, y sin tests no hay código. Estas especificaciones, en forma de historias de usuario, se tendrán que documentar de la forma que se considere más adecuada. En el inicio del proyecto, sólo es necesario que se hagan las imprescindibles para saber qué herramientas vamos a usar en el mismo.

Usar un repositorio de forma correcta no solo permite organizar el trabajo de desarrollo de forma más eficiente, sino que también contribuye a que sea más fácil colaborar con él y a la creación de buenos hábitos de trabajo colaborativo. Hay una serie de buenas prácticas, que incluyen las comentadas en el hito anterior, pero que además, en este hito, deberán de tener en cuenta lo siguiente.

• Trabajar siempre con hitos (milestones) y órdenes de trabajo (issues) en el repositorio. En este caso, el hito será la entrega de la práctica y las órdenes de trabajo las diferentes tareas necesarias para terminar el hito.

• Todo commit debe corresponder a una tarea que se haya establecido en el repositorio, toda tarea se cierra con un commit (simplemente incluyendo closes #[tarea], por ejemplo closes #1 si es el primer issue o tarea. Para referenciar una tarea, simplemente se pone el número de la tarea, por ejemplo

Avanza la tarea #1 porque se ha hecho x

• No incluir en el repositorio ningún fichero que pueda ser generado a partir del mismo: incluir un procedimiento para generar tales ficheros. Por ejemplo, ningún fichero compilado a partir de otros, o un PDF generado a partir de los ficheros LaTeX, o los ficheros generados por los entornos virtuales de ciertos lenguajes. Esos ficheros, además, se tendrán que incluir en .gitignore para que no aparezcan como "no seguidos" cuando se haga git status.

• No incluir en el repositorio ningún código que no sea propio, incluir en el mismo el procedimiento para incluir ese código en la compilación, generalmente en forma de fichero de requisitos. Si el código sobre el que se va a trabajar es directamente de otro repositorio, hacer un fork del mismo, no copiar los ficheros. La estructura de un repositorio siempre tiene que respetarse, y la mejor forma de atribuir correctamente los cambios es trabajar sobre el repositorio original modificado.

• No incluir ficheros binarios en el repositorio, aunque se necesiten en el proyecto. Para ello están los releases. En general los ficheros binarios son generados, así que esto es una simple consecuencia de lo de arriba.

• Si se va a usar algún proyecto anterior, hacer un fork del mismo, no copiar los ficheros y subirlos como contribución propia. Las contribuciones, siempre que sea posible, deben estar firmadas por la persona que las haya creado. Esto incluye si usas el mismo proyecto que usaste en esta asignatura en años anteriores.

Estas buenas prácticas se tendrán que seguir en todos los hitos subsiguientes del proyecto, empezando por este, y no hacerlo se penalizará. También se testearán a la hora de hacer el envío. Es decir, el hito actual será ya un hito del proyecto y dentro del hito tendrán que incluirse los issues que corresponda.

En este hito se podrá hacer ya un avance del código que se vaya a empezar a testear en el siguiente hito del proyecto. Este código tendrá la estructura general de las clases o módulos, así como los argumentos y signaturas de los métodos y subrutinas. Ese código deberá compilar, pero no es estrictamente necesario que tenga funcionalidad ninguna; ese código, además, tendrá que corresponder a las historias de usuario que se hayan planteado (y que se habrán incluido también en el repositorio).

Información adicional

Se pueden consultar los siguientes temas del curso 0:

• El amplio panorama de aplicaciones que se pueden diseñar para resolver problemas
• Diferentes servicios de uso habitual en despliegues en la nube
• Cómo especificar los requisitos y qué hacer para diseñar los primeros pasos de una aplicación.
• Cómo implementar clases abstractas o definir los interfaces de clase antes de implementar.

Entrega de la práctica

Subir los fuentes a GitHub y añadir al fichero el nombre del proyecto, el autor y un enlace al mismo y hacer un pull request.

Los avances en todos los hitos se reflejarán en el fichero README.md del mismo, que tendrá que estar estructurado como una descripción del proyecto, y con enlaces a información adicional requerida por los profesores para corregir el mismo.

El README no debe incluir pantallazos ni nada que no sea estrictamente descripción del proyecto en el hito en el que se encuentre en ese momento.

Cada proyecto tendrá su propio repositorio en GitHub. La explicación del proyecto deberá incluir los tipos de herramientas que se proyecte que se van a usar y las razones para hacerlo, una explicación de la infraestructura de la aplicación y los pasos que se van a dar para llevarla a cabo. Esta documentación se incluirá en el fichero README.md, aunque puede ser complementada utilizando capturas, detalles secundarios o de alguna manera más original que se os ocurra haciendo uso de gh-pages (este complemento se realizaría en el correspondiente directorio docs). Esta descripción de la aplicación irá evolucionando con los diferentes hitos, según se vaya avanzando en el proyecto, pero en ningún caso se incluirá explícitamente como un apartado o palabra "hito" en el proyecto.

Como mínimo, y para pasar los tests, esta entrega incluirá

• Un subdirectorio docs donde se pondrá material adicional (que se tendrá que enlazar desde el README en el apartado que se esté corrigiendo en ese momento).
• Un documento en Markdown, dentro de ese directorio, que incluya la cadena HU en el nombre del mismo.
• Uso de milestones/issues para añadir siempre código al repositorio. Los issues se cerrarán, cuando se hayan cumplido, con un commit.

Valoración

Se recuerda que es prerrequisito haber llevado a cabo el 80% de los objetivos del primer tema de la asignatura. Hasta que no se cumplan, no se evaluará este hito del proyecto. Si se cumplen los requisitos, la puntuación será:

• 2 puntos: Repositorio individual creado y entregado correctamente, con la licencia correcta, con todos los commits hechos por el propio estudiante y respetando las buenas prácticas que se iniciaron en el hito 0 y que se explican más arriba.
• 3 puntos: Documentación correcta que explique qué proyecto se ha elegido y por qué, y qué pasos se van a llevar a cabo para hacerlo. Esta descripción debe mostrar claramente que se ha comprendido el objetivo de la asignatura y que el proyecto corresponde a este objetivo. En caso contrario, se recibirán 0 puntos en este apartado.
• 1 punto: Historias de usuario escritas para empezar a trabajar a partir de ellas, y reflejadas en un directorio del proyecto; por supuesto, enlazadas desde el README.
• 2 puntos: avance de código, organizado correctamente en el repositorio según las mejores prácticas del lenguaje de programación elegido.
• 2 puntos: concedidos por originalidad de la aplicación, muestras de algún avance en la realización de la misma, grado de terminación, utilidad para la asignatura, cantidad de trabajo invertido.

Si el repositorio no existe, no tiene la licencia de software libre correcta, tiene algún error, no se ha hecho pull request correctamente, hay indicio de realización de la práctica en colaboración o algún otro tipo de plagio o no están los fuentes publicados, la práctica estará suspensa. En general, todos estos errores los capturará el sistema de test antes de que se envíe el hito y el estudiante podrá corregirlos. Si no se han alcanzado los objetivos indicados o no se ha superado el hito 0, no se evaluará hasta que se haya superado.