Este documento pretende ser una breve guía para comenzar a utilizar Git y Gerrit.

Git es una herramienta que tiene por objetivo el control de versiones del código fuente. La misma permite ir guardando cada versión del código de forma tal de poder volver atrás en el código y determinar exactamente los cambios entre una versión y otra. Esta herramienta permite ademas que varios programadores trabajen simultáneamente en distintas partes del código, permitiendo el intercambio simple de los cambios entre los desarrolladores Gerrit es una extension de Git y tiene por funciona principal establecer un mecanismo de revisión de los cambios en el código antes de la publicación de los mismo. De esta solo llega al repositorio final código que ha sido probado y revisado.

El proyecto utiliza GitHub.com como proveedor de git y gerrithub.io como proveedor de gerrit.

Para comenzar a utiilizar GerritHub accedemos a la dirección https://review.gerrithub.io/static/intro.html con lo que veremos la primera pantalla del proceso de alta de un nuevo usuario que se muestra a continuación

En la misma obtenemos un resumen de los pasos que debemos completar para la creación del usuario de GerritHub. Para continuar presionamos el botón verde que se encuentra en la esquina superior izquierda con la leyenda GitHbu Sing-in, y al hacer clic en el mismo nos lleva a una segunda pantalla que corresponde a la pantalla de login de GitHub que se muestra a continuación

En la misma deberemos completar nuestro nombre de usuario y contraseña de la cuenta de GitHub y continuar con el boton gris con la leyenda Sign In que se encuentra debajo del campo de password. Puede suceder que nuestro navegador ya tenga la información de nuestra cuenta de GitHub almacenada y en este caso esta pantalla no se muestra y avanzaremos automáticamente a la siguiente pantalla

En la misma nos pide confirmar los datos de nuestra cuenta en Gerrit, los cuales se completan automáticamente a partir de la información de nuestra cuenta de GitHub. Una vez que la información de esta pantalla es correcta avanzamos con el botón verde de la izquierda superior derecha con la leyenda Next, lo que nos llevara a la pantalla que se muestra en la figura

En la misma se nos pide que seleccionemos un repositorio de GitHub para clonar en Gerrit. En la lista de selección desplegable completamos CIAA y dejamos los tildes en todas las listas de los submodulos. A continuacion avanzamos con el botón verde de la izquierda superior derecha con la leyenda Next, lo que inicia el proceso de clonación del repositorio de GitHub en Gerrit. Cuando el proceso se complete veremos la pantalla que se muestra en la figura

En esta pantalla avanzamos una vez mas con el botón verde de la izquierda superior derecha con la leyenda Next, con lo que se inicia el proceso de importar los Pull Requets pendientes del repositorio que se acaba de clonar. Al terminar el proceso veremos una pantalla que se muestra en la figura

En esta pantalla avanzamos una vez mas con el botón verde de la izquierda superior derecha con la leyenda Next, con lo que se inicia el proceso de importar. Al terminar el proceso veremos el dashboard, la pantalla con la que habitualmente iniciaremos nuestras actividades en GerritHub que se muestra a continuación

Para poder enviar los cambios al servidor pueden utilizarse dos protocolos: https o ssh. En caso de optar por el protocolo https es necesario definir una clave en nuestro prefil de usuario de GerritHub y si vamos a utilizar el protocolo ssh es necesario generar un certificado y cargar la parte publica del mismo en nuestro perfil de GerritHub. A continuación se detallan los pasos a seguir para ambas opciones

Para generar una clave https para nuestro usuario GerritHub debemos acceder al dashboard y ingresar a los settings de nuestra cuenta como se muestra en la figura a continuación

Con lo cual accedemos a la configuracion de nuestra cuenta en GerritHub, a continuación seleccionamos la sexta opción del menú de la izquierda que dice HTTP Password, con lo cual accedemos a la pantalla que se muestra a continuación

En esta pantalla presionamos el boton Generate Password para generar una clave aleatoria. GerritHub no nos permite fijar una clave arbitraria sino que la misma debe ser generada al azar obligatoriamente. Esta clave deberá ser ingresada al momento de hacer un envío al servidor, para evitar el ingreso de esta clave larga y completa la mejor opción es incluir el nombre de usuario y la password al momento de hacer el clonado del repositorio, de esta forma queda almacenada permanentemente en nuestra copia local. Esto tiene como desventaja que cualquier persona con acceso a la copia local puede hacer cambios en el repositorio usando nuestra cuenta.

Para generar un certificado SSH simplemente abrimos una terminal y escribimos el siguiente comando:

ssh-keygen

Después de informarnos que estamos por generar una nuevo certificado RSA nos pedirá el nombre del archivo de donde almacenará el certificado. Por defecto utiliza un archivo llamado id_rsa dentro de la carpeta .ssh en el directorio del usuario. A continuación nos pedirá una clave para proteger el acceso al archivo que contiene la parte privada del certificado. Es conveniente definir una clave y no dejarla en blanco. Finalmente nos confirmará la creación de los dos archivos de los certificados. El archivo ~/.ssh/id_rsa es la parte privada y no debe ser publicada, mientras que el archivo ~/.ssh/id_rsa.pub es la parte publica y puede ser distribuida sin problemas. Puede ser que este proceso ya haya sido realizado antes, en cuyo caso no es necesario generar un nuevo certificado sino que podemos usar el existente.

En primer lugar aclaro que no he probado este proceso personalmente, y que el mismo una traduccion y sintesis del articulo Working with GIT on Windows, en el mismo se presentan varias alternativas pero nosotros solo vamos a seguir la que requiere la instalación de la menor cantidad de herramientas adicionales. Para esto y partiendo del supuesto que ya tenemos Git instalado, abrimos una terminal Bash de Git y seguimos un procedimiento muy parecido al de Linux, por lo que es recomendable leer el apartado anterior antes de continuar ingresando el siguiente comando

ssh-keygen -t rsa

Igual que en Linux nos pedirá la confirmación del nombre de archivo para el certificado una clave de acceso al mismo. Al terminar tendremos tambien dos archivos: id_rsa es la parte privada y id_rsa.pub es la parte publica. Estos archivos podremos encontrarlos en C:\Users\username\.ssh\ o en C:\Documents and Settings\username\.ssh\ según la version de Windows que se este utilizando.

Para que el servidor reconozca nuestra identidad es necesario informarle la parte publica del certificadoen nuestra cuenta de usuario. Para ello debemos acceder al dashboard y ingresar a los settings de nuestra cuenta como se muestra en la figura a continuación

Con lo cual accedemos a la configuracion de nuestra cuenta en GerritHub, a continuación seleccionamos la qinta opción del menú de la izquierda que dice SSH Public Keys, con lo cual accedemos a la pantalla que se muestra a continuación

Ahora debemos abrir con un editor de textos el archivo id_rsa.pub que contiene la parte publica de nuestro certificado, seleccionar todo el texto y copiarlo, a continuacion lo pegamos en el area de texto con el titulo Add SSH Publick Key y presionamos el boton Add, con lo cual la pantalla cambia y nos nuestra una lista de las claves ingresadas.

La primera parte del trabajo se realiza utilizando un client git como veniamos haciendo. La única diferencia es que el origen del repositorio será el servidor de GerritHub en lugar del servidor de GitHub. Si estamos empezando y todavía no tenemos una copia local del repositorio entonces la debemos clonar con el siguiente comando

git clone --recusive https://usuario:password@review.gerrithub.io/ciaa/Firmware

El mismo utiliza el protocolo https, si preferimos utilizar ssh entonces el comando será

git clone --recusive ssh://usuario@review.gerrithub.io:29418/ciaa/Firmware

Si por el contrario ya tenemos una copia local del repositorio en nuestra maquina podemos cambiar el servidor ogigen de la copia utilizando el siguiente comando

git remote set-url origin https://usuario:password@review.gerrithub.io/ciaa/Firmware

Nuevamente si preferimos utilizar ssh en luagr de https el comando sera el siguiente

git remote set-url origin ssh://usuario@review.gerrithub.io:29418/ciaa/Firmware

Es importante remarcar que si es la primera vez que nos conectamos al servidor se nos pedirá confirmar la clave de encriptacion utilizada por el ssh del servidor, para lo cual nos mostrara el hash RSA. Nosotros deberiamos controlar que dicho hash corresponde al que aparece en la pagina donde cargamos la parte publica del nuestro servidor antes de continuar. Una vez que aceptamos el mensaje esa clave se agrega a la lista de servidores conocidos por nuestro cliente ssh y no nos vuelve a preguntar por la identidad del mismo Continuando con el entorno git, es recomendable que antes de comenzar a trabajar ingresemos nuestros datos para que los cambias que hagamos queden correctamente identificados. Para eloo tuilizamos llos comandos para configurar el nombre de usuario y el correo.

git config user.name "Esteban Volentini"
git config user.email evolentini@gmail.com

Estos comandos configuran estos datos unicamente para el repositorio de la CIAA, y deben ser ingresados cada vez que se haga una nueva copia local del repositorio con el comando clone. Ahora por fin estamos en condiciones de empezar a programar, con lo cual abrimos nuestro editor de texto o el IDE y comenzamos a trabajar.

Una vez que terminamos entonces podemos hacer una revision de los cambios que hicimos con el comando

git diff

El cual nos mostrará una pantalla similiar a la que se muestra a continuacion

En la mismas se pueden ver cada uno de los bloques cambiados, el cual empieza con una cantidad de lineas en color blanco que corresponden a lineas que no sufrieron cambios, seguidas de lineas en color rojo que corresponden a las lineas suprimidas y lineas en color verde que son las lineas agregadas. Como puede notarse un cambio dentro de una linea de codigo implica la eliminacion de la linea original y la creacion de una nueva linea.

Si estamos de acuerdo con todos los cambios entonces es el momento de confirmarlos. Para ello utilizaremos el comando

git commit -a -m "\#235 use result value of fseek functions"

donde el parametro -a indica que queremos confirmar todos los cambios realizados, incluyendo los archivos eliminados y los archivos creados ademas de los cambios en los archivos existentes. El parametro -m nos permite ingresar un texto para explicar los cambios realizados. Dentro del proyecto CIAA utilizamos el sistema de Issues para documentar los cambios que se realizan, por lo tanto en todos los commits debemos ingresar un comentario que inicia con # continuado del numero del Issue que motiva los cambios y con un texto breve que describa los cambios realizados, de preferencia en idioma ingles.

Ahora estamos en condiciones de enviar los cambios al servidor de GerritHub para su revision Para ello utlizamos el siguiente comando

git push origin HEAD:refs/for/master

En esta linea es clave la ultima parte donde ref/for/master le indica al servidor de Gerrit que es un cambio sujeto a revision y que esta destinado a la rama master. Una vez completo el envío al servidor ingresamos una vez mas al dashboard de GerritHub y obtenemos la siguiente pantalla

En la misma podemos ver que aparecen los cambios que enviamos para iniciar el proceso de revision.