Git, GitHub y entornos

El enlace 1:1 con producción solo se sostiene si los cambios entran siempre por el mismo camino: una rama, un pull request con comprobaciones y un merge decidido.

Vocabulario mínimo

Término	Qué es
Repositorio	La carpeta de un proyecto con todo su historial. Git guarda el historial; GitHub guarda una copia compartida.
Commit	Una foto de los cambios con un mensaje que explica qué cambia y por qué.
Rama	Una línea de commits paralela. Sirve para trabajar sin tocar lo que ya funciona.
main	La rama principal, la versión oficial. Las demás ramas nacen de ella y vuelven a ella.
Pull request (PR)	La petición, en GitHub, de juntar una rama con main. Muestra qué cambia y permite revisar y comprobar antes de aceptar.
Merge	Aceptar el PR: los commits de la rama pasan a main.
CI	Un robot (GitHub Actions) que ejecuta las comprobaciones en cada PR y marca el resultado en verde o en rojo.
Entorno	Una copia del producto que funciona por su cuenta, con su web, su base de datos y sus claves.
Producción	El entorno que usan los clientes.
Staging	Un entorno igual que producción, sin clientes y con datos de prueba. El ensayo general.
Preview	Un entorno temporal para un PR concreto, que desaparece al cerrarlo.
Promoción	Llevar a producción la misma versión que ya funcionó en staging.
Rollback	Volver a la versión anterior cuando la nueva falla.

Cómo entra un cambio

El flujo es GitHub Flow, igual en los tres repos:

1. Partir de main actualizada y crear una rama con un nombre que diga qué se hace.
2. Hacer commits pequeños. En un sistema, el mensaje nombra el id de la ficha (feat(ds): componentes/boton …).
3. Subir la rama y abrir un PR. La descripción responde a tres preguntas: qué cambia, por qué y cómo se ha probado (con los comandos ejecutados y su resultado).
4. Esperar a la CI y a la revisión. Si algo falla, más commits en la misma rama.
5. Hacer merge y borrar la rama.

git switch main && git pull
git switch -c componentes-boton-tamanos
# cambios…
git add . && git commit -m "feat(ds): componentes/boton documenta los tamaños"
git push -u origin componentes-boton-tamanos
gh pr create      # o desde la web de GitHub

Reglas:

• main siempre funciona. Nunca se trabaja directamente en ella.
• Un PR, un cambio. Una tanda de fichas puede ir en un PR; una tanda y un cambio de interfaz, no.
• Las ramas duran poco: horas o pocos días. Cuanto más dura una rama, más conflictos.

Los tres repos

	Kit	Sistema	Producción
Comprobaciones antes del merge	Tipos y build.	ds sync y ds check en verde.	Los tests del producto y, cuando haya CI, ds check del sistema.
Qué pasa al hacer merge	Nada se publica solo. Si cambia algo que usan los sistemas, se etiqueta una versión (ver «Kit y sistemas»).	Se publica el sistema, si está desplegado.	Se despliega: en producción si no hay staging; en staging si lo hay.
Quién hace merge	Quien mantiene el kit; un agente, si tiene autorización expresa y las comprobaciones pasan.	Igual que el kit.	Siempre una persona responsable del producto. Un agente abre el PR, pero no hace merge.

El merge en producción es distinto porque, sin staging, hacer merge es desplegar: el cambio llega a los clientes en minutos. Por eso esa decisión no se delega.

Reglas para agentes

• Una rama por tarea. Nunca commits en main.
• Antes de abrir un PR en un sistema: npx ds sync y npx ds check. El resultado va en la descripción.
• En producción, abrir el PR y parar. Si el checkout de producción tiene cambios sin commit de otra persona, no se tocan: se trabaja en una copia aparte del repo con git worktree add, que crea otra carpeta con su propia rama sobre el mismo historial.
• Si una comprobación falla, se arregla en la rama; no se desactiva la comprobación.

Entornos del producto y el sistema

Sin staging

Es la situación de partida de muchos productos: lo que entra en main sale a producción. Por eso el sistema vive en su propio repo (ver «Kit y sistemas»): documentar no puede romper el producto. Las huellas del sync detectan cualquier cambio de producción la próxima vez que se ejecute ds sync.

Con staging

Cuando el producto tiene staging y CI, el sistema se engancha a esa CI:

Rama + PR ──▶ CI: tests + ds check ──▶ merge: main → staging ──▶ probar ──▶ promoción → producción

1. ds check en cada PR de producción. La CI descarga el repo del sistema junto al de producción y ejecuta npx ds sync y npx ds check. Al principio solo avisa: la ficha desajustada se actualiza en un PR del sistema. Cuando las fichas estén completas, bloquea el merge.
2. Staging para revisar diseño en real. Los cambios de diseño se miran en staging, con datos de demo, antes de promocionar. Con previews por PR, la revisión de diseño y de textos se hace sobre el enlace del preview, antes del merge.
3. Iniciativas. Una pieza de una iniciativa llega a producción por el mismo camino: PR en producción, staging y promoción. Su ficha pasa de «En desarrollo» a «En producción» cuando la versión llega a producción, no al hacer merge en staging.

Decisiones escritas

La forma de trabajar de cada equipo (flujo de ramas, entornos, quién promociona) se decide una vez y se escribe en un registro de decisión (ADR): un archivo corto con contexto, decisión y consecuencias. Las decisiones propias del sistema van en su docs/DECISIONES.md.