0.Repositorio.md

Hito 0: Descripción del problema a resolver usando correctamente git y GitHub

Resumen

En este hito tenemos que mostrar que entendemos correctamente el concepto de aplicación que se va a desplegar en la nube, así como demostrar nuestro conocimiento del uso de herramientas habituales en desarrollo de software.

Descripción

En este hito 0 del proyecto se trata de poner a punto las herramientas que se van a usar para comunicar los objetivos, los ejercicios y las prácticas durante el resto del curso. Durante el mismo, se busca también que se interioricen una serie de buenas prácticas a la hora de trabajar con repositorios de git.

git y GitHub son herramientas suficientemente conocidas y documentadas y esenciales en el desarrollo de software hoy en día. Trabajar con ellas de forma fluida es un prerrequisito para poder trabajar correctamente en esta asignatura, empezando por este mismo hito.

Para ello, se creará un repositorio, que se usará durante el resto de la asignatura, para mostrar el avance el proyecto de despliegue de una aplicación en diferentes hitos. Este repositorio contendrá obligatoriamente

• Fichero con el nombre, formato y extensión convencional, que explique qué problema trata de resolver el proyecto, en qué va a estar basado y algunas referencias relacionadas con el mismo, por ejemplo, si se va a usar una práctica de otra asignatura o el trabajo fin de grado ya terminado o simplemente un proyecto personal que se considere interesante.

No estamos recomendando que se use ninguno de ellos. De hecho, preferimos que no se haga. En todo caso, eso es tema para el siguiente hito.

• Licencia que se va a usar en el proyecto.

• Otra serie de ficheros de uso habitual en repositorios, sobre todo los que se generan automáticamente cuando se crea un repositorio.

• Documentación sobre la realización de este proyecto. En este hito no va a hacer falta, pero conviene que se cree un documento aparte usando los diferentes mecanismos que ofrece GitHub y se enlace desde el fichero donde se explique el proyecto, en el directorio principal.

La corrección de los hitos siempre se hará a partir de este README, por lo que lo que no se enlace, será difícil tenerlo en cuenta, sobre todo porque es imposible encontrarlo.

Estas buenas prácticas se comprobarán a lo largo del resto de los proyectos. Si no se siguen correctamente el hito del proyecto correspondiente será calificado a la baja, y en algunos casos simplemente no pasará los tests.

Prerrequisitos

Darse de alta en el grupo de Telegram para tutorías y actualizaciones de los apuntes.

Adicionalmente, se supone en el estudiante el conocimiento esencial de una ingeniería informática, incluyendo uso de git y Github. Este tutorial puede ayudar con algunos aspectos específicos que se usan aquí.

Explicación

En cuanto al entorno

Primero, hay que configurar correctamente el entorno, lo que incluye

• Descarga de git para usarlo desde línea de órdenes (cómo se descargue no hace falta documentarlo).
• Creación de par de claves y subida de clave pública a GitHub.
• Configuración correcta del nombre y correo electrónico para que aparezca en los commits.
• Edición del perfil de GitHub para que aparezca una imagen en vez del avatar por omisión, nombre completo y ciudad, así como universidad.
• Incrementar la seguridad de nuestra cuenta en GitHub activando el segundo factor de autenticación.

La justificación de lo hecho no forma parte del proyecto en sí, sino que es parte de la documentación. Por tanto, mostrar que se ha hecho esto tendrá que hacerse en el documento aparte que se ha indicado arriba.

Usar un repositorio de forma correcta no sólo permite organizar el trabajo 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, pero no se limitan, a

• Usar o bien el sistema de control de versiones que se incluya en el entorno de desarrollo, y con esto quiero decir, por ejemplo, que si se suele usar Emacs o NetBeans, suelen tener un sistema de control de versiones integrado, o bien la línea de órdenes, lo que se recomienda. No usar nunca el cliente gráfico de GitHub ni, salvo en caso de urgencia (considerándose como tal que tengas que hacer algo urgentemente y no tengas acceso a tu propio ordenador, sino sólo a un navegador y recuerdes tu contraseña de GitHub (no es que estemos recomendando meter contraseñas de nada en ordenadores ajenos (vale, ya paro. Que no lo hagáis y ya está (salvo para hacer los pull request de esta asignatura, donde quizás es más conveniente para crear las ramas sobre la marcha))), editar usando el editor de GitHub.

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

• Hacer commits que abarquen una sola funcionalidad o tarea, pero sólo si la funcionalidad es correcta (no tiene errores sintácticos, por ejemplo). Hacer commits a menudo.

• Hacer commits descriptivos que indiquen en qué han avanzado la tarea, no solamente una referencia a la tarea o "cambios en el fichero tal", siendo tal el fichero que se ha cambiado y que fácilmente se puede ver en el commit.

• Todo commit debe corresponder a una tarea que se haya establecido en el repositorio propio, 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 añadiendo la funcionalidad 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 o instalació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.

• Usar desde el principio un fichero .gitignore para evitar añadir accidentalmente ficheros que no deban estar en el repositorio, como ficheros de respaldo o ficheros generados en compilación o construcción.

• No publicar ficheros binarios en el repositorio, aunque se necesiten en el proyecto. Para ello están los releases. Si son generados por el repositorio, ver la primera regla.

• 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, por eso no se deben copiar simplemente los ficheros, sino forkear los repositorios correspondientes.

• Siempre comprobar, antes de hacer un pull request, que se está trabajando sobre la última copia del fichero para evitar conflictos que imposibiliten que se lleve a cabo la fusión por parte de la persona encargada del mismo.

• Hacer siempre un rebase (con --rebase) cuando se vaya a fusionar el repositorio de la asignatura para evitar merge commits y re-firma de commits. Los commits de cada usuario deben de permanecer igual.

Incumplir alguna de las buenas prácticas anteriores puede conllevar penalización en este hito y en los sucesivos.

En cuanto al problema que se describirá en el README

Será el problema que se resolverá a lo largo del curso, eventualmente desplegándose en la nube. Por lo tanto, debe tener las siguientes características

• Ser un problema con una lógica de negocio aceptable, que vaya más allá de "busca y almacena".
• Un problema cuya resolución esté en gran parte basada en un servidor, puesto que el servidor es lo que se despliega en la nube.
• Un problema que realmente se beneficie de su despliegue en la nube, por los diferentes casos de uso de los datos que se puedan procesar y tratar en la misma.

Reglas generales de entrega de las prácticas

• Lee atentamente la plantilla, borra lo que no corresponda, marca lo que sea necesario, y sólo lo que se aplique en un momento determinado.
• Nunca se abren dos PRs.
• Nunca se cierra un PR.

Entrega de la práctica

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

Cada proyecto tendrá su propio repositorio en GitHub. La documentación se incluirá en ficheros Markdown. Esta descripción de la aplicación irá evolucionando con los diferentes hitos. En cada hito el fichero README.md describirá el estado del proyecto actual, y se sacará a otros ficheros (enlazándolos) la documentación adicional que haya podido necesitarse para la corrección de otros hitos.

Cuando se incluya material adicional externo al proyecto, pero que puede ser útil para complementar la entrega de la práctica, por ejemplo capturas de pantalla de la configuración de git o del par clave pública/privada, se deben seguir las directivas mencionadas anteriormente.

El enlace a esta documentación adicional debe estar bien claro en el fichero principal del proyecto y etiquetado también correctamente.

Valoración

Rúbricas de evaluación:

1. 3 puntos: Repositorio individual creado y entregado correctamente, con todos los ficheros que se solicitan, y el contenido correcto en cada uno de los ficheros. Si se incumplen alguna de las buenas prácticas en la entrega puede haber penalización, aunque no por envíos sucesivos dentro del mismo PR.
2. 3 puntos: Presencia de todos los ficheros de documentación necesarios y entregados correctamente, con la configuración de usuario y repositorio correcta, incluyendo la definición de órdenes de trabajo (issues) (si las hubiera) creadas y cerradas correctamente y la configuración del entorno de trabajo.
3. 4 puntos: Descripción correcta de un problema susceptible de ser desplegado en la nube, que se resuelva mediante la lógica de negocio de nuestra aplicación, siguiendo lo dicho más arriba.

En esta asignatura tenemos tolerancia 0 con el plagiarismo y el "trabajo en común". Cada estudiante tiene que hacer las entregas de forma autónoma, sin "hacerlo en colaboración" o "copiar código que se encuentre uno por ahí". Esto incluye tanto material evaluable como material no evaluable. Se aconseja que no se pida a un compañero/a "qué hay que poner aquí", sino que se lea este documento y se interprete y comprenda de forma autónoma.

Si el repositorio no existe, no se ha rellenado su nick de GitHub en el documento compartido, no tiene la licencia de software libre correcta, tiene algún error, no se ha hecho pull request correctamente o no están los fuentes publicados, la práctica estará suspensa.

Este hito contribuirá 0.5 puntos a la nota final.