Añadidos arhcivos basicos de repos
This commit is contained in:
@@ -0,0 +1,380 @@
|
||||
---
|
||||
version: 2.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [git, workflow, trunk-based, integration]
|
||||
---
|
||||
|
||||
# Command: git-push
|
||||
|
||||
Integra cambios a master y publica. Soporta ramas `issue/*` y `quick/*`.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando hayas terminado de trabajar en una rama temporal (issue/* o quick/*) y quieras integrar los cambios a master y publicar al remoto.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/git:push
|
||||
```
|
||||
|
||||
No requiere argumentos. Detecta automáticamente la rama actual y maneja el flujo completo.
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Desde rama issue**
|
||||
```bash
|
||||
# Estando en issue/0013-hot-reload
|
||||
/git:push
|
||||
```
|
||||
|
||||
Crea commits atómicos, ejecuta tests, merge a master, push y limpia rama local.
|
||||
|
||||
**Ejemplo 2: Desde master con cambios**
|
||||
```bash
|
||||
# Estando en master con cambios pendientes
|
||||
/git:push
|
||||
```
|
||||
|
||||
Detecta cambios, crea automáticamente rama `quick/<slug>`, y ejecuta flujo completo.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Repositorio es un repo git válido
|
||||
- [ ] Hay cambios para commitear O estamos en una rama temporal
|
||||
- [ ] Tests del proyecto disponibles (si aplica)
|
||||
|
||||
### Inputs
|
||||
|
||||
No requiere inputs del usuario. El comando detecta automáticamente:
|
||||
- Rama actual (master, issue/*, quick/*)
|
||||
- Cambios pendientes (staged, unstaged)
|
||||
- Archivos modificados
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Verificar rama actual y estado
|
||||
|
||||
```bash
|
||||
git branch --show-current
|
||||
git status --short
|
||||
```
|
||||
|
||||
##### Caso A: Estamos en rama `issue/*` o `quick/*`
|
||||
|
||||
✓ Continuar directamente al paso 2.
|
||||
|
||||
##### Caso B: Estamos en `master` con cambios pendientes
|
||||
|
||||
**Crear rama quick automáticamente antes de continuar:**
|
||||
|
||||
1. Detectar contexto automáticamente:
|
||||
|
||||
```bash
|
||||
git diff --name-only
|
||||
git diff --name-only --cached
|
||||
```
|
||||
|
||||
2. Analizar archivos para generar slug descriptivo:
|
||||
- Cambios en `README.md` → `update-readme`
|
||||
- Cambios en `.claude/` → `update-claude-config`
|
||||
- Cambios en `feature_flags.json` → `update-flags`
|
||||
- Cambios en `dev/issues/` → `update-issues`
|
||||
- Cambios en archivos de código → usar nombre del archivo principal
|
||||
- Cambios múltiples sin patrón claro → `misc-updates`
|
||||
|
||||
3. Crear rama quick automáticamente:
|
||||
|
||||
```bash
|
||||
git checkout -b quick/<slug-generado>
|
||||
```
|
||||
|
||||
4. Mostrar mensaje informativo:
|
||||
```
|
||||
✓ Creada rama automática: quick/<slug-generado>
|
||||
|
||||
Si estos cambios son parte de un issue, cancela (Ctrl+C) y usa:
|
||||
/factory:fix-issue <NNNN>
|
||||
```
|
||||
|
||||
5. Continuar al paso 2.
|
||||
|
||||
**IMPORTANTE:**
|
||||
- Por defecto siempre crear rama `quick/`
|
||||
- Solo usar `issue/` cuando se invoque desde `/factory:fix-issue` o el usuario indique explícitamente
|
||||
- No inventar números de issue
|
||||
- El objetivo es reducir fricción: si no sabes qué es, es un cambio quick
|
||||
|
||||
##### Caso C: Estamos en `master` sin cambios
|
||||
|
||||
✗ Error: No hay nada que publicar
|
||||
|
||||
**STOP**
|
||||
|
||||
#### 2. Revisar cambios y crear commits por bloque
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git diff --stat
|
||||
git diff
|
||||
```
|
||||
|
||||
Analizar los cambios y agruparlos en **bloques lógicos**. Cada bloque debe tener la misma naturaleza/propósito.
|
||||
|
||||
**Tipos de bloques comunes:**
|
||||
- Nuevas funcionalidades (feat)
|
||||
- Correcciones de bugs (fix)
|
||||
- Tests (test)
|
||||
- Documentación (docs)
|
||||
- Refactoring (refactor)
|
||||
- Configuración/mantenimiento (chore)
|
||||
|
||||
**Crear commits atómicos por bloque:**
|
||||
|
||||
```bash
|
||||
git add <archivos_del_bloque_1>
|
||||
git commit -m "<tipo>: <resumen breve>" -m "<descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque>"
|
||||
|
||||
git add <archivos_del_bloque_2>
|
||||
git commit -m "<tipo>: <resumen breve>" -m "<descripción larga en español>"
|
||||
```
|
||||
|
||||
**Convención de tipos:**
|
||||
- `feat:` nueva funcionalidad
|
||||
- `fix:` corrección de error
|
||||
- `refactor:` cambio estructural sin cambio funcional
|
||||
- `docs:` documentación
|
||||
- `chore:` mantenimiento, config, deps
|
||||
- `test:` tests nuevos o modificados
|
||||
|
||||
**Reglas críticas de commits:**
|
||||
- **No WIP**: nunca commitear "wip", "tmp", "fix fix" ni código a medias
|
||||
- **No mezclar tipos**: no combinar `feat:` + `test:` en un mismo commit
|
||||
- **No squash**: los commits individuales se preservan en master via `--no-ff`
|
||||
- **No rebase interactivo**: si los commits ya son limpios, no reescribir historia
|
||||
- **Descripción larga obligatoria**: cada commit debe tener cuerpo explicativo en español
|
||||
|
||||
#### 3. Ejecutar tests
|
||||
|
||||
{{include: run-tests}}
|
||||
|
||||
**Obligatorio antes de mergear:**
|
||||
|
||||
```bash
|
||||
go test -tags goolm ./...
|
||||
```
|
||||
|
||||
**Casos:**
|
||||
- Tests **pasan** → ✓ Continuar al paso 4
|
||||
- Tests **fallan** → ✗ **STOP**: corregir antes de continuar. No mergear código roto.
|
||||
- No hay tests aplicables (solo docs/config) → ℹ Indicar al usuario y continuar al paso 4
|
||||
|
||||
#### 4. Evaluar feature flags
|
||||
|
||||
Feature flags se usan cuando el issue es **parte de una feature multi-issue** o el cambio tiene riesgo y necesita poder desactivarse.
|
||||
|
||||
**Feature flag ≠ WIP** — un flag protege código terminado y testeado, no código a medias.
|
||||
|
||||
**Si se modificó `dev/feature_flags.json` o cambios son parte de feature multi-fase:**
|
||||
|
||||
1. Verificar que `dev/feature_flags.json` existe y está actualizado
|
||||
2. Confirmar que el flag correspondiente tiene el estado correcto (`enabled: true/false`)
|
||||
3. Incluir el archivo en el commit correspondiente (no crear commit separado solo para flags)
|
||||
|
||||
**Si el issue es autocontenido** (se completa en esta rama):
|
||||
- No necesita flag
|
||||
- ✓ Saltar este paso
|
||||
|
||||
#### 5. Merge a master con --no-ff
|
||||
|
||||
{{include: git-merge-to-master}}
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
git merge --no-ff <rama> -m "merge: <rama> — <título breve>"
|
||||
```
|
||||
|
||||
**Formato del mensaje de merge:**
|
||||
- Título: `merge: <rama> — <descripción corta>`
|
||||
- Cuerpo (opcional): resumen de lo que entra
|
||||
|
||||
**Ejemplos:**
|
||||
```
|
||||
merge: issue/0021-threads-default-config — habilitar threads en agentes
|
||||
merge: quick/fix-typo-readme — corregir typo en README
|
||||
```
|
||||
|
||||
**Si hay conflictos durante el merge:**
|
||||
1. Resolver los conflictos manualmente
|
||||
2. `git add` los archivos resueltos
|
||||
3. `git commit` (sin -m, para mantener el mensaje de merge)
|
||||
|
||||
#### 6. Push a remoto
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**Si falla el push:**
|
||||
- Error "rejected - non-fast-forward" → alguien pusheó a master antes
|
||||
- Solución: `git pull --rebase && git push`
|
||||
|
||||
#### 7. Limpiar rama local
|
||||
|
||||
```bash
|
||||
git branch -d <rama>
|
||||
```
|
||||
|
||||
**Si el branch delete falla:**
|
||||
- `-d` falla si la rama no está mergeada
|
||||
- Usar `-D` solo si estás seguro que el merge se completó correctamente
|
||||
|
||||
### Verificación final
|
||||
|
||||
```bash
|
||||
git log --oneline -3
|
||||
git branch --list
|
||||
```
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Rama `<rama>` integrada a master y publicada
|
||||
|
||||
Commits creados:
|
||||
- <commit 1>
|
||||
- <commit 2>
|
||||
- merge: <rama>
|
||||
|
||||
Rama local eliminada.
|
||||
Master actualizado y sincronizado con remoto.
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Commits atómicos**: un commit = un cambio lógico completo
|
||||
- **Mensajes descriptivos**: título corto + cuerpo explicativo en español
|
||||
- **No mezclar tipos**: feat, fix, test, docs cada uno en su commit
|
||||
- **Tests obligatorios**: siempre ejecutar antes de merge
|
||||
- **Merge --no-ff**: preservar historia de la rama
|
||||
- **Push inmediato**: integrar y publicar en un solo flujo
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "nothing to commit, working tree clean"
|
||||
|
||||
**Causa:** No hay cambios pendientes para commitear.
|
||||
|
||||
**Solución:**
|
||||
Si estás en una rama temporal y todos los cambios ya están commiteados, continúa con el merge. Si estás en master sin cambios, no hay nada que hacer.
|
||||
|
||||
### Error: "Tests failing"
|
||||
|
||||
**Causa:** Los tests no pasan.
|
||||
|
||||
**Solución:**
|
||||
1. Ver detalles de los tests fallidos:
|
||||
```bash
|
||||
go test -v -tags goolm ./...
|
||||
```
|
||||
|
||||
2. Corregir el código que causa el fallo
|
||||
3. Re-ejecutar tests hasta que pasen
|
||||
4. Crear commit con el fix si es necesario
|
||||
5. Continuar con el merge
|
||||
|
||||
### Error: "merge conflict in <archivo>"
|
||||
|
||||
**Causa:** El archivo tiene cambios en master que conflictúan con tu rama.
|
||||
|
||||
**Solución:**
|
||||
1. Ver conflictos:
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
2. Abrir archivo y resolver marcadores de conflicto:
|
||||
```
|
||||
<<<<<<< HEAD
|
||||
código en master
|
||||
=======
|
||||
tu código
|
||||
>>>>>>> rama
|
||||
```
|
||||
|
||||
3. Editar y dejar solo la versión correcta
|
||||
|
||||
4. Stagear archivo resuelto:
|
||||
```bash
|
||||
git add <archivo>
|
||||
```
|
||||
|
||||
5. Completar merge:
|
||||
```bash
|
||||
git commit
|
||||
```
|
||||
|
||||
### Error: "branch -d <rama> failed"
|
||||
|
||||
**Causa:** Git detecta que la rama no está completamente mergeada.
|
||||
|
||||
**Solución:**
|
||||
1. Verificar si el merge se completó correctamente:
|
||||
```bash
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
2. Si el merge commit está presente, forzar eliminación:
|
||||
```bash
|
||||
git branch -D <rama>
|
||||
```
|
||||
|
||||
3. Si el merge no se completó, volver atrás y resolver el problema.
|
||||
|
||||
### Error: "rejected - non-fast-forward"
|
||||
|
||||
**Causa:** Alguien más pusheó cambios a master mientras trabajabas.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git pull --rebase
|
||||
git push
|
||||
```
|
||||
|
||||
Si hay conflictos durante el rebase, resolverlos y continuar:
|
||||
```bash
|
||||
# Resolver conflictos
|
||||
git add <archivos-resueltos>
|
||||
git rebase --continue
|
||||
git push
|
||||
```
|
||||
|
||||
### Advertencia: "Detached HEAD state"
|
||||
|
||||
**Causa:** No estás en ninguna rama.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git checkout master
|
||||
# O crear rama si tienes cambios importantes
|
||||
git checkout -b quick/rescue-changes
|
||||
```
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **NO hacer commits WIP** - cada commit debe ser atómico y completo
|
||||
- **NO mezclar tipos** en un commit (feat + test en commits separados)
|
||||
- **NO saltear tests** - si fallan, arreglar antes de merge
|
||||
- **NO hacer push --force** a master nunca
|
||||
- **NO hacer squash** - preservar commits individuales vía --no-ff
|
||||
- **SIEMPRE** escribir descripción larga en español en cada commit
|
||||
- **SIEMPRE** ejecutar tests antes de merge a master
|
||||
- **SIEMPRE** usar --no-ff para el merge
|
||||
- **SIEMPRE** limpiar rama local después del merge
|
||||
Reference in New Issue
Block a user