Contributing ES - BruGeth/Cinerama GitHub Wiki
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
- Convención de commits
- Pasos para colaborar
- Estructura sugerida para Pull Requests
- Proceso de revisión de Pull Requests
- Guías de desarrollo
- 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:
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 |
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.
-
Clona el repositorio (si aún no lo has hecho)
git clone https://github.com/BruGeth/Cinerama.git cd cinerama
-
Actualiza tu rama local
develop
git checkout develop git pull origin develop
-
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
-
Agrega tus cambios
git add .
-
Haz commit siguiendo la convención
git commit -m "feat(componente): agregar nueva funcionalidad"
-
Haz push a tu rama
git push origin feature/tu-nueva-funcionalidad
-
Crea un Pull Request (PR) hacia
develop
(omain
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 |
|--------|-------|
|  |  |
---
## 💬 Additional Notes
- Any concerns, future improvements, or technical debt to be aware of?
- Agrega a @Brugeth como revisor
- Espera la revisión y corrige los cambios solicitados
- Si el PR es aprobado, puede ser fusionado
- 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:
- Descripción clara del problema
- Pasos para reproducir el bug
- Comportamiento esperado
- Comportamiento actual
- Capturas de pantalla si aplica
- 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:
- Revisa los issues existentes para evitar duplicados
- Describe claramente el caso de uso
- Explica los beneficios para los usuarios
- Proporciona ejemplos si es posible