workspace/projects/gamilit/docs/98-standards/GIT-CONVENTIONS.md

Git Conventions - GAMILIT

Tabla de Contenidos

• 1. Conventional Commits
• 2. Formato de Commit Message
• 3. Branch Naming
• 4. Pull Request Guidelines
• 5. Ejemplos Prácticos
• 6. Reglas del Proyecto
• 7. Buenas Prácticas

---

1. Conventional Commits

El proyecto GAMILIT sigue la especificación de Conventional Commits para mantener un historial de commits claro y semántico.

Tipos de Commit

Tipo	Descripción	Cuándo usar
feat	Nueva característica	Agregar nueva funcionalidad visible al usuario
fix	Corrección de bug	Solucionar un error o bug en el código
docs	Cambios de documentación	Modificar README, comentarios, ADRs, etc.
style	Cambios de formato	Formateo, espacios, punto y coma (sin cambio lógico)
refactor	Refactorización de código	Reestructurar código sin cambiar comportamiento
test	Agregar o modificar tests	Crear/actualizar pruebas unitarias o de integración
chore	Tareas de mantenimiento	Actualizar dependencias, configs, scripts de build
perf	Mejoras de rendimiento	Optimizaciones que mejoran el performance
ci	Cambios en CI/CD	Modificar pipelines, GitHub Actions, etc.
build	Cambios en build	Modificar configuración de compilación
revert	Revertir commit previo	Deshacer un commit anterior

---

2. Formato de Commit Message

Estructura Base

<type>(<scope>): <subject>

[body]

[footer]

Componentes

Type (requerido)

Uno de los tipos listados en la sección anterior.

Scope (opcional)

El scope indica el área del proyecto afectada. Ejemplos:

• backend, frontend, database
• auth, gamification, assignments
• api, ui, db, docs
• exercises, classrooms, notifications

Subject (requerido)

• Máximo 50 caracteres
• Comenzar con minúscula
• No terminar con punto
• Usar imperativo ("add" no "added" ni "adds")
• Describir QUÉ hace el cambio, no CÓMO

Body (opcional)

• Separado del subject por una línea en blanco
• Máximo 72 caracteres por línea
• Explicar el QUÉ y el POR QUÉ, no el CÓMO
• Puede tener múltiples párrafos

Footer (opcional)

• Referencias a issues: Closes #123, Fixes #456
• Breaking changes: BREAKING CHANGE: descripción
• Co-authored-by para colaboraciones

---

3. Branch Naming

Convención de Nombres

<type>/<descripcion-corta-en-kebab-case>

Tipos de Branches

Tipo	Descripción	Ejemplo
feat/	Nueva característica	feat/student-progress-dashboard
fix/	Corrección de bug	fix/login-timeout-error
docs/	Documentación	docs/api-authentication-guide
refactor/	Refactorización	refactor/exercise-service-cleanup
test/	Tests	test/gamification-unit-tests
chore/	Mantenimiento	chore/update-dependencies
perf/	Performance	perf/optimize-database-queries
hotfix/	Corrección urgente	hotfix/security-vulnerability

Branches Especiales

• main o master: Código en producción
• develop: Código en desarrollo (si se usa GitFlow)
• release/vX.Y.Z: Preparación de releases

Reglas de Naming

1. Usar kebab-case (palabras separadas por guiones)
2. Máximo 50 caracteres
3. Descriptivo pero conciso
4. En inglés (preferible) o español consistente
5. Sin números al final (usar el issue number en commits)

---

4. Pull Request Guidelines

Título del PR

Seguir el mismo formato que commits:

<type>(<scope>): <descripción>

Descripción del PR

## Descripción
Breve descripción de los cambios realizados.

## Cambios Principales
- Cambio 1
- Cambio 2
- Cambio 3

## Tipo de Cambio
- [ ] Bug fix (cambio que soluciona un issue)
- [ ] Nueva característica (cambio que agrega funcionalidad)
- [ ] Breaking change (cambio que rompe compatibilidad)
- [ ] Documentación

## Testing
- [ ] Tests unitarios agregados/actualizados
- [ ] Tests de integración verificados
- [ ] Pruebas manuales realizadas

## Screenshots (si aplica)
[Agregar capturas de pantalla]

## Checklist
- [ ] El código sigue las convenciones del proyecto
- [ ] Los commits siguen Conventional Commits
- [ ] La documentación fue actualizada
- [ ] No hay warnings ni errores de lint

## Issues Relacionados
Closes #123
Related to #456

---

5. Ejemplos Prácticos

Ejemplo 1: Nueva Feature

git commit -m "feat(gamification): add ML coins reward system

Implement the ML coins transaction system that allows students to
earn and spend virtual currency based on their achievements.

- Create MLCoinsTransaction entity
- Add transaction service with reward calculation
- Implement purchase validation logic
- Add transaction history endpoint

Closes #234"

Ejemplo 2: Bug Fix

git commit -m "fix(auth): resolve session timeout not clearing tokens

The session timeout was not properly clearing JWT tokens from
localStorage, causing authentication errors on re-login.

Changed the logout flow to explicitly clear all auth-related
storage before redirecting to login page.

Fixes #567"

Ejemplo 3: Documentación

git commit -m "docs(api): add authentication flow documentation

Create comprehensive guide for the authentication process including
OAuth integration, JWT handling, and session management.

Added diagrams and code examples for common use cases."

Ejemplo 4: Refactorización

git commit -m "refactor(exercises): extract validation logic to separate service

Move exercise validation logic from controller to dedicated
validation service to improve testability and separation of concerns.

No functional changes, only code organization improvements."

Ejemplo 5: Breaking Change

git commit -m "feat(api): change classroom assignment endpoint structure

BREAKING CHANGE: The classroom assignment endpoint now returns
a different response structure with nested teacher information.

Old response:
{
  classroomId: string,
  teacherId: string
}

New response:
{
  classroom: {
    id: string,
    name: string,
    teacher: {
      id: string,
      name: string,
      email: string
    }
  }
}

Closes #890"

Ejemplo 6: Multiple Scopes

git commit -m "chore(backend,database): upgrade TypeORM to v0.3.x

Update TypeORM dependency and migrate entity decorators to new syntax.
Also update database migrations to be compatible with new version.

- Upgrade TypeORM to 0.3.20
- Update all entity files
- Refactor repository patterns
- Update database connection config"

Ejemplo 7: Performance Optimization

git commit -m "perf(database): add indexes for frequently queried fields

Add composite indexes on user_stats table to improve leaderboard
query performance. Reduces query time from ~2s to ~200ms.

Added indexes:
- (tenant_id, total_points, updated_at)
- (user_id, created_at)"

---

6. Reglas del Proyecto

Commits

1. Commits Atómicos: Cada commit debe representar un cambio lógico único
2. Idioma: Preferir inglés para mensajes de commit (consistencia con código)
3. Tamaño: Evitar commits masivos (más de 10 archivos modificados)
4. WIP: No hacer commits de "Work in Progress" a ramas principales
5. Tests: Commits que agreguen features deben incluir tests

Branches

1. Naming: Siempre usar el formato <type>/<descripcion>
2. Limpieza: Borrar branches después de merge
3. Actualización: Hacer rebase/merge de main regularmente
4. Protección: No hacer push directo a main o develop

Pull Requests

1. Review: Mínimo 1 aprobación antes de merge
2. CI/CD: Todos los checks deben pasar (tests, lint, build)
3. Conflicts: Resolver conflictos antes de merge
4. Squash: Considerar squash para múltiples commits pequeños
5. Descripción: Siempre incluir descripción detallada

Merging

1. Strategy: Usar "Squash and merge" para features pequeñas
2. Strategy: Usar "Merge commit" para features grandes o releases
3. Strategy: Usar "Rebase and merge" para cambios lineales
4. Message: Editar el mensaje de merge si es necesario

---

7. Buenas Prácticas

Antes de Commitear

# Verificar qué archivos cambiaron
git status

# Revisar los cambios específicos
git diff

# Agregar archivos selectivamente
git add <file1> <file2>

# O agregar por chunks interactivos
git add -p

# Verificar qué se va a commitear
git diff --staged

Escribir Buenos Mensajes

Bueno:

feat(auth): add password strength validation

Implement password strength checker that enforces:
- Minimum 8 characters
- At least one uppercase letter
- At least one number
- At least one special character

Closes #123

Malo:

fixed stuff

WIP

Updated files and added new features to the authentication module, also fixed some bugs and refactored code

Corregir Commits

Modificar el último commit

# Cambiar el mensaje del último commit
git commit --amend -m "nuevo mensaje"

# Agregar archivos olvidados al último commit
git add archivo-olvidado.ts
git commit --amend --no-edit

Revertir un commit

# Crear un nuevo commit que revierte cambios
git revert <commit-hash>

# Mensaje sugerido
git revert <hash> -m "revert: undo feature X due to critical bug"

Mantener Historial Limpio

# Interactive rebase para limpiar commits antes de PR
git rebase -i HEAD~5

# Opciones en interactive rebase:
# - pick: mantener commit
# - reword: cambiar mensaje
# - squash: combinar con commit anterior
# - drop: eliminar commit

Git Hooks (Recomendado)

Usar herramientas como Husky para validar commits:

// package.json
{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
      "pre-commit": "lint-staged"
    }
  }
}

---

Referencias

• Conventional Commits
• Semantic Versioning
• Git Best Practices
• How to Write a Git Commit Message

---

Última actualización: 2025-11-29 Versión: 1.0.0 Mantenedor: Equipo GAMILIT