Saltar a contenido

Capítulo 8: Trabajo colaborativo con GitHub

GitHub no solo sirve para alojar repositorios individuales: es, sobre todo, una plataforma de colaboración. Los proyectos Open Source y los equipos profesionales usan GitHub para coordinar trabajo entre muchas personas, revisar código, discutir cambios y mantener orden en el flujo de contribuciones.

En este capítulo vas a simular ese trabajo colaborativo usando el proyecto del libro y un segundo repositorio que actuará como proyecto original. Asumirás distintos roles (propietario, colaborador y revisor) y recorrerás el flujo completo: Fork, Clone, sincronización con upstream, ramas de trabajo, Pull Requests, Code Review e Issues.

8.1 ¿Cómo trabajan realmente los equipos de desarrollo?

Los equipos profesionales no trabajan todos sobre la misma copia del código ni envían archivos por correo. Utilizan Git y GitHub para que cada persona tenga su propia copia, su propia rama de trabajo y un flujo ordenado para proponer cambios y revisarlos antes de integrarlos.

Flujo profesional típico

Un flujo habitual en proyectos reales es:

  • Existe un repositorio original (a veces llamado upstream).
  • Cada desarrollador tiene una copia del repositorio (mediante clone o fork).
  • Cada cambio importante se desarrolla en una rama independiente.
  • Cuando la funcionalidad está lista, se abre un Pull Request.
  • Otros miembros del equipo revisan el código (Code Review).
  • Si se aprueba, se hace merge hacia la rama principal.

Este ciclo puede repetirse muchas veces al día, incluso en proyectos con decenas o cientos de colaboradores.

Evitar sobrescribir el trabajo de otros

Git y GitHub ayudan a evitar que las personas se pisen el trabajo entre sí:

  • Cada persona trabaja en su propia rama o Fork.
  • Los cambios se integran solo cuando se revisan y aprueban.
  • Si hay conflictos, se resuelven dentro del Pull Request.

Así, el repositorio principal se mantiene estable y las contribuciones se incorporan de forma controlada.

Ejemplo sencillo con el proyecto del libro

Imagina que el repositorio original del sitio web personal está en la cuenta de “Academia El Profe”. Un estudiante desea mejorar la página de recursos y otro quiere agregar un formulario de contacto.

En lugar de editar directamente main del repositorio original:

  • cada uno hace un Fork hacia su propia cuenta;
  • clona su Fork localmente;
  • crea una rama para su mejora;
  • abre un Pull Request al terminar;
  • un docente revisa y decide si integrar los cambios.

Nota

En GitHub, los Pull Requests y los Issues son herramientas centrales para coordinar trabajo entre varias personas. Son la base del flujo profesional en proyectos Open Source y en muchas empresas.

Breve conclusión: los equipos colaboran en GitHub usando copias independientes, ramas de trabajo y Pull Requests revisados, evitando sobrescribir el trabajo ajeno y manteniendo un repositorio principal estable.

8.2 ¿Qué es un Fork?

La documentación oficial de GitHub define los Forks como “copias independientes” de repositorios. A diferencia de un simple clon local, un Fork es otro repositorio en GitHub, asociado al original pero con identidad propia.

Fork vs Clone

Un Fork:

  • se crea en GitHub (no en tu equipo);
  • aparece como un repositorio nuevo en tu cuenta u organización;
  • mantiene un vínculo con el repositorio original, indicado como upstream;
  • puede enviar cambios de vuelta al original mediante Pull Requests.

Un Clone:

  • se crea en tu equipo local mediante git clone;
  • es una copia local de un repositorio (original o Fork);
  • no establece por sí mismo un vínculo especial con el upstream (más allá del remoto origin).
Característica Fork Clone
Dónde vive En GitHub, como repositorio propio. En tu equipo local
Cómo se crea Desde la interfaz web (botón Fork). Con git clone URL
Relación con el original Conserva referencia de upstream y permite Pull Requests. Solo conoce el remoto del que fue clonado
Uso típico Contribuir a proyectos de terceros sin escribir directamente en el original Trabajar localmente con cualquier repositorio

Cuándo utilizar un Fork

Según GitHub Docs, un Fork puede ser mejor opción que una rama cuando:

  • quieres experimentar de forma segura sin afectar el proyecto original;
  • deseas tener tu propio espacio de discusiones, Issues y Pull Requests relacionados con tu trabajo;
  • podrías querer convertir tu trabajo en un repositorio independiente más adelante.

En muchos proyectos Open Source, el flujo por defecto para contribuciones externas es:

  1. Fork del repositorio original.
  2. Clone del Fork en local.
  3. Rama de trabajo en el Fork.
  4. Pull Request desde el Fork al repositorio original.

Repositorio original vs copia personal

En este capítulo:

  • El repositorio original será el del proyecto del libro en la cuenta “Academia El Profe”.
  • Tu Fork será la copia en tu cuenta personal.

Trabajarás como si fueras colaborador externo, aportando cambios a través de tu Fork.

[Ilustración: vista de GitHub mostrando un repositorio original y debajo la indicación “forked from Academia-El-Profe/proyecto-libro”, con flecha visual que indica que el Fork es una copia independiente pero enlazada al upstream]

Curiosidad

GitHub destaca que los Forks son la base de muchas comunidades Open Source: permiten que cualquier persona experimente y proponga cambios sin necesidad de recibir acceso directo de escritura al repositorio original.3

Breve conclusión: un Fork es una copia independiente de un repositorio en tu cuenta, vinculada al original por la relación upstream y preparada para enviar cambios mediante Pull Requests.

8.3 Clonando nuestro Fork

Una vez creado el Fork en tu cuenta, el siguiente paso es clonar ese Fork en tu equipo local para trabajar sobre él con Git.

Crear el Fork en GitHub

Desde el repositorio original del proyecto del libro:

  1. En GitHub, haz clic en el botón Fork.
  2. Elige tu cuenta personal como destino.
  3. Espera a que GitHub cree el nuevo repositorio.

Ahora verás un repositorio en tu cuenta, por ejemplo tu-usuario/sitio-web-personal, con la indicación de que es un Fork del repositorio original.

Clonar el Fork

La documentación general de GitHub explica que puedes clonar cualquier repositorio (incluyendo Forks) para obtener una copia local y sincronizar entre ambas ubicaciones.

  1. Ve a tu Fork en GitHub.
  2. Pulsa el botón Code.
  3. Copia la URL HTTPS.
  4. En tu equipo, ejecuta:
git clone https://github.com/tu-usuario/sitio-web-personal.git
  1. Entra en la carpeta clonada:
cd sitio-web-personal

Desde este momento, tu repositorio local está conectado al Fork (remoto origin apunta al Fork, no al repositorio original).

Flujo completo: Fork → Clone

flowchart LR
    A[Repositorio original en Academia El Profe] --> B[Fork en tu cuenta]
    B --> C[git clone tu Fork en local]
    C --> D[Trabajo diario sobre el Fork local]

Este diagrama resume la arquitectura: el original vive en la cuenta de la academia, tu Fork vive en tu cuenta y tu clon local vive en tu equipo.

Nota

Cuando clonas tu Fork, el remoto origin apunta a tu Fork, no al repositorio original. Para sincronizar con el original necesitarás configurar un remoto adicional llamado upstream.1

Breve conclusión: clonar el Fork te da un repositorio local conectado a tu copia personal en GitHub. Desde ahí podrás crear ramas, hacer commits y enviar cambios mediante Push y Pull Requests.

8.4 Manteniendo actualizado el Fork

Con el tiempo, el repositorio original puede seguir avanzando: nuevos commits, nuevas funcionalidades, correcciones. Para que tu Fork no se quede atrás, GitHub Docs indica que debes configurar un remoto upstream que apunte al repositorio original y sincronizar regularmente.

Configurar el remoto upstream

Desde tu clon local del Fork, ejecuta:

git remote -v

Verás algo como:

origin  https://github.com/tu-usuario/sitio-web-personal.git (fetch)
origin  https://github.com/tu-usuario/sitio-web-personal.git (push)

Para añadir el remoto upstream que apunte al repositorio original:

git remote add upstream https://github.com/Academia-El-Profe/sitio-web-personal.git

Vuelve a verificar:

git remote -v

Ahora deberías ver:

origin   https://github.com/tu-usuario/sitio-web-personal.git (fetch)
origin   https://github.com/tu-usuario/sitio-web-personal.git (push)
upstream https://github.com/Academia-El-Profe/sitio-web-personal.git (fetch)
upstream https://github.com/Academia-El-Profe/sitio-web-personal.git (push)

Sincronizar el Fork con upstream

La página “Syncing a fork” describe el flujo desde la línea de comandos:

  1. Traer cambios desde upstream:
git fetch upstream

Esto descarga los commits y ramas del repositorio original. Por ejemplo:

From https://github.com/Academia-El-Profe/sitio-web-personal
 * [new branch]      main     -> upstream/main
  1. Cambiar a tu rama principal local (por ejemplo, main):
git checkout main
  1. Fusionar los cambios de upstream/main en tu main local:
git merge upstream/main

Según GitHub Docs, si no tienes commits únicos en tu main local, Git hará un fast-forward. Si tienes cambios propios, puede que debas resolver conflictos.

  1. Finalmente, puedes publicar los cambios sincronizados en tu Fork remoto:
git push origin main

Qué sucede internamente

  • fetch upstream trae la historia del repositorio original a tu clon local.
  • merge upstream/main combina esos cambios con tu rama local.
  • push origin main actualiza tu Fork en GitHub.

Así, tu Fork se mantiene alineado con el repositorio original sin perder tus propias contribuciones.

Diagrama: sincronización de Fork

flowchart TD
    A[Fork local conectado a origin] --> B[Configurar remoto upstream]
    B --> C[git fetch upstream]
    C --> D[git checkout main]
    D --> E[git merge upstream/main]
    E --> F[git push origin main]

Buenas prácticas

Sincroniza tu Fork con el repositorio original antes de comenzar una nueva funcionalidad importante. Eso reduce la probabilidad de conflictos grandes al final.

Error común

Trabajar semanas sobre un Fork sin sincronizar y descubrir al final que el repositorio original cambió mucho. Esto complica los merges y aumenta los conflictos.

Breve conclusión: mantener actualizado tu Fork requiere configurar un remoto upstream, hacer fetch y merge periódicamente y publicar esos cambios en tu Fork remoto. Así trabajas siempre sobre una base cercana al repositorio original.

8.5 Pull Request

Los Pull Requests son la herramienta central de colaboración en GitHub. GitHub Docs los define como la forma de proponer cambios en un repositorio y solicitar que alguien los revise antes de integrarlos.2

Qué es un Pull Request

Un Pull Request:

  • compara una rama de origen (por ejemplo, una rama en tu Fork) con una rama base (por ejemplo, main en el repositorio original);
  • muestra los commits y diferencias de archivos entre ambas ramas;
  • permite discutir esos cambios mediante comentarios;
  • puede requerir aprobación antes de hacer merge.

Cuándo crear uno

Deberías crear un Pull Request cuando:

  • has terminado una funcionalidad o corrección en una rama de tu Fork;
  • deseas que los propietarios del repositorio original revisen tu propuesta;
  • quieres que tus cambios se integren a la rama principal del proyecto original.

Descripción y contexto

Al crear un Pull Request, GitHub te pide:

  • título descriptivo;
  • descripción detallada (qué se hizo y por qué);
  • referencia a Issues relacionados (si existen);
  • cualquier información necesaria para revisar.

Un buen Pull Request no es solo “código nuevo”, sino también una explicación clara que facilite la revisión.

Comparación de cambios

La interfaz de GitHub muestra:

  • la lista de commits incluidos;
  • los archivos modificados;
  • un diff entre la rama base y la rama comparada.

Esto permite a los revisores entender el impacto del cambio antes de decidir.

Revisión y estado

Los Pull Requests pueden tener estados como:

  • abierto;
  • aprobado (con revisiones positivas);
  • cambios solicitados;
  • mergeado;
  • cerrado sin merge.
Estado Significado
Open Propuesta en revisión
Approved Revisores consideran que puede integrarse.
Changes requested Se requieren ajustes antes de aprobar.
Merged Cambios integrados al repositorio base
Closed Pull Request cerrado sin merge

[Ilustración: interfaz de GitHub mostrando la pantalla de un Pull Request con título, descripción, pestañas de Commits y Files changed, botones de Comment, Approve, Request changes y un botón de Merge]

Consejo

Crea Pull Requests pequeños y bien descritos. Son más fáciles de revisar, generan menos conflictos y mejoran la calidad del código.

Breve conclusión: un Pull Request es la forma profesional de proponer cambios a un repositorio, acompañados de contexto y sujetos a revisión antes del merge.

8.6 Code Review

El Code Review es el proceso mediante el cual otra persona (o varias) revisa tu Pull Request, comenta sobre el código y decide si aprobarlo o pedir cambios. GitHub Docs describe las revisiones como uno de los mecanismos principales de colaboración en la plataforma.

Revisión de código

En un Pull Request, los revisores pueden:

  • comentar sobre líneas específicas del código;
  • dejar comentarios generales sobre el cambio;
  • aprobar el Pull Request;
  • solicitar cambios.

Esto convierte cada aporte en una conversación técnica, no solo en un cambio silencioso.

Comentarios y solicitudes de cambios

Los comentarios pueden:

  • señalar problemas de lógica o estilo;
  • sugerir mejoras;
  • pedir aclaraciones.

Cuando un revisor usa “Request changes”, el Pull Request queda marcado como pendiente de ajustes. Una vez que actualizas la rama (por ejemplo, haciendo nuevos commits), se puede revisar de nuevo y eventualmente aprobar.

Aprobación

En algunos repositorios, los administradores pueden requerir que todo Pull Request tenga cierto número de revisiones aprobadas antes de permitir el merge.

Aprobar un Pull Request indica que el código fue revisado y que los cambios son aceptables para integrarse al proyecto.

Ejemplo aplicado al proyecto del libro

Supón que creas una nueva sección “Recursos avanzados” en tu Fork y abres un Pull Request hacia el repositorio original.

Como revisor (rol de docente o mantenedor):

  1. Lees la descripción.
  2. Revisas los archivos modificados.
  3. Haces comentarios sobre el contenido de recursos.html.
  4. Pides un ajuste de texto en un párrafo.
  5. El colaborador actualiza el Pull Request con un nuevo commit.
  6. Finalmente, apruebas el Pull Request y haces merge.

[Ilustración: vista de GitHub donde un Pull Request muestra comentarios en línea sobre el código, un resumen de la revisión y el estado “Approved”, resaltando el proceso de Code Review]

Buenas prácticas

El Code Review no es solo para buscar errores. También sirve para compartir conocimiento, mejorar el diseño del código y mantener estilo y calidad consistentes.

Breve conclusión: el Code Review convierte cada Pull Request en una oportunidad de mejora colectiva. Comentarios, solicitudes de cambios y aprobaciones forman parte del flujo normal de colaboración en GitHub.

8.7 Issues

Además de código y Pull Requests, GitHub ofrece Issues como herramienta para gestionar tareas, errores y mejoras. GitHub Docs los presenta como elementos clave para organizar el trabajo de un repositorio.

Registrar tareas, errores y mejoras

Un Issue puede representar:

  • una tarea pendiente (por ejemplo, “Agregar sección de preguntas frecuentes”);
  • un error detectado en el sitio (“El enlace a recursos no funciona en móviles”);
  • una mejora (“Mejorar diseño del formulario de contacto”).

Cada Issue tiene:

  • título;
  • descripción detallada;
  • comentarios;
  • etiquetas;
  • estado (abierto o cerrado);
  • asignación a personas.

Asignación y etiquetas

Puedes asignar Issues a colaboradores específicos y usar etiquetas como:

  • bug para errores;

  • enhancement para mejoras;

  • documentation para temas de contenido;
  • etiquetas personalizadas para tu proyecto.

Esto ayuda a agrupar y priorizar el trabajo.

Estados

Un Issue puede estar:

  • Open: pendiente de resolución;
  • Closed: resuelto o descartado.

A menudo, el cierre de un Issue se hace cuando un Pull Request que resuelve ese issue es mergeado.

Ejemplo aplicado al proyecto del libro

En el repositorio del sitio web personal puedes crear Issues como:

  • Agregar sección de testimonios de estudiantes (enhancement).
  • Corregir error en enlace de contacto (bug).
  • Actualizar README con instrucciones de despliegue (documentation).

Cada Issue puede luego vincularse a ramas y Pull Requests que implementan la solución.

[Ilustración: pantalla de Issues en GitHub mostrando una lista de tareas con título, etiquetas de tipo (bug, enhancement), asignación a usuarios y estado Open/Closed]

Error común

Usar Issues solo como lista de problemas técnicos y olvidarse de registrar mejoras y tareas de contenido. Un buen uso de Issues refleja todas las dimensiones del proyecto.

Breve conclusión: los Issues permiten organizar el trabajo en torno a tareas, errores y mejoras, asignándolos a personas, etiquetándolos y vinculándolos con Pull Requests.

8.8 Flujo profesional de colaboración

Con todos los elementos vistos, puedes construir un flujo completo de colaboración con GitHub, similar al utilizado en proyectos Open Source y equipos profesionales.

El flujo resumido es:

Repositorio Original

↓

Fork

↓

Clone

↓

Nueva Branch

↓

Desarrollo

↓

Commit

↓

Push

↓

Pull Request

↓

Code Review

↓

Merge

Paso a paso aplicado al proyecto del libro

  1. Repositorio Original: El sitio web personal vive en el repositorio principal de “Academia El Profe”.
  2. Fork: Desde tu cuenta personal, haces un Fork del repositorio original.
  3. Clone: Clonas el Fork en tu equipo usando git clone.
  4. Nueva Branch: Creas una rama para la mejora específica (por ejemplo, mejora-recursos).
  5. Desarrollo: Implementas la mejora en la rama, haciendo commits pequeños y claros.
  6. Commit: Cada porción de trabajo lógico se registra en un commit.
  7. Push: Publicas la rama en tu Fork remoto.
  8. Pull Request: Desde GitHub, abres un Pull Request desde tu rama en el Fork hacia main del repositorio original.
  9. Code Review: Un revisor (docente o mantenedor) analiza los cambios, comenta y aprueba o pide ajustes.
  10. Merge: Una vez aprobado, el Pull Request se mergea y tu mejora se incorpora al repositorio original.

Diagrama: flujo Fork → Pull Request

flowchart LR
    A[Repositorio original] --> B[Fork en tu cuenta]
    B --> C[Clone del Fork en local]
    C --> D[Nueva branch de mejora]
    D --> E[Commits de desarrollo]
    E --> F[Push al Fork]
    F --> G[Pull Request hacia original]
    G --> H[Code Review]
    H --> I[Merge en repositorio original]

Roles en el flujo

Rol Responsabilidades principales
Propietario Mantener el repositorio original, revisar y mergear Pull Requests
Colaborador Crear Fork, desarrollar mejoras, abrir Pull Requests
Revisor Leer código, comentar, aprobar o pedir cambios

¿Sabías que...?

GitHub describe las revisiones de Pull Requests como “una de las formas principales de colaboración” en la plataforma, justamente porque permiten que personas con distintos permisos interactúen sobre el mismo proyecto.

Breve conclusión: el flujo profesional de colaboración con GitHub se basa en Forks, ramas, Pull Requests, Code Review e Issues, alineando el trabajo de propietarios, colaboradores y revisores alrededor de un repositorio original.

Práctica guiada

En esta práctica vas a simular un flujo completo de colaboración usando tu proyecto del libro y un repositorio original adicional.

Paso 1: crear un Fork

  1. Desde el repositorio original del sitio web personal, haz clic en Fork.
  2. Crea el Fork en tu cuenta personal.

Paso 2: clonar el Fork

  1. En tu Fork, copia la URL desde el botón Code.
  2. En tu equipo, ejecuta:
git clone https://github.com/tu-usuario/sitio-web-personal.git
cd sitio-web-personal

Paso 3: configurar el repositorio Upstream

  1. Añade el remoto upstream apuntando al repositorio original:
git remote add upstream https://github.com/Academia-El-Profe/sitio-web-personal.git
  1. Verifica con git remote -v que origin apunta a tu Fork y upstream al original.

Paso 4: crear una nueva rama

  1. Asegúrate de estar en main:
git checkout main
  1. Crea una rama para tu mejora:
git switch -c mejora-recursos

Paso 5: implementar una mejora al proyecto

  1. Edita recursos.html o crea una nueva sección educativa.
  2. Ajusta estilos o contenido en index.html para enlazarla.
  3. Haz commits pequeños y descriptivos.

Paso 6: Push de la rama al Fork

  1. Publica la rama en tu Fork remoto:
git push origin mejora-recursos

Paso 7: crear un Pull Request

  1. En GitHub, ve a tu Fork.
  2. GitHub detectará la rama nueva y te sugerirá crear un Pull Request.
  3. Abre un Pull Request desde tu-usuario:mejora-recursos hacia Academia-El-Profe:main.
  4. Escribe un título y descripción claros.

Paso 8: simular una revisión de código

  1. Cambia mentalmente de rol a revisor.
  2. Revisa los archivos modificados en la pestaña Files changed.
  3. Añade comentarios, por ejemplo señalando una mejora de texto.
  4. Simula “Request changes” si ves algo que ajustar.
  5. Actualiza la rama local con un nuevo commit que atienda los comentarios.
  6. Haz git push origin mejora-recursos de nuevo.

Paso 9: aprobar y completar el Merge

  1. Como revisor, cambia el estado del Pull Request a “Approve”.
  2. Usa el botón de Merge para integrar los cambios al repositorio original.
  3. Verifica que main del repositorio original incluye ahora tu mejora.

Paso 10: crear Issues relacionados

  1. En el repositorio original, abre la pestaña Issues.

  2. Crea algunos Issues, por ejemplo:

  3. Agregar sección de preguntas frecuentes.

  4. Mejorar accesibilidad del sitio (contrastes, etiquetas).

  5. Asigna los Issues a roles simulados (por ejemplo, a tu usuario) y etiqueta según el tipo.

Diagrama de la práctica completa

flowchart TD
    A[Repositorio original] --> B[Fork en tu cuenta]
    B --> C[Clone local]
    C --> D[Configurar upstream]
    D --> E[Crear rama de mejora]
    E --> F[Commits y push al Fork]
    F --> G[Pull Request hacia original]
    G --> H[Code Review y ajustes]
    H --> I[Merge aprobado]
    I --> J[Crear Issues para nuevas tareas]

[Ilustración: secuencia visual con tres pantallas de GitHub: repositorio original, Fork con rama de mejora y pantalla de Pull Request mostrando comentarios y botón de Merge, junto con la pestaña de Issues con tareas relacionadas]

Buenas prácticas

Usa Issues para organizar qué mejoras vas a hacer y Pull Requests para implementar cada una. Esta combinación refleja muy bien el flujo profesional en equipos reales.

Breve conclusión: la práctica guiada te permite vivir el flujo completo de colaboración: Fork, Clone, upstream, ramas, Pull Requests, Code Review e Issues, todo aplicado al mismo proyecto del libro.

Cierre del capítulo

En este capítulo viste cómo GitHub se convierte en el espacio donde equipos y comunidades coordinan trabajo: Forks para copias independientes, clones locales para desarrollo, remotos origin y upstream para sincronización, Pull Requests para proponer y discutir cambios, Code Review para asegurar calidad e Issues para organizar tareas.

Aplicando todo esto al proyecto del libro, te acercaste al flujo profesional usado en proyectos Open Source y empresas: nadie modifica directamente el código principal sin contexto, sino que cada aporte pasa por ramas, Forks, Pull Requests y revisiones. A partir de aquí, estás preparado para participar de manera ordenada y efectiva en repositorios colaborativos reales.

Notas al pie

Para profundizar

  1. Syncing a fork - GitHub Docs. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork ↩

  2. Reviewing changes in pull requests - GitHub Docs. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests ↩

  3. About forks - GitHub Docs. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks ↩