Contributing ES - BruGeth/Cinerama GitHub Wiki

🤝 Contribuir a Cinerama

Esta guía explica cómo contribuir correctamente al repositorio, incluyendo ramas, commits, PRs y revisión de código.

📑 Tabla de Contenidos

🚦 Flujo de trabajo con Git

Ramas principales

  • main: código estable en producción
  • develop: rama base para integrar nuevas funcionalidades
  • release/*: versiones listas para producción

🌱 Ramas de desarrollo

Cada desarrollador debe crear ramas usando el prefijo adecuado según el tipo de trabajo:

Prefijo de rama Uso principal Ejemplo
feature/ Nueva funcionalidad feature/seat-selection-ui
bugfix/ Corrección de errores en desarrollo bugfix/login-failure
hotfix/ Correcciones urgentes para producción (main) hotfix/fix-payment-crash
chore/ Tareas de mantenimiento o mejoras menores chore/add-eslint-config
test/ Experimentación o pruebas temporales test/load-testing-checkout
docs/ Cambios o adiciones de documentación docs/update-readme
refactor/ Reorganización o mejora de código sin cambiar funcionalidad refactor/checkout-module

Ejemplos:

  • feature/user-authentication
  • bugfix/payment-validation
  • hotfix/critical-security-patch
  • chore/update-dependencies

📝 Convención de commits

Usamos la convención Conventional Commits:

<tipo>(componente): mensaje breve

Tipos comunes

  • feat: nueva funcionalidad
  • fix: corrección de error
  • docs: documentación
  • style: formato (sin cambios de lógica)
  • refactor: reestructuración de código sin cambiar comportamiento
  • test: pruebas
  • chore: mantenimiento

Ejemplos

feat(backend): agregar endpoint para crear películas
fix(frontend): corregir bug en formulario de registro
docs: actualizar README con instrucciones de despliegue

🔤 Todo debe hacerse en inglés: nombres de ramas, commits, PRs.

🧩 Pasos para colaborar

  1. Clona el repositorio (si aún no lo has hecho)

    git clone https://github.com/BruGeth/Cinerama.git
    cd cinerama
  2. Actualiza tu rama local develop

    git checkout develop
    git pull origin develop
  3. Crea una nueva rama con el prefijo adecuado

    # Para nuevas funcionalidades
    git checkout -b feature/tu-nueva-funcionalidad
    
    # Para correcciones de errores
    git checkout -b bugfix/descripcion-del-error
    
    # Para hotfixes (desde main)
    git checkout main
    git checkout -b hotfix/correccion-critica
  4. Agrega tus cambios

    git add .
  5. Haz commit siguiendo la convención

    git commit -m "feat(componente): agregar nueva funcionalidad"
  6. Haz push a tu rama

    git push origin feature/tu-nueva-funcionalidad
  7. Crea un Pull Request (PR) hacia develop (o main para hotfixes)

🛠️ Estructura sugerida para Pull Requests

## 📌 Description

Please include a summary of the change and the related issue.  
Also mention any context or dependencies if relevant.

Closes: #<issue-number>

---

## ✅ Checklist

- [ ] Code compiles and runs correctly
- [ ] All existing and new tests pass
- [ ] Follows coding conventions/style
- [ ] No unnecessary console.logs or commented code
- [ ] Proper error handling implemented
- [ ] Responsive design (if applicable)
- [ ] Connected to backend (if required)

---

## 🧪 How to Test

1. Go to `...`
2. Click on `...`
3. Observe `...`

Provide clear steps or test credentials if needed.

---

## 📷 Screenshots (if UI was changed)

| Before | After |
|--------|-------|
| ![before](url) | ![after](url) |

---

## 💬 Additional Notes

- Any concerns, future improvements, or technical debt to be aware of?

🔍 Proceso de revisión de Pull Requests

Para colaboradores:

  1. Agrega a @Brugeth como revisor
  2. Espera la revisión y corrige los cambios solicitados
  3. Si el PR es aprobado, puede ser fusionado
  4. Si hay errores graves, el PR será cerrado

Checklist de revisión:

  • El código sigue las convenciones del proyecto
  • Todas las pruebas pasan
  • La documentación está actualizada
  • No hay cambios disruptivos sin discusión
  • El código está correctamente comentado

📋 Guías de desarrollo

Estándares de calidad de código

  • Sigue convenciones de nombres consistentes
  • Escribe comentarios significativos (ver Buenas prácticas para comentarios)
  • Incluye pruebas unitarias para nuevas funcionalidades
  • Mantén funciones pequeñas y enfocadas
  • Usa nombres de variables descriptivos

Buenas prácticas para comentarios

Los comentarios deben explicar el "por qué", no el "qué". El código debe ser autoexplicativo primero.

Para Java/Spring Boot

Usa JavaDoc para APIs públicas:

/**
 * Processes movie booking and updates seat availability
 * @param bookingRequest booking details including movie, seats, and user info
 * @param paymentMethod selected payment method
 * @return booking confirmation with transaction details
 * @throws BookingException if booking fails due to seat unavailability
 * @throws PaymentException if payment processing fails
 */
@Transactional
public BookingResult processMovieBooking(BookingRequest bookingRequest, PaymentMethod paymentMethod) {
    // Implementation
}

Comenta decisiones de negocio complejas:

// Apply 20% discount for students as per cinema policy CP-2024-15
// Valid only for movies before 6 PM on weekdays
if (isStudentDiscount(user) && isEligibleForStudentDiscount(showtime)) {
    applyStudentDiscount(booking, 0.20);
}

Explica configuraciones específicas de Spring:

@Configuration
public class SecurityConfig {
    
    // Disable CSRF for REST APIs since we use JWT tokens
    // JWT tokens are stateless and don't require CSRF protection
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf().disable()
            .build();
    }
}

Para React/JavaScript

Comenta hooks complejos y efectos:

useEffect(() => {
    // Debounce movie search to avoid excessive API calls
    // while user is typing in the search box
    const timeoutId = setTimeout(() => {
        if (searchQuery.length >= 3) {
            searchMovies(searchQuery);
        }
    }, 300);

    return () => clearTimeout(timeoutId);
}, [searchQuery]);

Explica lógica de renderizado condicional compleja:

const SeatSelector = ({ movie, showtime }) => {
    // Show different seat colors based on availability and pricing
    // Premium seats cost 50% more and are highlighted differently
    const shouldShowPremiumSeats = movie.hasLuxurySeating && 
                                  showtime.isPeakHour;
    
    return (
        <div>
            {shouldShowPremiumSeats && <PremiumSeatLegend />}
            {/* rest of component */}
        </div>
    );
};

Documenta props complejas con JSDoc:

/**
 * Movie booking summary component
 * @param {Object} props
 * @param {Array<Seat>} props.selectedSeats - Array of selected seat objects
 * @param {Movie} props.movie - Movie details object
 * @param {Showtime} props.showtime - Selected showtime information
 * @param {Function} props.onBookingConfirm - Callback when booking is confirmed
 */
const BookingSummary = ({ selectedSeats, movie, showtime, onBookingConfirm }) => {
    // Implementation
};

Prácticas a evitar

❌ No comentes código obvio:

// BAD
int totalSeats = 0; // initialize total seats to 0
totalSeats++; // increment seat counter

// GOOD - code is self-explanatory
int availableSeats = 0;
availableSeats++;

❌ No dejes código comentado sin explicación:

// BAD
// const oldPriceCalculation = basePrice * 0.8;
const finalPrice = calculateMovieTicketPrice(basePrice, discounts);

// BETTER - if you need to keep it
// Old calculation kept for reference until new pricing
// algorithm is validated in production (ticket #CIN-456)
// const oldPriceCalculation = basePrice * 0.8;
const finalPrice = calculateMovieTicketPrice(basePrice, discounts);

Requisitos de documentación

  • Actualiza README.md si agregas nuevas funcionalidades
  • Agrega comentarios JSDoc para nuevas funciones
  • Actualiza la documentación de la API para nuevos endpoints
  • Incluye ejemplos en los comentarios del código
  • Comenta decisiones de arquitectura o lógica de negocio compleja
  • Explica algoritmos no triviales o cálculos específicos del dominio cinematográfico

🐛 Reportes de bugs

Cuando reportes un bug, incluye:

  1. Descripción clara del problema
  2. Pasos para reproducir el bug
  3. Comportamiento esperado
  4. Comportamiento actual
  5. Capturas de pantalla si aplica
  6. Detalles del entorno (SO, navegador, versiones)

Los reportes de bugs y solicitudes de funcionalidades deben crearse como Issues en GitHub.
Al crear un nuevo issue, puedes seleccionar la plantilla adecuada (bug report o feature request) directamente desde la página de "New Issue" del repositorio en GitHub.

🌟 Solicitudes de funcionalidades

Al sugerir nuevas funcionalidades:

  1. Revisa los issues existentes para evitar duplicados
  2. Describe claramente el caso de uso
  3. Explica los beneficios para los usuarios
  4. Proporciona ejemplos si es posible

View in English

⚠️ **GitHub.com Fallback** ⚠️