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

• Flujo de trabajo con Git
  • Ramas principales
  • Ramas de desarrollo
• Convención de commits
• Pasos para colaborar
• Estructura sugerida para Pull Requests
• Proceso de revisión de Pull Requests
• Guías de desarrollo
  • Estándares de calidad de código
  • Requisitos de documentación
• Estructura del proyecto
• Reportes de bugs
• Solicitudes de funcionalidades
• Ayuda
• Reconocimiento

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

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

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

Usamos la convención Conventional Commits:

<tipo>(componente): mensaje breve

• 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

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.

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)

## 📌 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?

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

• 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

• 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

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

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();
    }
}

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
};

❌ 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);

• 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

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.

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