Contributing

​

Overview

​

Prerequisites

• Java 21 or higher
• Maven 3.8+ (or use the included ./mvnw wrapper)
• Docker & Docker Compose (for local database setup)
• Git for version control
• IDE (IntelliJ IDEA recommended)

​

Development Setup

​

1. Clone the Repository

git clone https://github.com/ccasro/5.01-Advanced-Spring-Framework.git
cd 5.01-Advanced-Spring-Framework

​

2. Start Local Databases

docker compose up -d

• MongoDB on localhost:27017
• MySQL on localhost:3306

​

3. Run the Application

./mvnw spring-boot:run

​

4. Verify Setup

http://localhost:8080/swagger-ui.html

​

Project Structure

src/main/java/cat/itacademy/s05/t01/blackjack_api/
├── domain/                    # Core business logic
│   ├── model/                # Domain entities and value objects
│   ├── port/                 # Repository and service interfaces
│   ├── service/              # Domain services
│   └── exception/            # Domain exceptions
├── application/               # Use cases and application logic
│   ├── usecase/              # Application use cases
│   ├── dto/                  # Application DTOs
│   └── mapper/               # Application mappers
└── infrastructure/            # External adapters
    ├── web/                  # REST controllers
    │   ├── controller/       # Controller classes
    │   ├── dto/              # Web request/response DTOs
    │   └── error/            # Global exception handling
    ├── persistence/          # Database adapters
    │   ├── mongo/            # MongoDB repositories
    │   └── mysql/            # MySQL repositories (R2DBC)
    └── config/               # Spring configuration

​

Architecture Principles

​

Coding Standards

​

Java Style

• Java 21 language features are encouraged
• Use Lombok for reducing boilerplate (@Data, @Builder, etc.)
• Follow standard Java naming conventions
• Keep methods small and focused (Single Responsibility)
• Prefer immutability where possible

​

Domain-Driven Design

​

Reactive Patterns

// Return Mono for single results
public Mono<GameStateResult> execute(String gameId) {
    return gameRepository.findById(gameId)
        .map(GameStateMapper::toResult);
}

// Return Flux for multiple results
public Flux<PlayerRankingDto> execute() {
    return playerRepository.findAllByOrderByScoreDesc();
}

​

Exception Handling

• Domain exceptions (GameNotFoundException, InvalidMoveException, etc.) in domain/exception/
• Global exception handler in infrastructure/web/error/GlobalExceptionHandler
• Map domain exceptions to appropriate HTTP status codes

​

Development Workflow

​

Branch Strategy

1. main - Production-ready code
2. feature/ - New features (feature/add-multiplayer)
3. fix/ - Bug fixes (fix/dealer-bust-calculation)
4. refactor/ - Code refactoring (refactor/simplify-game-logic)
5. test/ - Test improvements (test/add-ranking-tests)
6. docs/ - Documentation updates (docs/update-api-specs)

​

Creating a Feature

1. Create a new branch from main:

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

2. Make your changes following the coding standards
3. Write tests for your changes (see Testing Guide)
4. Run tests locally:

./mvnw test

5. Commit your changes using conventional commits

​

Commit Conventions

​

Commit Format

<type>: <description>

[optional body]

[optional footer]

​

Commit Types

​

Commit Examples

# Good commits
git commit -m "feat: add player statistics endpoint"
git commit -m "fix: prevent moves on finished games"
git commit -m "refactor: extract deck shuffling to domain service"
git commit -m "test: add unit tests for Hand value object"

# Bad commits (avoid these)
git commit -m "update"
git commit -m "fixes"
git commit -m "changes to game logic"

​

Commit Best Practices

• Keep commits small and focused on a single change
• Write clear and descriptive commit messages
• Use present tense (“add” not “added”)
• Reference issue numbers if applicable: fix: correct scoring (#42)
• Do not commit:
  • Secrets or credentials
  • Compiled files (.class, target/)
  • IDE-specific files (use .gitignore)
  • Large binary files

​

Testing Requirements

• ✅ Domain changes require domain unit tests
• ✅ Use case changes require application tests with mocked repositories
• ✅ Controller changes require WebTestClient integration tests
• ✅ All tests must pass before submitting a pull request

./mvnw test

​

Pull Request Process

​

1. Prepare Your Branch

git checkout main
git pull origin main
git checkout your-branch
git rebase main

​

2. Create Pull Request

• Push your branch to GitHub
• Create a pull request against main
• Use a descriptive PR title (following conventional commit format)
• Provide a clear description of changes

​

PR Template

## Summary
Brief description of what this PR does

## Changes
- List of changes made
- New features or fixes

## Testing
- Describe how you tested the changes
- List any new tests added

## Related Issues
Closes #issue-number (if applicable)

​

3. Code Review

• Address reviewer feedback
• Keep the PR focused and small when possible
• Use git commit --fixup for review changes if appropriate

​

4. Merge

• Ensure all tests pass
• Squash commits if needed
• Merge to main

​

Database Migrations

1. Create a new migration file in src/main/resources/db/migration/
2. Follow naming convention: V{version}__{description}.sql
   • Example: V2__add_player_statistics.sql
3. Test migration locally:

./mvnw flyway:migrate

​

API Documentation

• Keep Swagger/OpenAPI annotations up to date
• Document all REST endpoints with @Operation, @ApiResponse
• Test documentation at http://localhost:8080/swagger-ui.html

​

Code Review Guidelines

​

Getting Help

• Review existing code for patterns and examples
• Check the Architecture Overview
• Consult the API Reference
• Open a discussion on GitHub

​

Additional Resources

​

License