Guía de Trabajo Colaborativo en GitHub con Ramas

Conceptos Clave (El Diccionario del Colaborador)

Antes de empezar, debemos entender algunos términos básicos:

Repositorio (Repo): Es la carpeta principal de su proyecto. Contiene todos los archivos (código, datos, notebooks) y el historial completo de cambios. Vive tanto en tu computadora (local) como en GitHub (remoto).
Clonar (Clone): Es el acto de descargar una copia completa del repositorio remoto (de GitHub) a tu propia computadora para poder trabajar en él.
Rama (Branch): ¡Este es el concepto más importante para la colaboración! Imagina que la rama main es la versión “oficial” y estable de tu proyecto. Cuando quieres añadir algo nuevo o corregir un error, creas una nueva rama, que es una copia personal y paralela del proyecto. En esta nueva rama puedes hacer todos los cambios que quieras sin afectar la versión oficial.
Commit: Es una “fotografía” o un punto de guardado de tus cambios en tu rama. Cada commit tiene un mensaje que describe qué modificaste. Es como guardar una versión del archivo, pero con un registro claro de qué hiciste.
Push: Es la acción de “empujar” o subir los commits (tus cambios guardados) de tu rama local (en tu computadora) al repositorio remoto en GitHub. Así, los demás pueden ver tu progreso.
Pull Request (PR): Es una “solicitud para fusionar”. Cuando has terminado tu trabajo en tu rama, creas un Pull Request en GitHub. Esto le dice al resto del equipo: “He terminado mis cambios, por favor revísenlos y, si todo está bien, incorpórenlos a la rama principal main”.
Fusión (Merge): Es el acto de tomar los cambios de una rama e integrarlos en otra, usualmente después de que un Pull Request es aprobado. Git es increíblemente bueno haciendo esto de forma automática.

1. Clonar el repositorio

Este es el momento de abrir VS Code, Google Colab o tu herramienta preferida y hacer tu magia. Modifica los archivos, crea nuevos, etc.

Para VS Code: La integración con Git es nativa y excelente. Puedes ver los cambios, hacer commits y gestionar ramas desde la pestaña “Source Control”.
Para Google Colab: Puedes clonar el repositorio dentro del entorno de Colab con !git clone .... Trabaja en tu notebook y, cuando termines, guarda tus cambios y usa los comandos de Git (!git add ..., !git commit ...) directamente en las celdas del cuaderno para registrar tu trabajo.

Cada estudiante debe clonar el repositorio central en su computador:

git clone https://github.com/usuario/repositorio.git
cd repositorio

2. Crear una rama personal

Cada colaborador trabaja en una rama distinta para no afectar el código principal (main o master):

git checkout -b nombre_rama

Ejemplo:

git checkout -b juan-feature1

3. Realizar cambios en la rama

Editar archivos, agregar nuevos o eliminar lo que sea necesario. Luego, guardar los cambios en Git:

git add .
git commit -m "Descripción clara de los cambios"

4. Subir la rama a GitHub

Enviar la rama al repositorio remoto:

git push origin nombre_rama

5. Crear un Pull Request (PR)

Ir al repositorio en GitHub.
GitHub mostrará la opción Compare & Pull Request.
Describir los cambios y solicitar revisión.

6. Revisar y fusionar (merge)

Otro compañero o el profesor revisa el Pull Request.
Si todo está correcto, se aprueba y se hace merge a la rama principal (main).
Git combina los cambios de manera inteligente para que todos trabajen sobre la versión más actualizada.

7. Mantener la rama sincronizada

Antes de seguir trabajando, actualizar la rama local:

git checkout main
git pull origin main
git checkout nombre_rama
git merge main

8. Resolver conflictos

Si dos personas modifican la misma línea de un archivo, aparecerán conflictos.

Git marcará el archivo con las dos versiones.
El estudiante debe elegir qué parte conservar y volver a hacer:

git add archivo_conflictivo
git commit -m "Conflictos resueltos"

9. Buenas prácticas

Usar nombres de rama claros: nombre-alumno-tareaX.
Hacer commits pequeños y con mensajes descriptivos.
Revisar siempre la rama principal antes de empezar nuevos cambios.
Usar Pull Requests para discutir y revisar antes de fusionar.
No trabajar nunca directamente en main.

Anexo 1: Ramas

En un entorno colaborativo de Google Colab con GitHub, la creación de ramas puede ser realizada tanto por el líder (Estudiante 1) como por los demás estudiantes colaboradores. Aquí te explico cómo funciona:

¿Quién crea las ramas?

Ambos pueden crear ramas, pero con diferentes niveles de acceso:

1. El Líder (Estudiante 1)

Tiene acceso completo al repositorio
Puede crear ramas directamente en el repositorio
Puede crear ramas para otros estudiantes si es necesario

2. Estudiantes Colaboradores (2, 3, etc.)

También pueden crear sus propias ramas
Lo hacen mediante fork y pull requests o creando ramas directamente si tienen permisos

Cómo crean ramas los estudiantes colaboradores:

Opción 1: Con permisos de colaborador (Recomendado)

El líder les da acceso como colaboradores en GitHub:
- Settings → Collaborators → Add people

Los estudiantes clonan el repositorio:

git clone https://github.com/usuario/repositorio.git

Crean su rama:
```
git checkout -b nombre-rama-estudiante
```

Opción 2: Mediante Fork (Alternativa común)

Cada estudiante hace fork del repositorio

Clonan su fork:

git clone https://github.com/estudiante/repositorio-forkeado.git

Crean su rama en su fork personal
Hacen pull requests al repositorio original

Flujo de trabajo recomendado:

# Para cada estudiante colaborador:
git clone [URL del repositorio]
git checkout -b feature/estudiante2-tarea-especifica

# Trabajar en Google Colab...
# Guardar cambios

git add .
git commit -m "Descripción de los cambios"
git push origin feature/estudiante2-tarea-especifica

Configuración en Google Colab:

Conectar Google Colab a GitHub
Seleccionar la rama correcta antes de empezar a trabajar
Guardar cambios en la rama correspondiente

Buenas prácticas:

Usar nombres descriptivos para las ramas: feature/nombre-estudiante-descripcion
El líder debería proteger la rama main
Hacer pull requests para integrar cambios a main
Sincronizar regularmente con los cambios del main

Anexo 2: Uso del símbolo de exclamación `!` en Colab

En Google Colab, puedes usar el símbolo de exclamación ! para ejecutar comandos de terminal directamente en las celdas de código. Esto es extremadamente útil para gestionar repositorios de GitHub, instalar paquetes, y mucho más.

Uso básico de `!` en Colab

Ejecutar comandos simples:

# Listar archivos en el directorio actual
!ls

# Ver el directorio actual
!pwd

# Instalar un paquete con pip
!pip install numpy pandas

# Clonar un repositorio de GitHub
!git clone https://github.com/usuario/repositorio.git

Comandos Git esenciales con `!`

1. Configuración inicial:

# Configurar usuario de Git
!git config --global user.name "Tu Nombre"
!git config --global user.email "tu.email@ejemplo.com"

2. Clonar y configurar repositorio:

# Clonar el repositorio (solo la primera vez)
!git clone https://github.com/lider/repositorio.git

# Navegar al directorio
%cd repositorio

# Ver ramas disponibles
!git branch -a

3. Crear y cambiar de rama:

# Crear una nueva rama y cambiarse a ella
!git checkout -b mi-rama

# O alternativamente: crear y luego cambiarse
!git branch mi-rama
!git checkout mi-rama

# Ver en qué rama estás actualmente
!git branch

4. Trabajar con cambios:

# Ver estado de los cambios
!git status

# Agregar archivos específicos
!git add mi_archivo.ipynb

# Agregar todos los cambios
!git add .

# Hacer commit
!git commit -m "Agregué análisis de datos inicial"

# Subir cambios al repositorio remoto
!git push origin mi-rama

5. Sincronizar con main:

# Cambiarse a main
!git checkout main

# Traer los últimos cambios
!git pull origin main

# Volver a tu rama
!git checkout mi-rama

# Fusionar main en tu rama
!git merge main

Ejemplo de flujo completo:

# Celda 1: Configuración inicial
!git clone https://github.com/lider/proyecto-colab.git
%cd proyecto-colab
!git checkout -b analisis-datos-estudiante2

# Celda 2: Trabajar en el notebook
# [Aquí tu código de análisis...]

# Celda 3: Guardar y subir cambios
!git add .
!git commit -m "Análisis exploratorio completado"
!git push origin analisis-datos-estudiante2

Trucos útiles:

1. Capturar output de comandos:

# Guardar el resultado en una variable
resultado = !ls
print(resultado)

2. Usar variables de Python en comandos:

nombre_rama = "feature-nueva"
!git checkout -b {nombre_rama}

3. Múltiples comandos en una celda:

# Usar && para encadenar comandos
!git add . && git commit -m "Cambios" && git push

4. Ver historial de commits:

!git log --oneline --graph --all

Manejo de credenciales:

# Para evitar pedir usuario/contraseña cada vez
# Configurar token de acceso personal
!git remote set-url origin https://token@github.com/usuario/repositorio.git

Comandos útiles para troubleshooting:

# Ver configuración de Git
!git config --list

# Forzar push si hay conflictos
!git push -f origin mi-rama

# Descargar cambios remotos
!git fetch --all

0_Guía de Trabajo Colaborativo en GitHub con Ramas

ChatBots para Justo Fuentes

2025-09-16