Contributing to Pokermon

Thank you for your interest in contributing to Pokermon! This document provides guidelines and instructions for contributing to the project.

📋 Table of Contents

Code of Conduct
Getting Started
Development Workflow
Coding Standards
Testing Requirements
Submitting Changes
Asset Contributions

Code of Conduct

This project follows professional software development practices. We expect all contributors to:

Be respectful and constructive in discussions
Focus on the technical merits of contributions
Help maintain code quality and project standards
Follow the established architectural patterns

Getting Started

Prerequisites

JDK 17 or higher for JVM builds
Gradle (included via wrapper)
Android SDK (optional, for Android builds)
Git for version control

Initial Setup

Clone the repository:

git clone https://github.com/Gameaday/poker-basic.git
cd poker-basic

Verify setup:

./gradlew verifyKotlinNativeSetup --no-daemon

Run tests:
```
./gradlew :shared:test --no-daemon
```
Build the project:
```
./gradlew :shared:fatJar --no-daemon
```

Development Workflow

Branch Strategy

master - Stable, production-ready code
copilot/* - Feature branches created by GitHub Copilot
Feature branches should be named descriptively (e.g., feature/monster-evolution)

Making Changes

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following the coding standards below
Run tests frequently:
```
./gradlew :shared:test --no-daemon
```

Build to verify:

./gradlew :shared:compileKotlin --no-daemon

Commit with descriptive messages:

git commit -m "Add monster evolution system"

Coding Standards

Kotlin Style Guide

This project follows Kotlin coding conventions with the following specifics:

General Principles

Pure Kotlin-Native: All new code should be written in Kotlin
DRY Principles: Don't Repeat Yourself - create single sources of truth
Type Safety: Leverage Kotlin's type system and null safety
Immutability: Prefer val over var, use data classes for state

File Organization

// Package structure follows logical organization
com.pokermon/
├── GameEngine.kt           // Core logic
├── GameMode.kt            // Enums and constants
├── bridge/                // Cross-platform API
├── modes/                 // Game mode implementations
│   ├── adventure/         // Adventure mode specific
│   ├── classic/           // Classic mode specific
│   ├── safari/            // Safari mode specific
│   └── ironmon/           // Ironman mode specific
└── GameFlows/             // Reactive state management

Naming Conventions

Classes: PascalCase (e.g., GameEngine, MonsterDatabase)
Functions: camelCase (e.g., evaluateHand, dealCards)
Constants: UPPER_SNAKE_CASE (e.g., MAX_PLAYERS, DEFAULT_CHIPS)
Private properties: prefix with underscore if needed for clarity

Code Style

// ✅ GOOD: Clear, type-safe Kotlin code
data class Monster(
    val id: String,
    val name: String,
    val type: MonsterType,
    val level: Int = 1,
    val health: Int = 100
) {
    fun takeDamage(damage: Int): Monster {
        return copy(health = maxOf(0, health - damage))
    }
}

// ✅ GOOD: Null safety with smart casts
fun processMonster(monster: Monster?) {
    monster?.let {
        println("Processing ${it.name}")
        if (it.health > 0) {
            // it is smart-cast to non-null Monster
            it.takeDamage(10)
        }
    }
}

// ✅ GOOD: Flow-based reactive state
class GameStateManager {
    private val _gameState = MutableStateFlow<GameState>(GameState.Initializing)
    val gameState: StateFlow<GameState> = _gameState.asStateFlow()
}

// ❌ AVOID: Nullable types when not needed
var monster: Monster? = null  // Only if truly optional

// ❌ AVOID: Mutable state when immutable is sufficient
var health = 100  // Prefer val with copy() for changes

Documentation

Public APIs: Must have KDoc comments
Complex logic: Inline comments explaining "why", not "what"
TODOs: Use TODO comments with context, but don't commit them for production code

/**
 * Evaluates a poker hand and returns its strength.
 *
 * @param cards The list of cards to evaluate (must be exactly 5 cards)
 * @return HandEvaluation containing the hand type and comparison value
 * @throws IllegalArgumentException if cards.size != 5
 */
fun evaluateHand(cards: List<Card>): HandEvaluation {
    require(cards.size == 5) { "Hand must contain exactly 5 cards" }
    // Implementation...
}

Testing Requirements

Test Coverage

All new features must include tests
Bug fixes should include regression tests
Tests must pass before submitting changes

Writing Tests

class GameEngineTest {
    @Test
    fun `should deal correct number of cards to each player`() {
        // Arrange
        val game = Game(playerCount = 3, startingChips = 1000)
        val engine = GameEngine(game)
        
        // Act
        engine.dealCards()
        
        // Assert
        assertEquals(5, engine.getPlayerHand(0).size)
        assertEquals(5, engine.getPlayerHand(1).size)
        assertEquals(5, engine.getPlayerHand(2).size)
    }
}

Running Tests

# Run all tests
./gradlew :shared:test --no-daemon

# Run specific test class
./gradlew :shared:test --tests "GameEngineTest" --no-daemon

# Run tests with detailed output
./gradlew :shared:test --no-daemon --info

Submitting Changes

Pull Request Process

Ensure all tests pass:
```
./gradlew :shared:test --no-daemon
```

Build successfully:

./gradlew :shared:compileKotlin --no-daemon
./gradlew :shared:fatJar --no-daemon

Update documentation if needed (README.md, PROJECT_STATUS.md)
Create a pull request with:
- Clear title describing the change
- Detailed description of what changed and why
- Reference to any related issues
- Test results showing all tests pass

Pull Request Template

## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Performance improvement
- [ ] Documentation update
- [ ] Code refactoring

## Testing
- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Manual testing completed

## Checklist
- [ ] Code follows Kotlin coding conventions
- [ ] Documentation updated
- [ ] No new warnings or errors
- [ ] Commit messages are clear and descriptive

Asset Contributions

Asset Types Needed

Monster Artwork (50+ unique monsters)
- Format: PNG with transparency
- Resolution: 512x512 minimum
- Style: Consistent across all monsters
Card Designs (54 poker cards)
- Format: PNG
- Resolution: 300x450 minimum
- Style: Professional, readable
UI Elements
- Icons, buttons, backgrounds
- Format: PNG or SVG
- Style: Material Design 3 compatible
Audio
- Sound effects: OGG format
- Music tracks: OGG format, loopable
- Quality: 44.1kHz, stereo

Asset Submission

Follow asset guidelines in docs/ASSET_GUIDELINES.md (coming soon)
Submit via GitHub issue with "Asset Contribution" label
Include license information (must be compatible with project license)
Provide source files if available (PSD, AI, etc.)

Code Review Process

All submissions go through code review:

Automated checks run via GitHub Actions
Manual review by project maintainers
Feedback addressed through discussion
Approval and merge when ready

Review Criteria

✅ Code quality and style
✅ Test coverage
✅ Documentation completeness
✅ Performance considerations
✅ Architectural alignment

Getting Help

Questions? Open a GitHub Discussion
Bugs? File a GitHub Issue
Feature ideas? Start with a Discussion, then create an Issue

License

By contributing to Pokermon, you agree that your contributions will be licensed under the same license as the project.

Recognition

Contributors will be recognized in:

Project README.md
Release notes
Project documentation

Thank you for contributing to Pokermon! 🎮🐲

For project status and roadmap, see PROJECT_STATUS.md

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History