Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
436 lines (308 loc) · 7.95 KB

CONTRIBUTING.md

File metadata and controls

436 lines (308 loc) · 7.95 KB
Tipo: Documentación del Proyecto
Categoría: Guía de Contribución
Versión: 1.0
Propósito: Guía para contribuir al proyecto THYROX
Objetivo: Que contributors sigan procesos consistentes y de calidad
Fecha actualización: 2026-03-25

CONTRIBUTING

Propósito

Guía para contribuir al proyecto THYROX. Documenta procesos, convenciones, y best practices.

Objetivo: Asegurar contribuciones de calidad consistentes con los estándares del proyecto.

Antes de Comenzar

Prerequisites

Requerido:
Node.js 18.x o superior
Git 2.30+
GitHub account
Editor de código (VSCode recomendado)

Opcional:
Docker
PostgreSQL local
Postman/Insomnia

Setup Inicial

# Clonar repositorio
git clone https://github.com/user/thyrox.git
cd thyrox

# Instalar dependencias
npm install

# Setup inicial
npm run setup

# Verificar setup
npm run health-check

Proceso de Contribución

1. Crear un Issue

Antes de empezar a trabajar, crea un issue describiendo:

Título claro: "Feature: X" o "Fix: Y"
Descripción: Qué, por qué, cómo
Contexto: Información relevante
Screenshots/Logs: Si aplica
Labels: feature, bug, documentation, etc.

2. Crear una Branch

# Actualizar main
git checkout main
git pull origin main

# Crear branch
git checkout -b feature/nombre-feature
# o
git checkout -b fix/nombre-bug

Convención: type/description
feature/user-auth
fix/login-error
docs/update-readme

3. Hacer Cambios

Código:
Sigue convenciones del proyecto
Agrega tests para nuevo código
Asegúrate de que tests pasen
Documenta cambios complejos

Commits:
Commits frecuentes y descriptivos
Sigue Conventional Commits
Referencia el issue: fix: login error (fixes #123)

4. Push y Pull Request

# Push a origin
git push origin feature/nombre-feature

# Crear Pull Request en GitHub
# Rellena el template PR
# Referencia el issue

PR Description:
Qué cambia
Por qué cambia
Cómo testearlo
Breaking changes (si aplica)
Screenshots/videos
Closes #123

5. Code Review

Espera feedback de los maintainers
Responde comentarios constructivamente
Haz cambios según feedback
Re-request review después de cambios

6. Merge

Una vez aprobado:
Squash commits (si aplica)
Merge a main
Delete feature branch
Close issue relacionado

Convenciones del Código

JavaScript/Node.js

Style: ESLint config del proyecto
Linter: npm run lint
Formatter: Prettier
Tests: Jest

Ejemplo:

// Buen ejemplo
const getUserById = async (userId) => {
  try {
    const user = await db.users.findById(userId);
    if (!user) {
      throw new NotFoundError(`User ${userId} not found`);
    }
    return user;
  } catch (error) {
    logger.error('Error fetching user', { userId, error });
    throw error;
  }
};

Markdown

Formato: Markdown estándar
Line breaks: <br> para HTML
Headers: # Title, ## Subtitle, etc.
Lists: - para viñetas, no números

Git Commits

Sigue Conventional Commits:

feat(api): add user authentication endpoint
fix(db): resolve connection pooling issue
docs(readme): update installation steps
style(code): format with prettier
refactor(service): simplify user service
test(auth): add authentication tests
chore(deps): update dependencies

Testing

Unit Tests

npm run test
npm run test:watch
npm run test:coverage

Requerimientos:
Mínimo 80% coverage
Happy path y edge cases
Mocking de dependencias

Integration Tests

npm run test:integration

Requerimientos:
Test contra staging DB
Full workflow testing
Error scenarios

Manual Testing

  • Test en local antes de PR
  • Sigue casos de uso documentados
  • Prueba en diferentes ambientes
  • Verifica breaking changes

Documentation

Cambios en Código

Comenta código complejo:

// Evita el N+1 problem al pre-load relations
const users = await User.query()
  .withGraphFetched('posts');

Cambios en API

Actualiza docs/API.md:

### GET /api/v1/users/:id

Obtiene usuario por ID.

**Parameters:**
- id (string, required): User ID

**Response:**
- 200: User object
- 404: User not found

Cambios en Arquitectura

Actualiza ARCHITECTURE.md:

  • Decisiones arquitectónicas
  • Patrones nuevos
  • Cambios en estructura

Cambios en Proceso

Actualiza CONTRIBUTING.md (este archivo):

  • Nuevos procesos
  • Cambios en convenciones
  • Nuevas herramientas

Best Practices

Code Quality

DRY: Don't Repeat Yourself
SOLID: Single Responsibility, etc.
KISS: Keep It Simple, Stupid
YAGNI: You Aren't Gonna Need It

Naming

Variables: Descriptivas, claras
const userName = 'John'; ✓
const u = 'John'; ✗

Functions: Verbo + sustantivo
getUserById() ✓
getUser() con múltiples parámetros ✗

Comments

Usa cuando:
Explicas el "por qué", no el "qué"
Código complejo
Workarounds o hacks

No uses cuando:
El código es autoexplicativo
El nombre de función/variable es claro

Reportar Issues

Bug Report

**Descripción:** Qué está roto

**Pasos para reproducir:**
1. ...
2. ...
3. ...

**Comportamiento esperado:** Qué debería pasar

**Actual:** Qué pasa actualmente

**Ambiente:**
- OS: Ubuntu 20.04
- Node: 18.0.0
- Versión: 0.1.0

**Logs:**
[Pegá los logs aquí]

**Screenshots:**
[Si aplica]

Feature Request

**Descripción:** Qué quieres agregar

**Casos de uso:** Cuándo se usaría

**Diseño propuesto:** Cómo se vería

**Alternativas:** Otros enfoques

**Contexto adicional:** Información relevante

Ayuda y Soporte

Preguntas

Abre un issue con label question
O contacta a los maintainers
O revisa la documentación existente

Discussion

Para discusiones amplias, abre un Discussion en GitHub
No merece un issue individual
Puede llevar a un issue después

Escalation

Si algo está bloqueado, menciona a los maintainers
Sé respetuoso
Proporciona contexto completo

Code of Conduct

Principios

Respeto: A todos los miembros
Inclusión: Bienvenida a todos
Constructivo: Feedback helpful
Profesional: Comunicación clara

Prohibido

Abuso, acoso, discriminación
Spam o solicitudes injustificadas
Lenguaje ofensivo
Desviar temas

Violations

Reporta violations a maintainers
Proporciona evidencia
Mantén privacidad
Se tomarán acciones

Tips para Contribuciones Exitosas

✓ Lee la documentación existente
✓ Sigue las convenciones del proyecto
✓ Tests para todo código nuevo
✓ Commits descriptivos
✓ PRs enfocadas en un tema
✓ Comunica claramente
✓ Sé paciente con reviews
✓ Aprende del feedback
✓ Ayuda a otros contributors
✓ Celebra cuando merges

Recursos

Documentación:
README.md - Overview
ARCHITECTURE.md - Arquitectura
ROADMAP.md - Plan del proyecto
docs/ - Documentación detallada

Links útiles:
Conventional Commits: https://www.conventionalcommits.org/
GitHub Flow: https://guides.github.com/introduction/flow/
Semantic Versioning: https://semver.org/

FAQ

Q: ¿Cómo empiezo?
A: Lee este archivo, luego elige un issue con label good first issue

Q: ¿Puedo trabajar en múltiples issues?
A: Sí, pero en branches separadas. Una rama = un tema.

Q: ¿Cuánto tarda el code review?
A: 24-48 horas normalmente. Depende de la complejidad.

Q: ¿Qué si mi PR es rechazada?
A: Es feedback, no rechazo personal. Aprende y intenta de nuevo.

Última Actualización: 2026-03-25
Próxima Review: 2026-04-25

¡Gracias por contribuir!