Gestion del Codigo Fuente - Giratina-Votacion/decide GitHub Wiki

Nuestro método para la gestión del código fuente se ha realizado en la plataforma GitHub, aplicando una metodología basada en GitFlow

Para el M4, hemos decidido hacer un repositorio propio, sin otros equipos, ya que ninguno estaba en predisposición de integrarse con otros equipos, por lo cual vimos menos complicado tener un repositorio para nosotros mismos, el cual es un fork de EGCETSII/decide.

Siguiendo con la metodología GitFlow, hemos establecido la siguiente jerarquía de ramas:

Ramas del repositorio

• master: La rama por defecto, solo se deben subir cambios a esta rama cuando estén totalmente integrados en develop y se hayan probado correctamente. Una subida a master corresponde a una nueva release del proyecto.

• develop: La rama develop es la rama en la que se unirán todos los diferentes cambios creados por los desarrolladores del equipo. Mediante Pull requests, cada desarrollador indicará que su característica está lista para ser incluida.

• Ramas de desarrollo: Las ramas de desarrollo siguen la siguiente estructura: Usuario-impl, donde Usuario es el nombre del desarrollador e impl la característica nueva que implementa, ya sea una nueva funcionalidad, una rama dedicada a arreglar un error encontrado en el sistema...

Flujo de trabajo en nuestro repositorio

Los pasos a seguir para un desarrollador (llamemos a este usuario Usuario) que quiere implementar una funcionalidad nueva en el sistema (llamemos a esa funcionalidad votación dicotómica) son las siguientes:

1. En caso de que no lo haya hecho ya, realizar un git clone de nuestro repositorio. Si ya se dispone del repositorio en local, basta con hacer un git pull origin mastery git pull origin develop para traer los últimos cambios de esas ramas.
2. Crear una rama nueva para trabajar en la característica que se vaya a implementar, si no se ha hecho con anterioridad (por ejemplo, si ya se trabajó en la incidencia anteriormente pero se quedó estancada en algún punto). En cualquier caso, ejecutar un git checkout para acceder a la rama (Para nuestro ejemplo: git checkout -b Usuario-votacionDicotomica, o git checkout Usuario-votacionDicotomica si la rama ya existía).
3. Integrar los cambios actuales de develop en la nueva rama mediante git merge develop. Si surge algún conflicto, solucionarlo.
4. Implementar los cambios pertinentes utilizando el entorno de desarrollo. Para más información sobre cómo se gestiona el entorno de desarrollo y los cambios locales, ver Entorno de desarrollo
5. Una vez realizados los cambios, añadir los archivos que se quieran subir utilizando el comando git add.
6. Realizar el commit correspondiente a los cambios que se han realizado. Para más información acerca de cómo realizar un commit correcto, por favor, consulte en este mismo documento la sección Commits.
7. Cuando hayamos realizado el commit, es hora de subirlo al repositorio, mediante un git push (Para nuestro ejemplo: git push origin Usuario-votacionDicotomica).

Una vez nuestros cambios estén subidos y comprobados en la rama de desarrollo, es hora de integrarlas dentro de develop. Para esta tarea, usaremos las pull requests:

1. Crear una pull request desde nuestra rama de desarrollo hacia develop. Para ver cómo crear correctamente una pull request, consultar la sección Pull request.
2. Una vez la pull request esté creada, y haya sido aprobada por los revisores de la misma, se podrán mergear los cambios a la rama develop. (Nota: una vez se hayan mergeado los cambios dentro de la rama develop, se puede borrar la rama de desarrollo. En nuestro caso, por si son útiles para la posterior labor de corrección, no vamos a hacerlo, aunque es una práctica recomendable).
3. (OPCIONAL) Si surgen conflictos o errores dentro de la rama developtras hacer una pull request, solucionarlos con la mas alta prioridad. No se debe subir nunca código que provoque conflictos a la rama develop, pero puede ser que por error humano ocurra, aunque la herramienta para realizar pull requests informe de que no hay conflicto.

Commits

Un commit es una utilidad muy importante en un proyecto. No solo permite identificar qué hemos hecho, ofrece una infinidad de opciones. Veamos qué pasos se deben seguir para hacer commits en nuestro repositorio:

Formato de los commits

Los commits deben seguir el siguiente formato:

Nuestro equipo seguirá la siguiente estructura a la hora de realizar un commit:

Título del commit: Es importante que sea claro y conciso, que hable del tema que se está tratando pero sin entrar en demasiado detalle. Además, si el asunto del commit está documentado en una incidencia (normalmente éste será el caso), es importante mencionar dicha incidencia (utilizando #numero_incidencia), y no duplicar información que ya esté escrita en dicha incidencia.

Ejemplos de commits

Título: Commit correspondiente a la incidencia #x, donde x es la tarea que se ha realizado y de la cual ha commiteado y hecho push al repositorio.

Cuerpo: se han realizado los cambios que se describen en la incidencia #x

Título: Implementada funcionalidad de votación dicotómica

Cuerpo: implementados los cambios en los archivos que se describen en la incidencia #x

Debido a la importancia de no duplicar información, a veces bastará con tan sólo mencionar la incidencia en cuestión para que se sepa en qué se está trabajando y qué se ha hecho.

Puede que en algún caso, se hagan commits que no contengan un incremento completo y funcional. Por ello, distinguimos entre los siguientes casos:

• Commit con incremento completo: En este caso, se puede simplemente seguir la estructura mencionada arriba y cerrar la incidencia tras mencionarla, o desde el propio commit (Escribiendo en el mensaje Closes #x).
• Commit sin incremento completo: Si se produce un incremento parcial, pero no se llega a completar lo que se detalla en la incidencia, es importante detallar qué queda por hacer, qué se ha completado y, si procede, el motivo por el que no se ha podido completar la incidencia. En caso de que un miembro del equipo no sepa como seguir con su incidencia y necesite ayuda, se subirán al repositorio todos los cambios realizados y una explicación en la tarea correspondiente para que los demás miembros del equipo de desarrollo sepan que han hecho y puedan ayudar a terminar la incidencia.

Notas sobre los commits

• Nunca se debe subir un commit que mencione más de una incidencia si éstas no están, de alguna forma, conectadas. Es decir, no se debe resolver más de un incremento funcional en el sistema con un único commit, pues eso dificultaría el seguimiento de la incidencia. (Nota: Ejemplo de incidencias íntimamente conectadas: Integración con Travis CI y Despliegue en Heroku)
• No se deben subir cambios directamente a la rama develop, sin hacer un pull request desde la rama de característica.
• En relación con el punto anterior, en caso de que se produzca un error grave en la rama develop que impida el funcionamiento de la misma, ya sea con la integración de Travis o con el servicio desplegado en Heroku, se permitirá hacer commits directamente a develop hasta solucionar la incidencia.

Pull requests

Para subir cambios desde las ramas de desarrollo hacia develop, utilizamos las pull requests.

Introducción a las pull request

Las pull request son una herramienta muy útil que ofrece GitHub, que nos permite comparar los cambios entre diferentes ramas, y crear una solicitud para integrar los cambios de una de las ramas dentro de otra. Para el caso concreto del que estamos hablando, las pull request siempre se harían hacia develop desde la rama de desarrollo, o bien hacia una rama de desarrollo desde otra rama de desarrollo.

Creación de una pull request

A la hora de crear una pull request, a sabiendas de que hay varias herramientas que permiten crear una pull request en GitHub, usamos la propia interfaz web.

Una vez pulsemos el botón de "New Pull Request", accederemos a un menú en el que encontraremos un selector de ramas.

Además del selector mencionado anteriormente, hay varios detalles a tener en cuenta antes de crear una pull request:

• Reviewers: Los reviewers serán los encargados de dar el visto bueno a la pull request en cuestión.
• Asignees: Las personas asignadas a la pull request, normalmente, el creador de la misma y los revisores.
• Labels: En el caso de las pull request, las usaremos para indicar la prioridad (ver "Gestión de incidencias").
• Projects: En este apartado habrá que indicar el proyecto del equipo de desarrollo, para que se incluya dentro del mismo.

En lo referente al código, podemos tener varias opciones dependiendo del código y las ramas que vayamos a unir:

Caso 1: No hay ningún tipo de conflicto en el código.

En este caso, el revisor no tiene que tocar nada de código, simplemente debe revisarlo y dar el visto bueno al mismo, si cree que lo merece.

Caso 2: Conflictos en el código.

Si se producen conflictos, es tarea del revisor arreglarlos, y una vez estén corregidos, aprobar o rechazar la pull request.

En cualquier caso, una pull request se considera aprobada si hay consenso entre los revisores en el aprobado, y rechazada si se ponen de acuerdo en rechazarla. En caso de que se acepte, se puede presionar el botón de "Merge branches", para que los cambios queden reflejados en la otra rama.