This guide explains how to contribute correctly to the repository, including branches, commits, PRs, and code review.

• Git Workflow
  • Main branches
  • Development branches
• Commit Convention
• Steps to collaborate
• Pull Request structure
• Pull Request Review Process
• Development Guidelines
  • Code Quality Standards
  • Documentation Requirements
• Project Structure
• Bug Reports
• Feature Requests
• Getting Help
• Recognition

• main: stable code in production
• develop: base branch for integrating new features
• release/*: versions ready for production

Each developer should create branches using the appropriate prefix based on the type of work:

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

We use Conventional Commits convention:

<type>(component): brief message

• feat: new feature
• fix: bug fix
• docs: documentation
• style: formatting (no logic changes)
• refactor: code restructuring without behavior change
• test: tests
• chore: maintenance

feat(backend): add endpoint to create movies
fix(frontend): fix bug in signup form
docs: update README with deployment instructions

🔤 Everything must be done in English: branch names, commits, PRs.

1. Clone the repository (if you haven't already)

   git clone https://github.com/BruGeth/Cinerama.git
   cd cinerama

2. Update your local develop branch

   git checkout develop
   git pull origin develop

3. Create a new branch with the appropriate prefix

   # For new features
   git checkout -b feature/your-feature-name
   
   # For bug fixes
   git checkout -b bugfix/issue-description
   
   # For hotfixes (branch from main)
   git checkout main
   git checkout -b hotfix/critical-fix

4. Add your changes

   git add .

5. Commit with correct convention

   git commit -m "feat(component): add new feature"

6. Push to your branch

   git push origin feature/your-feature-name

7. Create a Pull Request (PR) to develop (or main for 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. Add @Brugeth as reviewer
2. Wait for review and fix requested changes
3. If PR is approved, it can be merged
4. If there are serious errors, the PR will be closed

• Code follows project conventions
• All tests pass
• Documentation is updated
• No breaking changes without discussion
• Code is properly commented

• Follow consistent naming conventions
• Write meaningful comments (see Best Practices for Comments)
• Include unit tests for new features
• Keep functions small and focused
• Use descriptive variable names

Comments should explain the "why", not the "what". Code should be self-explanatory first.

Use JavaDoc for public APIs:

/**
 * 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
}

Comment on complex business decisions:

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

Explain specific Spring configurations:

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

Comment on complex hooks and effects:

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

Explain complex conditional rendering logic:

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

Document complex props with 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
};

❌ Do not comment obvious code:

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

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

❌ Do not leave commented-out code without explanation:

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

• Update README.md if you add new features
• Add JSDoc comments for new functions
• Update API documentation for new endpoints
• Include examples in code comments
• Comment on architectural decisions or complex business logic
• Explain non-trivial algorithms or calculations specific to the cinema domain

When reporting bugs, please include:

1. Clear description of the issue
2. Steps to reproduce the bug
3. Expected behavior
4. Actual behavior
5. Screenshots if applicable
6. Environment details (OS, browser, versions)

Bug reports and feature requests should be created as GitHub Issues.
When creating a new issue, you can select the appropriate template (bug report or feature request) directly from the GitHub "New Issue" page in the repository.

When suggesting new features:

1. Check existing issues to avoid duplicates
2. Describe the use case clearly
3. Explain the benefits to users
4. Provide examples if possible

Ver en Español