Control de versiones · GitHub

Colaborar en equipo

Git resuelve un problema técnico: guardar la historia de un proyecto. GitHub resuelve uno social: cómo se ponen de acuerdo varias personas sobre qué entra en esa historia. Son dos cosas distintas, y por eso esta parte no tiene simulador — no hay comandos que practicar, hay acuerdos que entender.

Casi todo lo que verás aquí no es una función de GitHub, es una convención. Un pull request no existe en git: es una rama, una comparación y una conversación encima. Si entiendes qué hay debajo, cambiar a GitLab, Gitea o Bitbucket es cuestión de aprender dónde están los botones.

Fork frente a clon

Se confunden constantemente porque las dos «traen» un repositorio, pero ocurren en sitios distintos. Un clon baja el repositorio a tu máquina. Un fork crea una copia bajo tu cuenta en el servidor, con su propia URL — y sobre esa copia sí tienes permiso de escritura.

	clon	fork
Dónde ocurre	En tu disco	En el servidor
Quién lo hace	Git, con un comando	GitHub, con un botón
Te da permiso de escritura	No cambia nada	Sí, sobre tu copia
Existe en git a secas	Sí	No, es de la plataforma

Lo normal es hacer las dos: forkeas para tener una copia tuya en GitHub, y clonas esa copia para trabajar en tu máquina.

El triángulo: tú, tu fork y el original

Cuando colaboras en un proyecto ajeno hay tres copias en juego, y confundirlas es el error clásico del primer día. Por convención se les da estos nombres:

tu máquina

Donde editas. Es un clon, y no lo ve nadie más.

origin

Tu fork en GitHub. Aquí sí puedes hacer push.

upstream

El repositorio original. Solo lees de él.

El trabajo circula en un sentido: bajas de upstream, subes a origin, y desde ahí abres el pull request que pide devolverlo al original.

Sincronizar un fork

Un fork no se actualiza solo. Mientras trabajas, el proyecto original sigue avanzando, y si tardas una semana tu copia está una semana atrasada. Eso es lo que produce esos pull requests llenos de conflictos que nadie quiere revisar.

// Una sola vez: declarar de dónde viene el proyecto

git remote add upstream https://github.com/original/proyecto.git

// Cada vez que vayas a empezar algo nuevo

git switch main
git fetch upstream
git merge upstream/main
git push origin main

Todos esos comandos ya los practicaste en el simulador. Lo único nuevo aquí es upstream, que no es más que un segundo remoto.

Una rama por trabajo

Nunca trabajes en main, ni siquiera en tu propio fork. Dos razones prácticas: tu main se mantiene idéntica al original y sincronizarla nunca da conflictos; y cada pull request queda acotado a un solo tema, que es lo que hace que alguien acepte revisarlo.

Regla práctica Si al describir tu rama tienes que usar la palabra «y», probablemente deberían ser dos ramas.

Los archivos que hacen legible un repositorio

README.md — qué es el proyecto, para qué sirve y cómo se pone en marcha. Es lo primero que GitHub muestra, y para la mayoría de la gente es lo único que va a leer.

LICENSE — qué puede hacer otra gente con tu código. Sin licencia, por omisión, nadie tiene permiso de nada: publicar no es lo mismo que autorizar.

CONTRIBUTING.md — cómo se aceptan aportes: estilo, pruebas, formato de los commits. Le ahorra al que llega la pregunta «¿y ahora qué hago?».

.gitignore — ya lo conoces del simulador. Aquí importa el doble: lo que se sube a un repositorio público, público queda.

Qué es un pull request, de verdad

Un pull request es una petición de fusionar una rama en otra. Eso es todo. No existe en git: el comando equivalente sería un git merge que alguien tiene que ejecutar por ti. Lo que aporta GitHub es lo de alrededor — la comparación visible, la conversación, y la posibilidad de exigir condiciones antes de dejar que ese merge ocurra.

Por qué el nombre confunde Se llama «pull request» porque le pides al dueño que haga pull de tu rama. GitLab lo llama «merge request», que describe mejor lo que pasa.

Base y compare

Todo pull request tiene dos ramas y el orden importa. La base es la que va a recibir los cambios; la compare es la que los trae. Invertirlas es un error frecuente y el resultado es un PR que propone meter main dentro de tu rama.

base ← recibe

Normalmente main del repositorio original.

compare → aporta

Tu rama, en tu fork. Es la que tiene el trabajo.

La revisión y sus tres veredictos

Approve — «por mí, adelante». En un repositorio con protección de ramas, esto es lo que desbloquea el botón de fusionar.

Request changes — «así no». El pull request queda bloqueado hasta que respondas y quien lo pidió vuelva a mirarlo.

Comment — observaciones sin veredicto. Sirve para preguntar o sugerir sin frenar a nadie.

Lo que se revisa Un buen comentario de revisión habla del código, no de quien lo escribió, y distingue lo que bloquea de lo que es una preferencia. «Esto peta si la lista viene vacía» y «yo lo habría escrito de otra forma» no son la misma categoría de comentario.

Borradores

Un pull request en borrador (draft) es visible pero no se puede fusionar y no pide revisión. Sirve para enseñar hacia dónde vas antes de terminar — para que nadie te diga al final que el enfoque estaba equivocado desde el principio.

Conflictos en un pull request

Cuando GitHub avisa de que hay conflictos, no está pasando nada nuevo: es el mismo conflicto que ya resolviste en el simulador, entre tu rama y la base. Ofrece un editor web para los casos triviales, pero lo habitual es resolverlo en local y subir la resolución — el pull request se actualiza solo.

// Traer la base a tu rama y resolver como siempre

git fetch upstream
git merge upstream/main
# resolver, git add, git commit
git push origin mi-rama

Las tres formas de fusionar

El botón de fusionar esconde tres opciones, y cada equipo elige una. No hay una correcta: hay un acuerdo sobre qué historial quieren leer dentro de un año.

Opción	Qué deja en el historial
Merge commit	Todos tus commits más uno de fusión. Conserva cómo trabajaste, a costa de ruido.
Squash	Un único commit con todo el trabajo. El historial queda limpio y se pierde el detalle.
Rebase	Tus commits reaplicados encima, sin commit de fusión. Línea recta, sin rastro de la rama.

Issues: la unidad de trabajo

Un issue es una conversación con estado: abierta o cerrada. Se usa para errores, para ideas, para preguntas y para tareas pendientes. La ventaja frente a un chat es que queda enlazado al código y no se pierde en el desplazamiento.

Un issue útil Qué esperabas, qué pasó, y cómo reproducirlo. Sin esas tres cosas, quien lo lea tendrá que preguntarlas — y ahí se van tres días.

Etiquetas, hitos y asignados

Tres formas distintas de ordenar lo mismo, y conviene no mezclarlas:

Etiquetas (labels) — clasifican: bug, documentación, buena primera tarea. Sirven para filtrar.

Hitos (milestones) — agrupan por entrega: todo lo que tiene que estar listo para la versión 2.0.

Asignados (assignees) — dicen quién se hace cargo. Un issue sin asignado no es de nadie.

Cerrar issues desde el código

Si en el mensaje de un commit o en la descripción de un pull request escribes una palabra clave seguida del número, GitHub cierra el issue automáticamente al fusionar. Es lo que mantiene sincronizados el código y el tablero sin que nadie tenga que acordarse.

git commit -m "Validar el rango del pool antes de guardarlo

Closes #42"

Funcionan también Fixes y Resolves. Y ojo: el issue se cierra al fusionar el pull request, no al hacer el commit.

Projects

Un tablero que muestra issues y pull requests en columnas — pendiente, en curso, hecho. No añade información nueva: es otra vista de lo que ya existe. Su valor es que la columna se actualiza sola cuando el pull request se fusiona.

La carpeta .github

Un directorio normal, versionado como cualquier otro, del que GitHub lee su configuración. No confundir con .git, que es la memoria del repositorio y no se toca a mano.

.github/workflows/ — los flujos de GitHub Actions.

.github/ISSUE_TEMPLATE/ — plantillas para que los issues lleguen con la información necesaria.

.github/PULL_REQUEST_TEMPLATE.md — la lista de comprobación que ve quien abre un PR.

.github/CODEOWNERS — quién revisa qué.

Protección de ramas

Una regla que le dice al servidor que rechace ciertos empujes sobre una rama. Es lo que convierte «deberíamos revisar el código» en algo que de verdad ocurre, porque deja de depender de la disciplina de cada uno.

• Prohibir el push directo — todo entra por pull request, sin excepciones.

• Exigir aprobaciones — una o más revisiones antes de poder fusionar.

• Exigir que el CI pase — si las pruebas fallan, el botón no se activa.

• Prohibir el force push — nadie reescribe la historia publicada.

Por qué importa Aquí se cierra el círculo con lo que viste en el simulador: reset y --force reescriben el historial. Sobre una rama compartida eso rompe el trabajo de los demás, y la protección de ramas es la que lo impide de verdad.

Anatomía de un workflow

GitHub Actions ejecuta comandos en una máquina que GitHub levanta para ti. Un workflow es un archivo YAML en .github/workflows/ que responde a un evento y contiene jobs, y cada job una lista de pasos.

// .github/workflows/pruebas.yml

name: pruebas

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: php tools/validar-academia.php

Se lee de arriba abajo: on dice cuándo, runs-on dice dónde, y steps dice qué. Un paso es una acción reutilizable (uses) o un comando de shell (run).

El CI como puerta

Integración continua significa que cada cambio se comprueba automáticamente antes de entrar. El workflow corre en cada pull request y devuelve un tick verde o una cruz roja; con la rama protegida, la cruz roja impide fusionar.

Es el mismo papel que cumplen los validadores de este proyecto: nadie se acuerda de ejecutarlos siempre, así que se ejecutan solos.

Secrets

Valores cifrados que se guardan en la configuración del repositorio y que el workflow recibe como variables de entorno. Existen porque el CI a veces necesita credenciales —desplegar, publicar un paquete— y esas credenciales no pueden estar en el código.

Recuerda del simulador Si una credencial llega a commitearse, agregarla a .gitignore después no sirve de nada: ya está en el historial, y el historial se clona entero. Lo único que arregla eso es rotar la credencial.

CODEOWNERS

Un archivo que asocia rutas con personas o equipos. Cuando un pull request toca una de esas rutas, GitHub pide su revisión automáticamente. Sirve para que nadie tenga que saber de memoria a quién avisar.

*                 @equipo/mantenimiento
/backend/         @equipo/backend
/docs/            @equipo/documentacion