Configuración del repositorio para la entrega de trabajos prácticos

La presente guía tiene por objeto explicar la metodología y configuración, a emplear por la Cátedra, para la utilización del sistema de control de versiones GIT. De manera muy sintética y simplista se puede definir un sistema de control de versiones como aquel software que permite identificar de manera unívoca el conjunto de ficheros de código, y sus correspondientes modificaciones, que componen un determinado programa. Todo sistema de control de versiones dispone de un servidor, en donde se ubica el código, y un cliente, siendo este último la herramienta utilizada por el desarrollador para acceder a las funcionalidades brindadas por el sistema. Existen en la actualidad una gran cantidad de sistemas con diferentes metodologías de trabajo y métodos de identificación de cambios, entre los cuales se pueden citar los open source SVN, GIT, Mercurial o los comerciales IBM Rational Synergy o Microsfot Source Safe. Sin embargo el objetivo de todos ellos es el mismo, y se puede resumir mediante el siguiente ejemplo:

En un grupo de desarrollo conformado por dos personas, se están realizando cambios en un fragmento de código que se encuentra en el fichero funcion.c, el cual se ubica en un servidor compartido. Inicialmente el desarrollador A abre el fichero, generando una copia local, y comienza a realizar las modificaciones bajo su responsabilidad, a su vez el desarrollador B también abre el fichero generando su propia copia local y comienza a trabajar realizando las modificaciones que le fueron asignadas. Como se puede apreciar existen dos copias de un mismo fichero original en ubicaciones diferentes, cada una de ellas con distintos cambios según el trabajo que se esté realizando. En este escenario el desarrollador A puede guardar el fichero en el servidor, preservando los cambios realizados sin inconvenientes, sin embargo si el desarrollador B guardara sus cambios en el servidor, estaría sobrescribiendo lo realizado por A y por ende los cambios de este último se perderían. En este punto es donde entra en acción el sistema de control de versiones; al momento en que B intenta guardar los cambios realizados, el sistema le indicará que existe una nueva versión (posterior a la original que copio localmente) y que debe tomar una decisión:

• Sobrescribir los cambios realizados por A. Esta opción rara vez se realiza.
• Descartar los cambios introducidos por el mismo. Solo se realiza en casos excepcionales.
• Preservar los cambios realizados por A e introducir los realizados por él. Esta opción es la más usual y consiste en realizar la mezcla de ambos ficheros (funcion.C_verA y funcion.c_verB).

Como se mencionó anteriormente, dependiendo del sistema que se utilice las opciones indicadas en el párrafo precedente pueden realizarse en forma automática, asistida o totalmente manual.

El sistema de control de versiones a utilizar por la Cátedra, es el GIT. Si bien este sistema dispone de una gran cantidad de funcionalidades, diseñadas especialmente para el desarrollo de código en forma cooperativa, solo se utilizará un conjunto muy reducido de las funcionalidades disponibles. Esto se debe a que la mayoría de los trabajos prácticos se debe realizar en forma individual, por lo tanto el sistema de control de versiones se está utilizando tan solo como un servidor centralizado, para alojar el código y poder compartirlo unicamente entre el docente y el alumno.

Las funcionalidades a utilizar por la herramienta recomendada por la Cátedra y se tratará en el apartado Herramientas

Antes de proceder a la configuración y operación del cliente de control de versiones, en nuestro escenario, se debe generar la estructura de carpetas a utilizar para la entrega de trabajos prácticos. Esta estructura es de caracter obligatorio y debe ser respetada para optimizar la interacción entre el docente y el alumno. En primera instancia se debe proceder a crear en la carpeta /home/su_usuario, del SO recomendado por la Cátedra, la siguiente estructura teniendo en cuenta que en todos los casos se deben utilizar minúsculas para los nombres

/home/su_usuario/repolocal/r505x-td3-pellido-nombre/01_cuat/tp_01_01
                                                         /tp_01_02
                                                         ...
                                                         /tp_01_m
                                                 /02_cuat/tp_02_01
                                                         /tp_02_02
                                                         ...
                                                         /tp_02_n							

Cada carpeta correspondiente mencionada anteriormente, debe disponer de la siguiente estructura interna

   /tp_01_xx/bin
            /doc
            /inc
            /lib
            /src
            /sup

El contenido a incluir en cada carpeta se detalla a continuación

• src código fuente de la aplicación, es decir los ficheros .asm y/o .c
• inc cabeceras utilizadas por la aplicación, como ser los ficheros .inc y/o .h
• lib bibliotecas pre compiladas utilizadas por la aplicación.
• bin binarios finales generados a partir de las carpetas mencionadas anteriormente. Esta carpeta solo debe colocarse en el repositorio por pedido expreso del docente.
• doc únicamente los ficheros de configuración necesarios para generar la documentación del código y/o un único fichero en formato .pdf
• sup contiene todos aquellos ficheros de soporte, que se requieren para la ejecución del binario en un entorno específico, como ser en nuestro caso, la configuración y la imagen del disco utilizado por el BOCHS

Adicionalmente la carpeta raíz de cada trabajo práctico (ej.: tp_01_xx) debe disponer de un fichero tipo script o makefile con todas la sentencias necesarias para la generación del binario final. En la carpeta raíz de todos los trabajos prácticos /home/su_usuario/repolocal/r505x-td3-apellido-nombre/ se debe incluir un fichero de texto con el resumen del estado de cada trabajo práctico, con el siguiente formato:

***********************************************************************************************************************************
*                                    Planilla de avance de Trabajos Prácticos del Alumno                                          *
*                                                                                                                                 *
* Instrucciones: Colocar en el directorio raíz del repositorio local, para que sea de fácil acceso. Completar los datos (Usuario  * * SGE, Legajo)
* Indicar el estado del ejercicio: Funciona: SI / NO                                                                              *
* Agregar comentarios en caso que consideren oportuno, (por ejemplo si se compila con un makefile).                                *
***********************************************************************************************************************************
->Usuario SIGA: 
->Legajo: 
********************************************
*		    TP 1		   *
********************************************
TP01.01: Funciona -> SI/NO       Comentarios:
TP01.02: Funciona -> SI/NO       Comentarios:
...
TP01.09: Funciona -> SI/NO       Comentarios:
...
TP01.14: Funciona -> SI/NO       Comentarios:
TP01.15: Funciona -> SI/NO       Comentarios:(Entrega Obligatoria)
********************************************
*              TP Integrador               *
********************************************
Servidor:    Funciona -> SI/NO       Comentarios:
Cliente:     Funciona -> SI/NO       Comentarios:
Driver:      Funciona -> SI/NO       Comentarios:

Independientemente de lo expresado en el párrafo anterior es de suma importancia que cada vez que se realice una actualización de los ficheros en el repositorio se indique el estado operativo (funciona/no funciona), detallando el problema actual y la resolución según corresponda. Esta metodología le permitirá al alumno analizar y recordar los diferentes inconvenientes con los que se topó al momento de realizar el ejercicio y como fueron resueltos, utilizando la herramienta de visualización del histórico de cada fichero/proyecto.

Al igual que los sistemas de control de versiones, existen una gran cantidad de herramientas (clientes) que permiten operar sobre el GIT. En la Cátedra se utilizará por defecto el Cliente GIT por consola, pero a fin de proveer mayor flexibilidad a los alumnos, se presenta la citan algunas alternaticas:

• Cliente git por consola: es el cliente más básico disponible para Linux ya que presenta una interfaz por línea de comandos.
• https://git-scm.com/download/gui/linux
• git gui - gitk: es la interfaz gráfica por defecto de GIT, dispone de todos los comandos de git, pero la experiencia de usuario es un tanto rústica para una GUI
• Gitkraken: es un cliente GUI versatil y poderoso pero de alto consumo de memoria.

El uso extensivo de GIT y sus respectivos clientes está fuera del alcance de esta guía, pero puede ser consultado en los manuales de los respectivos sistemas/herramientas.

De todo el conjunto de operaciones disponibles en GIT, vale la pena detallar las siguientes:

• clone: realiza una copia local de un repositorio existente.
• checkout: establece todos los ficheros del repositorio local a una versión/rama especifica.
• add: indica al repositorio local que el fichero especificado debe ser gestionado por el sistema de versionado.
• commit: permite almacenar en el repositorio local los ficheros y directorios, modificados desde el último acceso, creando los que no existan y actualizando los existentes.
• push: guarda en el repositorio origen o remoto, los cambios realizados en el local.
• pull: este comando es el complementario al anterior, ya que realiza una copia, actualización o eliminación local de los ficheros y directorios, que se hayan modificado en el servidor desde el último acceso. También es posible establecer la versión que se quiere utilizar como copia local, pero no entraremos en detalle de esta operatoria en este ítem.
• delete indica al repositorio local que el fichero especificado debe dejar de ser gestionado por el sistema de versionado.
• init: crea un repositorio local en el directorio actual.
• revert: deshace todos los cambios realizados desde el último commit realizado.
• log: muestra el histórico de cambios realizados en el repositorio.

Independientemente de la herramienta que se utilice los pasos para la configuración del repositorio local son los siguientes:

En GitLab

1. Ingresar https://gitlab.frba.utn.edu.ar/ con el usuario SInAP
2. Verificar que se disponga de las claves ssh configuradas en la PC de trabajo (Preferences->SSH Keys)
3. Seleccionar la pestaña Groups
4. Crear un grupo mediante el boton New group
5. Establecer Group path en apellido-nombre. En caso de tener dos o mas nombres y/o apellidos separarlos por “-”
6. Verificar que el Visibility Level seleccionado se Internal
7. Finalizar la creacion mediante Create group
8. Ingresar al grupo creado
9. Crear un proyecto mediante New Projet
10. Establecer Project Name en r505x-td3-apellido-nombre. En caso de tener dos o mas nombres y/o apellidos separarlos por “-”
11. Verificar que el Visibility Level seleccionado se Private
12. Sumar con perfil Master, a los usuarios indicados por los docentes
13. En el recuadro Project description presentar los siguientes campos con su informacion:

        usuario SInAP:
        mail:
        recursante: Si/No
        experiencia ASM: Alta/Media/Baja
        experiencia C: Alta/Media/Baja
        PC con Linux: Si/No
        Año Cursada Informatica II: YYYY
        Año Cursada Tecnicas Digitales II: YYYY

En su PC

1. Crear el directorio donde se harán los prácticos de la materia (por ejemplo /repolocal ).
2. Situarse en el directorio creado y clonar el repositorio remoto de GitLab, ingresando las respectivas credenciales

git clone https://gitlab.frba.utn.edu.ar/td3/repo/r505x-td3-apellido-nombre/r505x-td3-apellido-nombre
 

1. En el directorio raiz del repositorio crear el fichero de texto indicado en Estructuras de carpetas con los datos del alumno (.txt) y un fichero .gitignore con las siguientes reglas

# Ignore all 
* 

# Unignore all with extensions *.c *.h *.txt y con Makefile 
!*.c 
!*.h 
!Makefile 
!*.txt
!*.cpp
!*.hpp
!*README*
!*make*
!*suite*
!*.asm
!*.s
!*.inc
# Unignore all dirs
!*/

1. Dentro de cada carpeta de trábajo practico, crear un fichero .gitignore (/tp_01_xx/.gitignore). Dicho ficher debe tener las reglas que se indican a continuación para evitar copiar al repositorio remoto ficheros objeto y binarios. El siguiente modelo filtra todos los ficheros del directorio /bin y aquellos binarios y objetos generados por error dentro de los restantes directorios.

   ./bin/*
   ./inc/*.o
   ./inc/*.bin
   ./inc/*.elf
   ./lib/*.o
   ./lib/*.bin
   ./lib/*.elf
   ./lib/*.o
   ./lib/*.bin
   ./lib/*.elf
   ./src/*.o
   ./src/*.bin
   ./src/*.elf
   ./sup/*.o
   ./sup/*.bin
   ./sup/*.elf
   ./doc/*.o
   ./doc/*.bin
   ./doc/*.elf
   ./doc/*.html

1. Indicar, si es necesario, que hay nuevos ficheros que deben ser incluidos en la próximo commit

git add fichero.ext

1. Guardar los cambios realizados en el repositorio local

git commit -m "Mensaje indicando los cambios realizados"

1. Sincronizar el repositorio local

git push origin master

— ChristiaN 2023/03/25 18:00

• ¡No puedo ingresar al GIT desde el cliente!

Mediante un navegador WEB, ingresar la dirección https://gitlab.frba.utn.edu.ar/, y verificar que puede ingresar a su carpeta. De no ser posible, verifique que el usuario y clave sean correctos, ingresando al SIGA. En caso que el navegador WEB le permita ingresar, verifique que la dirección configurada en el cliente sea correcta. Si luego de verificar todo lo indicado aún no puede ingresar, consulte al docente a cargo.