Oficina de Software Libre y Conocimiento Abierto

Gestión de proyectos en GitLab.

by · 24 marzo, 2020

Tabla de contenidos

Manual de buenas prácticas en gestión de proyectos en GitLab

Índice

Introducción

    • Tablón de Issues: GitLab también dispone de un tablero, en el cual se puede organizar los Issues, según su categoría y estado.

      Esto permite organizarlos de forma mas gráfica, para ayudar a su resolución.

      Ejemplo: Tablón de Issues de Inkscape

      El objetivo de este manual es aprender algunas buenas prácticas de gestión de proyectos, y explicar cómo aplicarlas sobre GitLab.

      El manual estará especialmente enfocado en proyectos con repositorios públicos, aunque la mayoría de consejos son aplicables a cualquier tipo de proyecto que pueda ser accesible por terceras personas.

      Asumimos que el lector tiene algunos conocimientos previos de Git, y sabe hacer una gestión de versiones básica utilizando esta herramienta

      Conceptos iniciales

      Los repositorios son herramientas de desarrollo distribuido que permiten:

      • Que varios desarrolladores trabajen sobre el mismo proyecto
      • Que el trabajo de un desarrollador no interfiera sobre el resto
      • En caso de error, poder volver a una versión anterior, ya sea en un fichero independiente, o en todo el proyecto.

      También son herramientas de desarrollo continuo:

      • El repositorio debe reflejar, de forma actualizada, el estado de desarrollo del proyecto

        El repositorio podrá ser utilizado por potenciales usuarios, o por otros desarrolladores, para encontrar la última versión del programa, descargarla y, dado el caso, contribuir al proyecto

      Repositorio como herramienta de desarrollo continuo

      El repositorio de un proyecto, es el lugar de referencia donde usuarios y desarrolladores esperan encontrar la última versión del proyecto. Por tanto, el repositorio debe estar actualizado, a fín de que los usuarios puedan encontrar las últimas novedades.

      En software libre, uno de los principales indicativos de que un proyecto ha dejado de mantenerse, es que su repositorio no se ha actualizado en un largo periodo de tiempo.

      Manteniendo tu repositorio actualizado a tiempo real con el desarrollo, animarás a mas usuarios y desarrolladores a probar tu proyecto, mostrando que este se actualiza regularmente, y cuenta con un desarrollo activo. Además, facilitarás que terceras personas puedan contribuir a tu proyecto, al tener la certeza de que el trabajo en el que se basan está actualizado respecto al desarrollo del proyecto.

      Consejos:

      • Haz un commit cada vez que desarrolles algo

        No es necesario que hagas un push inmediatamente de cada commit. Pero sí es recomendable hacer un push cada cierto número de commit, o al terminar la jornada de trabajo.

      • Realiza el desarrollo del proyecto directamente sobre el repositorio:

        La manera mas sencilla de tener tu repositorio actualizado es desarrollar directamente sobre el directorio donde tienes el repositorio. Esto te ayudará a sincronizar el trabajo entre varias máquinas sin tener que recurrir a pendrives ni otras herramientas intermedias.

        Además, si quieres compartir el código con otras personas, podrás compartirlo directamente a través del repositorio. Esa persona podrá ir actualizando su código con los últimos cambios que se vayan subiendo.

      • Documenta los errores que surjan a través de issues: Cuando encuentres algún error, o te quede alguna tarea pendiente de resolver, añade un issue al proyecto indicando el problema y algunos detalles sobre el mismo. Esto ayudará a posibles contribuidores a encontrar tareas con las que ayudar.

      Repositorio como herramienta de desarrollo distribuido

      El repositorio también es una herramienta de desarrollo distribuido, que permite que varias personas trabajen sobre el mismo proyecto.

      Consejo:

      • Añade a tu equipo de desarrollo como miembros del proyecto: esto, sumado a los consejos anteriores, permitirá que el trabajo de todos los miembros del equipo se sincronice correctamente. Cada programador puede saber lo que están haciendo los demás, con lo que se evita trabajar en algo que ya esté trabajando otra persona.

        Además, en caso de que varios programadores trabajen sobre el mismo fichero, al subir los cambios al repositorio, Git detectará el conflicto y ofrecerá ambas versiones para seleccionar los cambios que se quieren mantener, impidiendo la subida hasta que el conflicto se haya resuelto. Esto ayudará a mantener la integridad de los ficheros dentro del proyecto.

      En este repositorio, podemos ver como los commit son enviados por diferentes programadores

      Particularidades de los repositorios públicos

      Los repositorios públicos presentan ciertas particularidades frente al resto de repositorios. Algunas de estas las hemos mencionado en las secciones anteriores.

      • El repositorio es el portal de referencia para los usuarios y desarrolladores interesados en el proyecto

        • La web puede estar desactualizado, el repositorio no debe estarlo. En caso de que la web esté obsoleta, los usuarios acudirán al repositorio, donde esperarán encontrar información mas actual.

      • El contenido del repositorio debe estar enfocado a personas ajenas al proyecto, no a tu propio equipo de desarrollo

        El repositorio debe contener información que permita al usuario entender el proyecto, saber en que consiste, cómo usarlo, y cómo instalarlo.

      En general, cualquier persona interesada en tu proyecto, debe ser capaz de entenderlo y seguir su desarrollo, mirando el repositorio

      En las siguientes secciones, explicaremos varios pasos a seguir para conseguir este objetivo, explicando cada paso, y las ayudas que proporciona GitLab para llevarlos a cabo.

      Volver al inicio

      Añadiendo documentación

      Uno de los principales puntos que se deben seguir para conseguir un repositorio entendible es añadir documentación. La documentación permitirá al usuario entender el proyecto, saber como usarlo, instalarlo… y añadirá mucha información útil para poder seguir su desarrollo.

      Fichero README. Presentando nuestro proyecto

      El fichero README es el primer fichero que se muestra al abrir nuestro repositorio. Este fichero sirve de presentación de nuestro proyecto, y debe contener la información necesaria para que el usuario pueda entender el proyecto y utilizarlo.

      El README debería explicar:

      • ¿en qué consiste nuestro proyecto? ¿para qué sirve?: Explicamos una breve introducción a nuestro proyecto, su objetivo y sus funcionalidades.

      • ¿cómo funciona?: Explicamos el funcionamiento de la aplicación, con algunos ejemplos de uso, para que el usuario sepa utilizarlo

      • **¿que requisitos tiene?: ** En esta sección debemos indicar los requisitos que tiene nuestra proyecto para poder funcionar: sistema operativo, librerías, entorno de ejecución… etc

      • ¿cómo instalarlo?: Aquí debemos indicar los pasos que se han de seguir para instalar el programa. Estos pasos deben ser lo mas sencillos posible, y no obviar ningún punto de la instalación, incluyendo posibles dependencias del proyecto, configuraciones, etc

      Otras secciones que podemos añadir son:

      • Contribuidores: indicamos los nombres de aquellas personas que han contribuido con el proyecto, y la contribución que han hecho al mismo. Esto servirá de agradecimiento para reconocer el trabajo de dichas personas, dando visibilidad al mismo.

      • Implementación: Algunos detalles sobre cómo está construida la aplicación, a nivel de código y arquitectura

      …

      Para entender la documentación del fichero README, pongamos un ejemplo:

      “Queremos desarrollar una aplicación que muestra la palabra correspondiente a una definición. El usuario puede escribir la definición de una palabra que no sepa, y la aplicación le mostrará posibles palabras que puedan corresponder a dicha definición“

      • ¿en que consiste el proyecto?

        El proyecto trata de ayudar en aquellas situaciones en las que no encontramos las palabras para una descripción o definición concreta.

      • ¿cómo funciona?

        La aplicación cuenta con una interfaz gráfica de escritorio, con un formulario en el que el usuario introduce la definición a consultar. La aplicación se conectará a un servidor, a través del cual se buscará las palabras mas acordes a dicha definición, que se mostrarán en la parte inferior del formulario

        Incluir capturas de dicha aplicación, mostrando su interfaz y ejemplos de uso

      • Requisitos

        La interfaz gráfica está desarrollada en Qt sobre Python, usando PySide2 sobre Python 3. Dado que la aplicación hace consultas a un servidor, se requiere conexión a internet.

        • Python 3.5 o superior
          • PySide2
          • requests
        • Conexión a Internet

      • Cómo instalarlo

        Para instalarlo, podéis descargar la última Release desde nuestro repositorio. Previamente debéis instalar Python 3 y ejecutar el script requeriments.txt para instalar las dependencias

        Una vez instaladas las dependencias, podéis instalar la aplicación usando el script installer.py

      Como vemos, el contenido del README está enfocado en el usuario, centrándose en el uso de la aplicación, por encima de los detalles técnicos. El objetivo es que el usuario, leyendo el README, se anime a probar nuestra herramienta, siendo capaz de instalarla y usarla de la forma mas sencilla posible.

      Podemos ver un ejemplo de un README real aquí:

      Creación de un README en GitLab

      Durante la creación de un proyecto, GitLab nos da la posibilidad de crear un README en el repositorio.

      Esto nos creará un fichero README, únicamente con el nombre del proyecto, que podremos ir rellenando para añadir el resto de información.

      Podemos ver como el README se muestra por defecto al abrir el repositorio.

      Si, en cambio, hemos creado un repositorio vacío. aún podemos crear nuestro README pulsando en el botón “Add README”

      Esto nos abrirá el editor con un fichero en blanco, para que lo rellenemos de la forma conveniente.

      Una vez relleno, pulsamos en el botón “Commit changes” para añadir el nuevo fichero al repositorio

      Vemos como el README se muestra por defecto al abrir el repositorio.

      Otros ficheros

      Otros ficheros interesantes para documentar el proyecto son los siguientes:

      • LICENSE: Almacena el texto completo de la licencia que hemos elegido para nuestro proyecto
      • CHANGELOG: Fichero que almacena los cambios realizados entre versiones
      • CONTRIBUTING: Fichero que da indicaciones sobre cómo contribuir al proyecto. En ocasiones, también almacena la lista de contribuidores del proyecto.

      GitLab también trae opciones para generar estos ficheros.

      Ejemplo de CHANGELOG:

      Ejemplo de CONTRIBUTING:

      Generar fichero LICENSE en GitLab

      Para añadir un fichero LICENSE, pulsamos el botón “Add license” (bajo el nombre del proyecto)

      Esto nos abrirá el editor, que nos permitirá crear el nuevo fichero.
      GitLab incluye una serie de plantillas predefinidas de algunas licencias conocidas. Podemos seleccionarlas desplegando el menú de “Select a template type”, seleccionando LICENSE, y seleccionando nuestra licencia de la lista de “Apply a LICENSE”

      Tras seleccionar la licencia, GitLab nos rellenará el texto con el contenido de dicha licencia. Hecho esto, podemos guardar el fichero pulsando en “Commit changes”

      Tras añadir el fichero de licencia, GitLab reconocerá el contenido y nos mostrará el tipo de licencia en la página principal del proyecto

      Generar ficheros CONTRIBUTING y CHANGELOG en GitLab

      GitLab también nos permite crear estos dos ficheros, pulsando en sus respectivos botones en la página principal del proyecto.

      Estos ficheros, al igual que con el README, no disponen de plantilla predefinida; sino que GitLab simplemente nos abrirá el editor con el texto en blanco para que lo rellenemos nosotros.

      Formatos de texto

      Los repositorios usan un sistema de control de versiones, Git, basado en ficheros de texto plano. Aunque Git admite la subida de ficheros binarios (doc, odt, pdf, ejecutables…), éste no es capaz de obtener las diferencias entre las versiones de estos ficheros.

      Por lo tanto, lo ideal es que toda la documentación se añada, siempre que sea posible, en ficheros de texto plano.

      Para añadir formato a estos ficheros, se recomienda usar lenguajes de etiquetas, como Markdown o LaTeX.

      GitLab, al igual que GitHub y otros portales similares, incluye de forma nativa un intérprete de Markdown, un lenguaje de etiquetas con una sintaxis bastante sencilla, y que permite generar ficheros HTML. En GitLab, al abrir un fichero con este formato, el fichero se renderiza automáticamente desde la web, permitiendo visualizarlo directamente desde cualquier navegador. Por lo tanto, este es el formato mas recomendable a la hora de escribir documentación dentro de un repositorio

      Ejemplo: README escrito en Markdown

      El visualizador de GitLab también permite ver el contenido sin renderizar, lo cual nos permite ver las etiquetas que componen el documento

      Ejemplo: Mismo README sin renderizar

      En algunos ficheros, cómo el LICENSE, el texto suele ir en un fichero de texto plano sin formatear.

      Ejemplo: Fichero LICENSE (texto plano sin formato)

      Edición de ficheros en GitLab

      GitLab incluye un Web IDE que nos permite editar todo tipo de ficheros de código. En el caso de la documentación, el IDE nos resultará muy útil para editar ficheros en Markdown, resaltando las etiquetas y permitiendo previsualizarlo.

      Ejemplo: Edición de fichero README en Markdown con el WebIDE

      Podemos observar cómo el IDE marca el nivel de indentación al editar una sección

      También nos permite previsualizar el resultado, sin necesidad de tener que actualizar el fichero.

      Ejemplo: Previsualización del README anterior en el WebIDE

      Esto nos facilitará muchísimo la redacción de este tipo de ficheros

      Volver al inicio

      Sincronizando nuestro proyecto

      Una vez completada la documentación, pasamos al tema principal de nuestro proyecto: el proyecto, nuestro programa a desarrollar

      Para sincronizar el proyecto con el repositorio, y facilitar la contribución de terceras personas, se recomiendan seguir ciertas pautas.

      Debemos pensar que. en un repositorio público, nuestro proyecto puede ser visto por terceras personas, que puedan tener interés en probar y contribuir a nuestro proyecto. Por tanto, es necesario facilitar la descarga del repositorio, y la compilación e instalación de nuestro programa.

      Subiendo ficheros

      Cómo dijimos anteriormente, Git solo permite el seguimiento de ficheros de texto plano. Por tanto, es recomendable evitar la subida de ficheros binarios de todo tipo.

      Recomendaciones:

      • Subir el código fuente (obvio): Al subir el código fuente, si éste se compone de muchos ficheros, es recomendable organizarlo en directorios, según la tarea que realiza cada uno

      • Ficheros de compilación: Es recomendable el uso de ficheros tipo Makefile, cmake y similares, a fín de facilitar la compilación del código por terceras personas. Estas ficheros usan herramientas genéricas, que ocupan poco espacio, y están disponibles para la mayoría de sistemas operativos. Además, permiten compilar el proyecto sin necesidad de recurrir a un IDE completo.

      • Documentación en texto plano: Cómo dijimos anteriormente, el uso de documentación en texto plano permite visualizar el documento directamente desde el navegador, además de aprovechar al máximo la gestión de versiones mediante Git.

      No recomendable:

      • Ejecutables del proyecto: Suman peso al repositorio, además de que un nuevo commit los volverá obsoletos. Git no es capaz de rastrearlos. Para subir el instalador (si no es de texto) y las versiones compiladas, es recomendable realizar una RELEASE

      • Ficheros del IDE: Atan al desarrollador a utilizar un IDE concreto, lo cual puede suponer muchas limitaciones: el desarrollador original puede estar utilizando un IDE de pago, o que sólamente existe para un sistema operativo concreto… lo cual complicaría la compilación del código a otros desarrolladores que no dispongan de los recursos necesarios para usar ese IDE. Es preferible usar ficheros tipo Makefile o CMake, tal y como dijimos anteriormente.

      Ejemplo de buenas prácticas: Sólo ficheros de texto: código fuente, Makefile y README en Markdown. No hay ficheros del IDE ni ejecutables

      Ejemplo de malas prácticas: No hay README, ni Makefile. Están los ficheros del IDE y ejecutable dentro del repositorio

      Volver al inicio

      Desarrollando nuestro proyecto en ramas

      Al desarrollar nuestro proyecto, es posible que haya ocasiones en las que tengamos que subir versiones sin terminar, o sin probar, al repositorio.

      Los usuarios y desarrolladores que clonen nuestro repositorio esperan encontrar versiones estables, por lo cual esas versiones incompletas o sin probar les pueden suponer muchos problemas. Sin embargo, sigue siendo recomendable subir al repositorio los cambios que vayamos haciendo.

      Para resolver esto, un recurso muy sencillo es el uso de ramas de desarrollo. Las ramas de desarrollo permiten bifurcar el desarrollo principal en varios flujos secundarios. Estas ramas permiten separar el trabajo de las versiones en desarrollo, de las versiones ya estables. Además de poder realizar ciertos desarrollos “experimentales”, o de tareas concretas, sin tener que tocar la versión principal.

      De esta forma, el usuario puede descargar los cambios de la versión principal, ubicada en la rama estable del repositorio, con seguridad de que esa versión funcione sin aparentes problemas.

      Flujo de trabajo en ramas

      El flujo de trabajo con el uso de ramas sería el siguiente:

      • Rama master: rama principal, donde se suben las versiones estables y probadas
      • Rama (o ramas) de desarrollo: ramas donde se realiza el trabajo de desarrollo

      El desarrollo se realiza en estas ramas secundarias y, una vez terminado y probado, se vuelcan a master. Una vez volcada la nueva estable en la rama master, se vuelve a la rama de desarrollo para continuar el trabajo

      No es estrictamente necesario que la rama master sólo incluya versiones completas. Se pueden ir subiendo los cambios de la versión en desarrollo que ya se han completado y probado. De esta forma, el usuario podrá ir probando las nuevas funcionalidades y cambios de la próxima versión en desarrollo, sin tener que esperar a que se publique dicha versión de forma oficial.

      Estructura en ramas

      Una estructura básica podría ser:

      • Rama master: rama principal, que se muestra por defecto al abrir el proyecto. Contiene las versiones estables ya probadas

      • Rama development: rama de desarrollo, donde se realiza el trabajo de desarrollo

      También podemos tener varias ramas secundarias:

      • nightly, weekly, monthly: ramas donde se sube el trabajo realizado cada ciertas franjas de tiempo (dias, semanas y meses)
      • alfa, beta, stable: ramas donde se van subiendo las siguientes versiones en diferentes fases del desarrollo.

      Con este modelo, el usuario interesado simplemente tiene que descargar la rama master, para tener los cambios de la última versión estable.

      Modelo avanzado de ramas

      También podemos crear ramas para el desarrollo de diferentes funcionalidades, y la solución de determinadas tareas (normalmente asociadas a issues).

      Un modelo avanzado de ramas, incluyendo estos casos, y usado en muchas empresas, sería este:

      Podemos ver como el trabajo principal se realiza en la rama de desarrollo, de la cual a su vez cuelgan varias ramas, respondiendo a cada nueva funcionalidad en desarrollo.

      Al terminar cada versión, antes de subir los cambios a la rama master, se genera una nueva rama correspondiente a dicha versión.

      En caso de encontrar algún error en la versión en producción (ya subida a master), se genera una nueva rama para corrección de errores, y se incorpora a la rama de desarrollo para generar una nueva release, antes de pasar la versión ya corregida a master.

      Gestión de ramas en GitLab

      GitLab tiene múltiples herramientas para gestionar ramas de desarrollo.

      Visualizando las ramas de un repositorio

      Al entrar a un repositorio, podemos cambiar de rama pulsando en el menú desplegable situado en la parte superior

      Ejemplo: lista de ramas de Inkscape

      También podemos ver el listado completo de ramas pulsando en el número de ramas, en la descripción del proyecto; o en la barra lateral, en Repository -> Branches

      Esto nos llevará a un buscador mediante el cual podemos filtrar ramas concretas del listado de ramas. También podemos filtrar según su estado: active, stale. O buscar entre todas las ramas

      Ejemplo: listado de ramas activas de Inkscape

      Vemos como este proyecto incluye múltiples ramas para desarrollar funcionalidades y tareas concretas, además de tener algunas ramas para corrección de errores. También podemos ver como algunas de las ramas están protegidas, limitando los miembros que pueden subir cambios a ellas.

      Creando nuevas ramas desde GitLab

      Para crear una rama desde GitLab, simplemente tenemos que pulsar en el botón “+” en la página principal del proyecto. Esto nos abrirá un desplegable con varias opciones, en el cual pulsamos en “New branch”

      Esto nos llevará a una página donde nos pedirá el nombre de la rama, y la rama desde la que bifurca.

      En nuestro caso, vamos a crear una rama llamada “wip”, que bifurcará de la rama master

      Rellenamos el formulario, y pulsamos en “Create branch” para crear la nueva rama.

      Cambiando de rama desde GitLab

      Para cambiar de rama en GitLab, simplemente seleccionamos la nueva rama en el menú desplegable, en la página principal del proyecto.

      Esto nos llevará a la nueva rama, mostrando los cambios que haya en la misma

      En este caso, hemos añadido un fichero nuevo a esta rama

      Cambiando la rama por defecto de nuestro proyecto

      Por defecto, GitLab asume que la rama principal es master, y esa es la que se abre por defecto al descargar nuestro repositorio, o abrirlo desde la web.

      En algunas ocasiones, nos puede interesar que la rama por defecto sea otra. Esto se puede cambiar en GitLab, desde las opciones de configuración de nuestro repositorio, en Settings -> Repository -> Default branch

      En el menú desplegable, seleccionamos la rama que queremos mostrar por defecto, y pulsamos en el botón “Save changes” para aplicar los cambios

      Tras cambiar esto, vemos que, al abrir la página principal del proyecto, la rama que se muestra por defecto es la “wip”, en vez de master

      Borrando una rama

      En la barra lateral, pulsando en Settings -> Repository -> Branches , podemos acceder al listado de ramas de nuestro proyecto.

      En este listado, podemos borrar una rama pulsando en el botón rojo de la fila correspondiente a dicha rama.

      GitLab también ofrece algunas opciones mas, como la de borrar aquellas ramas cuyos cambios ya hayan sido fusionados en la rama principal, crear una nueva rama, o realizar un “Merge Request” de una rama a otra.

      Gestión de ramas desde Git

      Para poder trabajar con la nueva rama desde nuestro ordenador, debemos sincronizar sus cambios en nuestro repositorio Git. También tendremos que cambiar algunos pasos de nuestro flujo de trabajo, para poder cambiar entre ramas, y subir los cambios realizados a la rama correcta.

      • Descargando la nueva rama en nuestro repositorio

        Para sincronizar la nueva rama en el repositorio Git de nuestro ordenador, podemos usar el comando git pull, con la siguiente sintaxis:

        git pull origin [rama]

        Esto descargará la rama y sus contenidos en el directorio de nuestro repositorio

      • Cambiando a la nueva rama

        Para trabajar sobre la nueva rama, podemos cambiar la rama de trabajo usando el comando git checkout, con esta sintaxis:

        git checkout [rama]

        En nuestro caso, dado que nuestra rama se llama “wip”, el comando será:

        git checkout wip

        Con esto, los commit que hagamos en nuestro directorio, se aplicarán en la nueva rama, en lugar de aplicarse sobre la rama por defecto.

      • Subiendo los cambios al servidor en la nueva rama

        Para subir los cambios a esta nueva rama, simplemente indicamos el nombre de la rama en el comando git push

        git push origin [rama]

        En nuestro caso, con la rama “wip”:

        git push origin wip

      • Saber nuestra rama actual

        Podemos saber en que rama estamos actualmente, usando el comando git branch

        Esto nos mostrará las ramas que tenemos descargadas en nuestro repositorio, y nos marcará con un * la rama en la que estamos situados actualmente.

      Creando una nueva rama desde Git

      Si lo preferimos, también podemos crear una nueva rama directamente desde Git. Para ello, recurrimos al comando git checkout con esta sintaxis:

      git checkout -b [rama]

      Esto nos creará una nueva rama en nuestro repositorio local (nuestro directorio de trabajo).

      Esta rama bifurcará de nuestra rama por defecto. En nuestro caso, al haber cambiado la rama principal a “wip”, la bifurcación se realizará a partir de esa.

      Para subir la nueva rama al servidor, simplemente hacemos un git push indicando como destino dicha rama

      git push origin [rama]

      Tras esto, al consultar el listado de ramas desde GitLab, vemos que aparece la nueva rama que hemos creado desde Git

      Volver al inicio

      Publicando versiones

      Con los pasos anteriores, ya tenemos un entorno de trabajo preparado para trabajar de forma cómoda y segura, a su vez que los usuarios interesados por nuestro proyecto pueden entender nuestro proyecto, y descargar los últimos cambios estables realizados sobre el mismo.

      Pero la descarga del proyecto aún puede ser complicada: hay que descargar el repositorio y, si queremos utilizar el programa, compilarlo. Además de tener dificultades para saber que versión estamos utilizando.

      Para solucionar esto, podemos publicar versiones haciendo uso de RELEASES. Esto nos aportará varias ventajas:

      • Permiten subir ejecutables e instaladores (o, en general, cualquier tipo de fichero): De esta manera, evitaremos el tener que subir ficheros binarios al repositorio

      • Facilitan a los usuarios el acceso a las diferentes versiones del proyecto: En lugar de tener que recurrir a las ramas del repositorio, pueden descargarlas mas facilmente desde el apartado de RELEASES del proyecto. Además, permite acceder mucho mas facilmente a versiones anteriores, sin tener que recurrir al historial o a las ramas del repositorio.

      • Facilitan el seguimiento del desarrollo: Es mucho mas fácil reportar un error de la versión 0.6, que “del commit del 15 de Mayo a media tarde” 😉

      Ejemplo: RELEASES de Pendrive Reminder:

      Creando una nueva RELEASE en GitLab

      En GitLab, las RELEASE son tags (etiquetas) asociadas a una versión del código, en la que se añade un mensaje con (opcionalmente) algunos ficheros adjuntos.

      La RELEASE tomará el último contenido de la rama que se le indique, y lo empaquetará, añadiendo el mensaje con los ficheros adjuntos que se le hayan incluido.

      Para crear una nueva RELEASE, nos vamos a la página principal de nuestro proyecto, y pulsamos en el botón “+”

      En el desplegable, seleccionamos “New tag”. Esto nos abrirá una página, con un formulario donde pondremos los datos de la versión a publicar. Debemos indicar el nombre de la etiqueta (el número de versión), la rama desde la cual se generará, y un mensaje.

      Es importante rellenar el campo “Release notes”, que es el que se tomará para generar la RELEASE. En él añadiremos unas notas sobre la Release, y adjuntaremos los ficheros (ejecutables, instaladores…) asociados a la misma. En caso de no rellenar este campo, únicamente se creará la etiqueta (tag), pero no aparecerá como RELEASE

      Rellenamos los campos, y pulsamos el botón “Create tag” para crear la RELEASE

      Visualizando las RELEASE del proyecto

      Para visualizar las Releases de un proyecto, tenemos que ir a la barra lateral, a la sección Project -> Releases.

      Esto nos mostrará las últimas versiones del proyecto, con su documentación y los archivos adjuntos (instalador, ejecutable…) que se hayan añadido a la misma.

      En nuestro caso, vemos que nuestro proyecto sólo tiene una RELEASE y, dado que no hemos adjuntado ningún otro fichero, ésta sólo contiene el código fuente.

      Volver al inicio

      Publicando reportes: Issues

      Con los pasos anteriores, ya el usuario puede entender el proyecto, descargarlo, e instalarlo. Pero, al usar o desarrollar el proyecto, es posible que surjan algunos problemas: errores que solucionar, tareas pendientes… etc

      Para notificar estos cambios, es recomendable publicar reportes, avisando que hay algún problema o tarea pendiente que resolver.

      Para publicar estos reportes, podemos usar Issues. Estos Issues son mensajes que colgarán de nuestro repositorio, y que albergarán un mensaje con el problema a resolver. Los Issues por defecto son públicos, de tal forma que, cualquier persona que entre a nuestro repositorio puede verlos, y participar en ellos.

      Además, los issues incluyen las siguientes características:

      • Pueden ser asignados a desarrolladores: Estos desarrolladores pueden ser miembros del proyecto, o ser ajenos al mismo. Pueden ser asignados a uno o varios desarrolladores. Estos desarrolladores serán los responsables de resolver dicha tarea.
      • Permiten conversación: Los miembros del proyecto, u otros usuarios, pueden responder al issue para encontrar una solución al problema, o dar mas información sobre el mismo.

      Una vez resuelta la tarea o problema, el issue debería cerrarse, para indicar que esa tarea se ha completado.

      Gestión de Issues en GitLab

      Visualizando los Issues de un proyecto

      Para visualizar los issues de un proyecto, tenemos que pulsar en la barra lateral del proyecto, en “Issues”. Esto nos abrirá la lista de Issues, donde podremos ver los Issues abiertos, cerrados, y todos, y tendremos un buscador donde poder hacer una busqueda por nombre, filtrando por algunos parámetros

      Ejemplo: Lista de Issues de Inkscape

      Podemos ver como los issues tienen etiquetas, idénticas a las de los MR, añadiendo clasificaciones según el tema a tratar y su importancia.

    Leyendo un Issue

    Pulsando en uno de los Issues, podemos leer su contenido y participar en el mismo

    Vemos como el Issue contiene una explicación del problema, pasos para reproducirlo, y datos adicionales como versión, sistema operativo… etc. En la parte inferior, observamos que el Issue se ha asociado a otro similar.

    Revisando la barra lateral, vemos las etiquetas del Issue y que, en este caso, no tiene ningún desarrollador asignado al mismo.

    • Discusión sobre un Issue

      Los issues también admiten respuestas, tanto de desarrolladores miembros del proyecto, como de personas ajenas al mismo.

      Podemos ver dicha conversación en la parte inferior del Issue, en la pestaña “Discusion”

      Si queremos participar en la discusión, podemos responder a un mensaje, pulsando el botón de “reply”, en la esquina superior derecha del mensaje.

      O podemos poner un mensaje nuevo, escribiendo el mensaje en el cuadro de texto al final de la conversación

    Añadiendo nuevos Issues

    Para añadir un nuevo Issue, nos vamos a Issues->List y pulsamos en “New issue”

    Esto nos abrirá un formulario, donde podremos rellenar los datos del Issue. Rellenamos el título y la descripción.

    • Si el Issue lo estamos creando en nuestro propio proyecto, también se nos permitirá añadir unas etiquetas y asignar el Issue a un miembro del equipo.

    • Si el Issue lo estamos creando en un proyecto ajeno, únicamente podremos rellenar el título y la descripción

    Rellenamos el formulario, y pulsamos en “Submit issue” para publicar el issue.

    Permitiendo el envío de Issues a personas ajenas a nuestro proyecto

    En algunos casos, es posible que el envío de Issues esté restringido a los miembros de nuestro proyecto. Esto impediría que personas ajenas al mismo puedan enviar dichos issues.

    Para resolver esto, nos vamos a la configuración de nuestro proyecto, pulsando Settings -> General en la barra lateral.

    En la sección “Visibility, project features, permissions”, configuramos los Issues en modo “Everyone With Access”

    Pulsamos en “Save Changes” para guardar los cambios.

    Con este cambio, ya permitimos que otras personas puedan contribuir a nuestro proyecto, creando issues y participando en ellos

    Revisando los Issues de nuestro proyecto

    Si queremos revisar los issues que han enviado a nuestro proyecto, podemos entrar a Issues -> List en la barra lateral (igual que con cualquier otro proyecto, sea nuestro o no).

    En el listado, pulsamos en el Issue que nos interesa para revisarlo.

    • Gestionando un issue: Al revisar el issue, GitLab nos da algunas opciones para poder gestionarlo.

      En el lado derecho, veremos una barra en la que podemos realizar algunas acciones sobre dicho Issue, como asignarlo a un desarrollador.

      Podemos asignar el Issue a un miembro del proyecto, o a la misma persona que lo ha enviado. También podemos añadir etiquetas, o ponerle una fecha

    • Editando un Issue: Al igual que con los Merge Request, los Issues también se pueden editar. Para ello, pulsamos en el icono de edición que está a la derecha del título

      Podemos editar el título y la descripción del issue. **También podemos borrar el Issue, pulsando el botón “Delete”

      Una vez editado el issue, si no lo hemos borrado, pulsamos en “Save changes” para guardar los cambios.

    • Cerrando un issue: Una vez resuelto el problema, podemos cerrar el issue.
      Para ello, podemos pulsar en “Close Issue” , en la parte superior de la página.

      También podemos añadir un mensaje antes de cerrar el issue.

      Para ello, nos vamos a la sección “Write”, al fondo del Issue, escribimos un mensaje, y pulsamos en “Comment & close issue”

      Esto marcará el issue como cerrado, indicando que el problema se ha resuelto. Aunque aún será posible responder al mismo.

    • Reabriendo un issue:

      En algunas ocasiones, puede ocurrir que el problema referente al issue que hemos cerrado vuelva a aparecer, bien porque no se ha resuelto correctamente, bien por otra razón.

      En estos casos, podemos reabrir el issue, marcandolo de nuevo como abierto.

      Para ello, simplemente entramos en el issue, y pulsamos en “Reopen issue”

      Esto marcará el issue como abierto, indicando que la tarea aún no se ha resuelto.

    Volver al inicio

    Realizando contribuciones: Merge Request

    Los Merge Request (equivalente a los Pull Request de GitHub), permiten recibir contribuciones de personas ajenas al proyecto. También se pueden utilizar para mezclar contenido de diferentes ramas, previa aprobación.

    Hay que tener en cuenta que, aunque el repositorio sea público, los cambios solamente pueden ser realizados por los miembros del proyecto que tengan permisos para ellos.

    Para que un desarrollador ajena al proyecto pueda hacer contribuciones al mismo, es necesario realizar un Merge Request, de la siguiente manera:

    El procedimiento a seguir para generar un Merge Request es el siguiente:

    1. El contribuidor realiza un fork del repositorio: Este fork será una copia idéntica del repositorio original, pero bajo la propiedad de la persona que realiza el fork. Esto permitirá al contribuidor realizar los cambios sobre los ficheros pertinentes, sin restricción de permisos.

    2. El contribuidor envía un Merge Request al proyecto original: Una vez terminados los cambios en los ficheros, el contribuidor genera un Merge Request, que contendrá los cambios realizados en el proyecto, ofreciendo su incorporación en el proyecto original.

      El Merge Request incluirá los cambios realizados a los ficheros del proyecto, mostrando las diferencias entre éste y el proyecto actual, permitiendo revisar dichos cambios, y aceptar o rechazar los mismos.

    3. El administrador del proyecto original recibe el Merge Request: El administrador revisa los cambios realizados en dicho Merge Request y, si le gustan y parecen apropiados, pasará a aprobarlo. En caso de no estar de acuerdo, el Merge Request será rechazado.

      Para facilitar esto, también es posible incorporar sistemas de testeo automático al repositorio, de tal forma que, al recibir el Merge Request, el propio proyecto realizará los tests correspondientes, y rechazará aquellos MR que no pasen los mismos.

    Esta es una manera muy sencilla, y bastante popular, de contribuir a un proyecto de software libre

    Gestión de Merge Request en GitLab

    Visualizando los Merge Request de un proyecto

    Para ver los Merge Request enviados a un proyecto, podemos entrar en la sección Merge Request, en la barra lateral del proyecto.

    Esto nos mostrará un listado con los MR realizados a este proyecto, con un buscador, y permitiendo visualizar los abiertos, cerrados, aplicados y la lista completa.

    Ejemplo: listado de Merge Request de Inkscape

    Pulsando en uno de los Merge Request, podemos ver información sobre el mismo.

    El “Overview” nos mostrará un resumen del MR y la discusión en torno al mismo.

    Ejemplo: discusión de un Merge Request enviado a Inkscape:

    Podemos ver como el MR ha sido revisado por una pipeline, que ha comprobado que el MR pasa todos los tests pertinentes.

    Pulsando en “Changes” podemos ver los cambios a los ficheros realizados en dicho MR

    Ejemplo: contenido de un Merge Request enviado a Inkscape

    Podemos ver como se resaltan las líneas modificadas dentro del fichero. También se nos permite comparar los cambios entre diferentes ramas y versiones, tanto del MR como del proyecto original,

    Creando un nuevo Merge Request

    • Creando un fork del proyecto: El primer paso para poder crear el Merge Request es realizar un fork del proyecto. Esto nos creará una copia del proyecto, bajo nuestra propiedad, en la que podremos editar los ficheros que nos interesen.

      Para crear un fork, nos vamos a la página principal del proyecto, y pulsamos en el botón “fork”.

      GitLab nos mostrará una nueva página, preguntando en que “namespace” queremos clonar el proyecto.
      El “namespace” hace referencia a cualquier espacio desde el cual se pueda “colgar” un proyecto: usuario, grupo. subgrupo… etc

      En nuestro caso, colgaremos el fork del namespace de nuestro usuario.

      Esto nos creará un fork del proyecto en nuestro espacio de usuario.

      Vemos que el propietario del proyecto ha cambiado, y que el proyecto muestra una anotación indicando que es un fork de otro proyecto.

    • Editando ficheros: Una vez realizado el fork, editamos los ficheros que nos interesan. También podemos añadir ficheros nuevos.

      En nuestro caso, vamos a editar el README y añadir un CHANGELOG

      Vemos los dos nuevos ficheros añadidos al repositorio

    • Enviando el Merge Request: Para enviar el Merge Request, pulsamos en “Merge Requests”, en la barra lateral del proyecto.

      Esto nos abrirá una nueva página, donde se nos ofrecerá crear un nuevo Merge Request

      Pulsamos en “New Merge Request”. Se nos abrirá una nueva página, consultando la rama que queremos fusionar, y el proyecto al que queremos enviar el MR.

      Pulsamos en “Compare branches and continue”

      Esto nos abrirá un formulario con los datos a rellenar para enviar el MR.

      Pulsamos el botón “Submit merge request” para enviar el MR

      El MR enviado aparecerá en el listado del proyecto original

      Vemos que el MR ha pasado los tests automáticos, y aparece como listo para mergear.

    Permitiendo Merge Request de contribuidores externos a nuestro proyecto

    En algunos casos, el proyecto puede tener bloqueada la recepción de Merge Request por usuarios ajenos al proyecto. Esto puede impedir a otros usuarios hacer contribuciones a nuestro proyecto.

    Para resolver esto, tenemos que irnos a los ajustes de nuestro proyecto, en la barra lateral, en Settings -> General

    En la sección “Visibility, project features, permissions”, buscamos la sección “Merge requests”

    En nuestro caso, vemos que las Merge Request están en modo “Only Project Members”, restringiendo su envío a los miembros del proyecto.

    Para permitir que cualquiera pueda envíar Merge Request, cambiamos esa opción a “Everyone With Access”.

    Con esto, ya permitimos que cualquiera pueda enviar MR a nuestro proyecto

    Revisando un Merge Request

    Con los pasos anteriores, al administrador del proyecto le llegará un nuevo Merge Request que podrá revisar, y aceptar o rechazar.

    Para revisar los Merge Request de nuestro proyecto, nos vamos a la sección “Merge Request” de nuestro proyecto, en la barra lateral, que nos mostrará el listado de MR recibidos.

    En este caso, vemos el Merge Request que hemos enviado des´de nuestro otro usuario. Pulsamos sobre él para revisarlo.

    Nos vamos a la pestaña “Changes” (junto a la discusión), para ver los cambios realizados

    • Aceptando el MR

      Para aceptar el MR, desplegamos el botón “Mere when pipeline succeeds”

      Aquí tenemos dos opciones, “Merge when pipeline succeeds” (la opción por defecto, que pasa los tests antes de aplicarlo, y sólo aplica el MR si los tests son correctos) o “Merge immediately”, que aplica el MR inmediatamente, sin realizar ningún test.

      En nuestro caso, usaremos la segunda opción.

      Esto aplicará los cambios del MR directamente sobre nuestro repositorio. En nuestro caso, sobre la rama master.

      Vemos como los cambios realizados en el fork se han integrado correctamente en el proyecto original

    • Revirtiendo el MR: Si no estamos contentos con el resultado del MR, podemos revertirlo. Para ello tenemos que volver a la página del MR, y pulsar en Revert

      En el listado de Merge Request, nos vamos a la sección “Merged” y buscamos el que queremos deshacer.

      Lo abrimos, y pulsamos en el botón “Revert”

      Nos preguntará en que rama queremos revertir. En nuestro caso, indicamos que en “master”

      Pulsamos en “Revert”

      Esto nos creará un nuevo MR para revertir el anterior.

      Pulsamos en “Submit merge request” para completar la acción

      Esto nos llevará al nuevo MR revirtiendo el anterior. Pulsamos en “Merge” para aplicar los cambios

      Vemos como los archivos de nuestro proyecto han vuelto a su estado original

    • Aplicando el Merge Request sobre una rama diferente: En algunos casos, nos puede interesar aceptar el Merge Request, pero aplicándolo sobre una rama diferente a la propuesta.

      Para conseguir esto, podemos editar el MR, cambiando la rama destino a otra diferente.

      Entramos en el Merge Request, y pulsamos en “Edit”

      Esto nos mostrará las propiedades del MR, con varias opciones para editar su contenido.

      Para cambiar la rama destino, nos vamos a “Target branch”, y seleccionamos la rama que nos interese

      Pulsamos en “Save changes” para aplicar los cambios

      Esto modificará el MR para proponer los cambios sobre otra rama diferente

    • Editando el Merge Request: En la misma página de edición del MR, podemos realizar mas cambios sobre el mismo:

      • Editar el título y mensaje del MR: Para añadir un mensaje mas descriptivo, o cambiar el mensaje original del contribuidor

      • Asignar el MR a un usuario: Esto asignará la revisión del MR a un miembro específico del proyecto

      • Añadir etiquetas: Esto añadirá etiquetas para facilitar la búsqueda posterior del MR, y aportar información sobre su propósito. En caso de no existir esa etiqueta, podremos crearla

      Rellenamos los campos que nos interese editar, y pulsamos en “Save changes” para aplicar los cambios

      El resumen del MR ahora mostrará los cambios que hemos hecho sobre el mismo

    Tras aplicar el MR, vemos que los cambios se han realizado sobre la rama “test”, en vez de la rama “master” indicada por defecto

    También podemos ver que el commit que se ha aplicado, está a nombre del contribuidor externo que ha enviado el MR, a pesar de no ser miembro del proyecto.

    Esto es porque el MR incorpora los commit que se han realizado sobre el fork, no únicamente los cambios.

    Volver al inicio

    Finalizando

    Esta guía recopila algunas buenas prácticas en gestión de proyectos, y su aplicación en GitLab. Pero estas no son las únicas buenas prácticas que puedes seguir, ni la única manera de aplicarlas.

    Existen muchas otras, como seguir una buena guía de estilo al escribir un commit^

    Tampoco es necesario seguir todas las prácticas a rajatabla: todo dependerá del proyecto que estés realizando y de sus necesidades. Aunque puede ser buena idea.

    Existen muchos otros modos de organizar el desarrollo, como la integración continúa y el desarrollo basado en test (TDD), que no hemos explicado aquí.

    Aquí sólo hemos explicado unas pautas básicas, ya es tu trabajo seguir investigando en estos temas, para seguir aprendiendo

    Volver al inicio

    Referencias

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *