Guía completamente reescrita, con los flujos de trabajo detallados para cada rol y las instrucciones claras para crear y usar un Token de Acceso Personal (PAT). Está diseñada para ser compartida directamente con los alumnos.

Guía Definitiva de Trabajo Colaborativo en GitHub desde Google Colab

Esta guía está diseñada para que puedas colaborar con tu equipo en un mismo proyecto de Python utilizando Git y GitHub, pero ejecutando todos los comandos directamente desde un Notebook de Google Colab.

📖 Conceptos Clave (El Diccionario del Colaborador)

Antes de empezar, es fundamental que todos hablen el mismo idioma. Repasemos los términos esenciales:

  • Repositorio (Repo): Es la carpeta principal de tu proyecto. Contiene todos los archivos, imágenes y el historial completo de cada cambio que se ha realizado. Vive tanto en la nube (GitHub) como en tu entorno de trabajo (Colab).
  • Clonar (Clone): Es la acción de descargar una copia exacta y completa del repositorio desde GitHub a tu sesión de Google Colab.
  • Rama (Branch): Es una línea de trabajo paralela e independiente. La rama main se considera la versión “oficial” y estable del proyecto. Para añadir nuevas funcionalidades o trabajar en tu parte, creas tu propia rama sin afectar el código principal.
  • Commit: Una “fotografía” o punto de guardado de tus cambios en tu rama. Cada commit debe llevar un mensaje claro que describa qué modificaste.
  • Push: La acción de subir tus commits (tus “fotografías” guardadas) desde tu entorno de Colab al repositorio remoto en GitHub, para que el resto del equipo pueda ver tu progreso.
  • Pull Request (PR): Una “solicitud para integrar cambios”. Cuando terminas tu trabajo en tu rama, abres un PR en la web de GitHub. Es una invitación formal para que tus compañeros revisen tu código y, si todo está correcto, lo aprueben para fusionarlo con la rama main.
  • Fusión (Merge): El acto de integrar los cambios de una rama en otra (usualmente, de tu rama personal a la rama main) una vez que el Pull Request ha sido aprobado.

🚀 Flujo de Trabajo Paso a Paso

Dividiremos el proceso en dos roles: el Líder del Proyecto (Estudiante 1), que prepara el terreno, y los Colaboradores (Estudiantes 2 y 3), que desarrollan el trabajo.

Parte 1: Misión del Líder del Proyecto (Estudiante 1)

Realiza estos pasos solo una vez al inicio del proyecto.

Objetivo: Crear el repositorio, establecer la estructura inicial y dar acceso a los colaboradores.

  1. Crear el Repositorio en GitHub 🏗️

    • Ve a tu cuenta de GitHub y crea un nuevo repositorio.
    • Nómbralo de forma descriptiva (ej: Proyecto-Programacion-Equipo5).
    • MUY IMPORTANTE: Marca la casilla Add a README file. Esto inicializa el repositorio con la rama main lista para usar.
    • Puedes elegir si será Public o Private.

  2. Añadir Colaboradores 🤝

    • Dentro del repositorio, ve a la pestaña Settings > Collaborators.
    • Añade a tus compañeros usando sus nombres de usuario de GitHub.
    • Avísales que deben revisar su correo electrónico y aceptar la invitación.

  3. Crear y Subir el Notebook Inicial 📝

    • Abre Google Colab y crea un nuevo notebook.

    • Define la estructura del trabajo con títulos y secciones claras para cada estudiante. Esto es clave para minimizar conflictos.

      # =========================================
# CUADERNO DE TRABAJO COLABORATIVO
# Asignatura: Estadística Aplicada con Python
# =========================================

# =========================================
# SECCIÓN 1: Estudiante 1
# TODO: Desarrollar aquí la Situación 1
# =========================================

# =========================================
# SECCIÓN 2: Estudiante 2
# TODO: Desarrollar aquí la Situación 2
# =========================================

# =========================================
# SECCIÓN 3: Estudiante 3
# TODO: Desarrollar aquí la Situación 3
# =========================================

    • Guarda este notebook directamente en tu repositorio. En Colab, ve a Archivo > Guardar una copia en GitHub.

    • Selecciona el repositorio correcto, deja la rama como main y escribe un mensaje de commit descriptivo (ej: feat: Crea estructura inicial del notebook).

¡Misión cumplida! El proyecto base ya está en GitHub y los colaboradores tienen acceso.

Parte 2: Misión de los Colaboradores (Estudiantes 2 y 3)

Sigue estos pasos después de que el Líder del Proyecto haya preparado todo.

Objetivo: Traer el proyecto a tu entorno, trabajar en tu propia rama y proponer tus cambios para integrarlos.

  1. Aceptar la Invitación ✅

    • Busca en tu correo la invitación de GitHub para colaborar. Haz clic y acéptala. ¡Ya tienes permisos sobre el repositorio!
    • Aceptas la invitación, dando clic en el Link, al dar clic en el link se abrirá el GitHub del que invita, verás un mensaje como: “@justoprogramacion has invited you to collaborate on this repository” y a la derecha verás un boton que dice: “View Invitation”, dale clic y te aparecerán dos botones uno verde que dice: “Accept Invitatios” y otro negro que dice: “Decline Invitatios”, dale clic al boton verde para aceptar la invitación.

  2. Preparar tu “Colab-Consola” 💻

    • ¡Paso Crítico! NO abras el notebook del proyecto directamente desde la web de GitHub.
    • En su lugar, abre una pestaña nueva y crea un cuaderno de Google Colab completamente vacío. Este cuaderno será tu “consola” o “terminal” para ejecutar los comandos de Git.

  3. Configurar tu Identidad de Git

    • En la primera celda de tu “Colab-Consola”, ejecuta lo siguiente para que tus contribuciones queden registradas a tu nombre. Solo necesitas hacerlo una vez por sesión.

      # Celda 1: Configurar usuario de Git
!git config --global user.name "TuNombreDeUsuarioEnGitHub"
!git config --global user.email "tu-email-asociado-a-github@ejemplo.com"

  4. Clonar el Repositorio 📥

    • Ve a la página del repositorio en GitHub, haz clic en el botón verde < > Code y copia la URL HTTPS.

    • En la siguiente celda de tu “Colab-Consola”, clona el proyecto y muévete a su directorio:

      # Celda 2: Clonar el proyecto y entrar en su carpeta
!git clone https://URL-QUE-COPIASTE.git
%cd nombre-del-repositorio

    • Si ejecutas el comando %ls, verás los archivos del proyecto, incluyendo el .ipynb inicial.

  5. Crear tu Rama de Trabajo Personal 🌿

    • Nunca trabajes directamente sobre la rama main. Crea tu propia “copia” para trabajar de forma segura. Usa un nombre descriptivo.

    • En una nueva celda, ejecuta:

      # Celda 3: Crear una nueva rama y cambiarse a ella
!git checkout -b nombre-alumno-tarea
# Ejemplo: !git checkout -b ana-graficos-dispersion

  6. ¡A Trabajar en el Notebook! 🚀

    • En el panel de archivos de la izquierda en Colab (icono de carpeta 📁), verás la carpeta del proyecto que clonaste.
    • Abre el notebook del proyecto (ej: desarrollo_proyecto.ipynb) haciendo doble clic sobre él en ese panel de archivos.
    • Ahora sí estás editando la copia correcta. Ve a tu sección asignada, desarrolla tu código y guarda tus cambios periódicamente (Ctrl+S).

  7. Guardar y Subir tus Cambios (Commit & Push) 📤

    • Cuando hayas alcanzado un punto de guardado lógico (ej: “terminé la función de carga de datos”), vuelve a tu “Colab-Consola”.

    • Ejecuta los siguientes comandos para guardar tus cambios en Git y subirlos a tu rama en GitHub:

      # Celda 4: Guardar y subir los cambios a tu rama
# 1. Añade TODOS los archivos modificados al área de preparación
!git add .

# 2. Confirma los cambios con un mensaje descriptivo
!git commit -m "feat: Completa el análisis exploratorio de la Situación 2"

# 3. Sube tu rama con tus commits a GitHub (reemplaza el nombre de la rama por el tuyo)
!git push origin ana-graficos-dispersion

🔐 Autenticación: Cómo Usar un Personal Access Token (PAT)

La primera vez que hagas push, Colab te pedirá que te identifiques. No uses tu contraseña de GitHub. La forma moderna y segura es usar un Token de Acceso Personal (PAT).

¿Cómo crear tu PAT?

  1. Ve a la Configuración de GitHub:
    • Haz clic en tu foto de perfil en la esquina superior derecha y selecciona Settings.
  2. Accede a la Configuración de Desarrollador:
    • En el menú de la izquierda, desplázate hacia abajo y haz clic en Developer settings.
  3. Selecciona Personal Access Tokens:
    • En el nuevo menú de la izquierda, haz clic en Personal access tokens y luego en Tokens (classic).
  4. Genera un Nuevo Token:
    • Haz clic en el botón Generate new token y elige Generate new token (classic).
  5. Configura tu Token:
    • Note (Nota): Dale un nombre descriptivo para que recuerdes para qué es (ej: Token para Google Colab).
    • Expiration (Expiración): Elige una duración. Para una tarea de clase, 30 o 90 días es una buena opción.
    • Select scopes (Seleccionar permisos): Esta es la parte más importante. Marca la casilla principal que dice repo. Esto le dará al token todos los permisos necesarios para clonar, leer y subir cambios a tus repositorios.
    • Haz clic en el botón verde Generate token al final de la página.
  6. ¡Copia y Guarda tu Token!
    • GitHub te mostrará el token UNA SOLA VEZ. Es una cadena de texto que empieza con ghp_....
    • Cópialo inmediatamente y guárdalo en un lugar seguro, como un gestor de contraseñas. Si lo pierdes, tendrás que generar uno nuevo.
    • Cuando Colab te pida el Password al hacer git push, pega este token.

Parte 3: El Proceso de Revisión (Pull Request)

  1. Crear el Pull Request (PR) en GitHub 💬

    • Después de hacer push, ve a la página del repositorio en GitHub. Verás una notificación amarilla destacando que subiste una nueva rama.
    • Haz clic en el botón Compare & Pull Request.
    • Añade un título claro y una descripción de los cambios que hiciste.
    • En la barra lateral derecha, asigna a un compañero o al líder como Reviewer.
    • Finalmente, haz clic en Create Pull Request.

  2. Revisar y Fusionar el PR ✅

    • El revisor asignado recibirá una notificación. Deberá revisar el código, puede dejar comentarios y, si todo está correcto, aprobará el PR.
    • Una vez aprobado, el líder del proyecto (o quien tenga permisos) podrá fusionar tus cambios a la rama main haciendo clic en Merge pull request.

Parte 4: Mantenerse Sincronizado

Antes de empezar una nueva tarea, es vital que actualices tu copia del proyecto con los últimos cambios que otros han integrado a main.

# Celda 5: Sincronización
# 1. Vuelve a la rama principal
!git checkout main

# 2. Descarga los últimos cambios del repositorio remoto
!git pull origin main

¡Ahora tu rama main local está al día y puedes crear una nueva rama para tu siguiente tarea!