Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

Introduccin a GITHUB: flujo de trabajo

cesar pachn http://www.cesarpachon.com cesarpachon@gmail.com Junio 2013

Contenido
Introduccin a GITHUB: flujo de trabajo ......................................................................................1 1 Introduccin: qu es Github?................................................................................................ 1 2 Flujo de trabajo en github ................................................................................................... 1 3 Un ejemplo real.................................................................................................................... 3 3.1 Paso 1: Haciendo el Fork...............................................................................................3 3.2 Paso 2: Clonando el proyecto localmente.....................................................................4 3.3 Paso 3: actualizando el repositorio local desde el repositorio original...........................5 3.4 Paso 4: cambio local .................................................................................................... 5 3.5 Paso 5: commit............................................................................................................. 6 3.6 Paso 6: pull request....................................................................................................... 7 3.7 Esperando la aceptacin ..............................................................................................9 4 Referencias........................................................................................................................ 10

Introduccin: qu es Github?

GitHub (http://www.github.org) es un portal web que ofrece el servicio gratuito de repositorios para proyectos de software libre utilizando el sistema de control de cambios "git". Git se diferencia de sistemas tradicionales como CVS y subversion entre muchas otras cosas porque promueve la creacin de forks (copias derivadas del proyecto original) y por esta razn presenta un flujo de trabajo que al principio es un poco difcil de entender.

Flujo de trabajo en github

La figura 1 ilustra uno de los escenarios posibles que se pueden presentar al trabajar con http://www.cesarpachon.com - 1 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning github (git en general). En primer lugar, se distinguen dos espacios principales: el servidor de github, y la mquina local del usuario. En este ejemplo, asumimos que existe una organizacin (llamada "organizacion") con un proyecto llamado "principal". Otro usuario, llamado "Juan", se interesa por el proyecto. En este momento, el proyecto va en su versin 0.2.

Figura 1: Flujo de trabajo colaborativo en un proyecto abierto de GitHub Lo primero que hace Juan es hacer un Fork del proyecto (paso 1). Con esto, consigue crear una copia exacta del proyecto en ese instante, que quedar publicada como juan/principal en el sistema github. Ahora Juan debe descargar esa copia a su equipo local. Para ello, ejecuta el comando de clonar de git, y ahora si, cuenta con una copia del proyecto en su versin 0.2 lista para usar y modificar (paso 2). Mientras juan trabaja con el proyecto local, "organizacion" sigue haciendo cambios por su cuenta, llevando el proyecto "organizacion/principal" a la versin 0.4. Juan decide actualizar su repositorio local, por lo que ejecuta un comando fetch (paso 3) que actualiza cambios en la mquina local. Aqu es importante destacar que el fork de juan en github sigue en la versin 0.2, slo se afect la versin local. En el paso 4, Juan agrega un cambio a su repositorio local y desea publicarlo. Lo primero es subir el cambio a su fork en github, para ello usa el comando commit (paso 5).

http://www.cesarpachon.com - 2 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning una vez el fork queda en versin 0.5, decide enviar el cambio al repositorio original. Esto no se puede hacer directamente. Debe hacer una solicitud al encargado de ese repo. Esto se llama un "pull request" (6). eventualmente el administrador de "organizacion" revisa y aprueba el cambio, y por medio de un merge (7) lo incluye en el cdigo oficial del proyecto.

Un ejemplo real

Es hora de un ejemplo real. El usuario "juan" ser mi propio usuario de github ("cesarpachon"). El proyecto principal ser el proyecto gpbexporter del usuario forestmedia (https://github.com/forestmedina/gpbexporter). Se trata un script en python para exportar modelos 3d desde el programa de modelado Blender 3D (www.blender3d.org) al motor de videojuegos Gameplay3D (www.gameplay3d.org). Algo bueno de usar este proyecto como ejemplo es que slo hay un archivo principal, por lo que se trata de un repositorio pequeo. 3.1 Paso 1: Haciendo el Fork

Figura 2: Haciendo el fork en la pgina original del proyecto Para hacer el fork ingresamos a la pgina del proyecto

(https://github.com/forestmedina/gpbexporter) y buscamos el botn "fork" en la parte superior derecha de la pgina. Con esto, se crea una copia del proyecto en cesarpachon/gpbexporter (ver figura 3).

http://www.cesarpachon.com - 3 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

Figura 3: copia del proyecto en cuenta personal 3.2 Paso 2: Clonando el proyecto localmente

Para clonar el proyecto en el equipo local hay que ubicarse en la carpeta en donde quedar almacenado (/home/cesar/).

luego se ejecuta el comando git clone, pasando la direccin web que aparece en la pgina del proyecto a clonar (aparece un recuadro en la parte inferior derecha de la pgina).

Figura 4: clonacin del proyecto en equipo local

http://www.cesarpachon.com - 4 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning 3.3 Paso 3: actualizando el repositorio local desde el repositorio original

La operacin de actualizacin desde el repositorio original (no el repositorio del usuario en github) se llama fetch. Un fetch normal actuara desde cesarpachon/gpbexporter, pero queremos que la operacin ocurra desde forestmedina/gpbexporter, asi que hay que configurar el remoto del repositorio. Por defecto, el remoto es el repositorio en github del usuario, y se llama "origin". Hay que agregar un remoto al proyecto original llamado "upstream".

Figura 5: agregando la ruta remota upstream

git remote -v permite verificar que "origin" y "upstream" estn correctamente configurados:

git fetch upstream es el comando que ejecutar la consulta y descarga de cambios desde el repositorio original a la copia local:

3.4

Paso 4: cambio local

Un cambio local puede ser realizar un cambio al contenido de un archivo existente agregar un nuevo archivo. En este ejemplo, he agregado un archivo de prueba (test/cone.blend) al proyecto:

http://www.cesarpachon.com - 5 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

3.5

Paso 5: commit

El archivo slo existe localmente. Hay que notificar a git que se desea agregarlo al proyecto, usando el comando git add <<nombre archivo>>. Se puede usar git status para verificar qu archivos estn pendientes para el commit:

el comando git commit se encarga de subir los cambios (primero sale una pantalla que solicita escribir un comentario que acompae el commit, en este caso escrib "adding simple test file":

un ltimo comando, git push, se encarga del envo de todos los cambios del commit al servidor remoto:

http://www.cesarpachon.com - 6 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

verificamos consultando la pgina web de github y el archivo cone.blend aparece all:

3.6

Paso 6: pull request

El paso final consiste en solicitar que nuestros cambios sean agregados al repositorio original, el cul est fuera de nuestro control. Para ello, visitamos la pgina del repositorio original (forestmedina/gpbexporter, en este caso) y ubicamos el enlace "pull requests" que aparece al lado derecho de la pgina:

http://www.cesarpachon.com - 7 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

este enlace nos permite ver todos los pull request creados, y crear uno nuevo, con el botn "New pull request":

el sistema permite comparar cambios entre diferentes ramas (branch) del mismo repositorio, o entre forks. Debemos pues seleccionar el hipervnculo "compare across forks":

Seleccionamos

como

base

el

proyecto

origen

(forestmedina:master)

como

repositorio de comparacin, el nuestro (cesarpachon:master): el sistema muestra la adicin del archivo test/cone.blend.

http://www.cesarpachon.com - 8 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

una vez hemos verificado que los cambios a subir son los deseados, hacemos click en el link que dice "click to create a pull request for this comparision". El paso final consiste en escribir un ttulo y una descripcin para la solicitud que estamos creando. Se pueden agregar imgenes. El botn "send pull request" termina el proceso.

3.7

Esperando la aceptacin

Ahora, es cuestin de esperar a que el encargado del repositorio original reciba la notificacin y acepte nuestro cambio. Una vez es aceptado, aparecer nuestra contribucin en el repositorio principal:

http://www.cesarpachon.com - 9 de 10

Cesar Pachn Consultora y Desarrollo en computacin grfica, videojuegos y e-learning

Referencias

https://help.github.com/articles/fork-a-repo https://help.github.com/articles/syncing-a-fork https://help.github.com/articles/adding-a-remote

http://www.cesarpachon.com - 10 de 10