PlayHours/.cursor/rules/commits.mdc

---
alwaysApply: false
---
# Commit Message Format for PlayHours Mod

## Format Structure

```
type(scope): emoji description

[Optional body with bullet points]
- Detail 1
- Detail 2

[Optional footer]
```

## Commit Types & Emojis

### Core Types
- **feat** ✨ - New feature
- **fix** 🐛 - Bug fix
- **docs** 📚 - Documentation changes
- **refactor** ♻️ - Code refactoring (no functional change)
- **test** 🧪 - Adding or updating tests
- **chore** 🔧 - Maintenance tasks (dependencies, build, etc.)

### Additional Types
- **perf** ⚡ - Performance improvements
- **style** 💎 - Code style/formatting (no logic change)
- **build** 📦 - Build system or dependencies
- **ci** 🤖 - CI/CD workflow changes
- **revert** ⏪ - Revert previous commit

## Scopes (Mod-Specific)

### Feature Areas
- **command** - Command system (`/hours` and subcommands)
- **config** - Configuration files and handlers
- **schedule** - Schedule calculation and enforcement
- **login** - Login guard and blocking
- **motd** - MOTD system and server list display
- **warnings** - Warning and auto-kick system
- **permissions** - Permission system and LuckPerms integration
- **i18n** - Localization and translations
- **exceptions** - Date exceptions handling
- **lists** - Whitelist/blacklist management
- **force** - Force mode functionality

### Technical Areas
- **core** - Core logic and services
- **events** - Event handlers (LoginGuard, TickScheduler, etc.)
- **text** - Message formatting and locale loading
- **gradle** - Build configuration
- **workflow** - CI/CD and release automation
- **mod** - Main mod class and initialization

### Documentation & Meta
- **docs** - Documentation files
- **changelog** - Changelog updates
- **release** - Release preparation
- **readme** - README updates

## Examples by Feature Area

### Commands
```
feat(command): ✨ add new /hours lists command for whitelist/blacklist management
fix(command): 🐛 fix permission check in DayCommandBuilder
refactor(command): ♻️ simplify command builder hierarchy
```

### Configuration
```
feat(config): ✨ add support for timezone configuration
fix(config): 🐛 fix TOML parsing error with midnight-spanning ranges
docs(config): 📚 add inline comments to default config
```

### Schedule System
```
feat(schedule): ✨ implement date exceptions for holidays
fix(schedule): 🐛 fix midnight-spanning time range calculation
perf(schedule): ⚡ optimize schedule caching mechanism
```

### Login & Access Control
```
feat(login): ✨ add custom kick messages per denial reason
fix(login): 🐛 fix race condition in login guard event handler
refactor(login): ♻️ extract access checker to separate service
```

### MOTD System
```
feat(motd): ✨ add countdown timer when server closing soon
fix(motd): 🐛 fix color code parsing for custom MOTD format
style(motd): 💎 improve MOTD formatter code readability
```

### Warnings & Auto-Kick
```
feat(warnings): ✨ add configurable warning intervals
fix(warnings): 🐛 fix warning broadcaster not respecting exempt permission
perf(warnings): ⚡ reduce tick scheduler overhead
```

### Permissions
```
feat(permissions): ✨ add LuckPerms soft dependency detection
fix(permissions): 🐛 fix timeout protection in permission checker
docs(permissions): 📚 document all permission nodes in PERMISSIONS.md
```

### Localization
```
feat(i18n): ✨ add Spanish language support (es_es.json)
fix(i18n): 🐛 fix time format for French locale
refactor(text): ♻️ improve message formatter placeholder handling
```

### Build & Release
```
build(gradle): 📦 update Forge to 47.4.10
ci(workflow): 🤖 add automated release workflow for Gitea
chore(release): 🔧 prepare v1.0.1 release
```

### Documentation
```
docs(installation): 📚 add troubleshooting section
docs(examples): 📚 add real-world configuration examples
docs(changelog): 📚 update changelog for v1.0.2
```

## Commit Message Rules

### Title (Required)
- **Format:** `type(scope): emoji description`
- **Length:** Max 72 characters
- **Language:** English only
- **Case:** Lowercase for type and scope
- **Description:** Start with verb in past tense (added, fixed, updated)
- **Emoji:** Include relevant emoji after scope

### Body (Optional but Recommended)
- Add blank line after title
- Use bullet points for multiple changes
- Explain **what** and **why**, not how
- Reference issues/PRs if applicable
- Provide as much detail as possible

### Footer (Optional)
- Breaking changes: `BREAKING CHANGE: description`
- Close issues: `Closes #123`
- Co-authors: `Co-authored-by: name <email>`

## Multi-Feature Commits

When committing multiple changes:

```
feat(command,config): ✨ add support for per-player schedule overrides

- Added new command `/hours player <name> set schedule`
- Updated config to support player-specific sections
- Added permission node playhours.admin.player
- Updated documentation with new feature
```

## Breaking Changes

```
feat(config)!: ✨ redesign configuration structure for better clarity

BREAKING CHANGE: Configuration file structure has changed.
Old format will not work. Please regenerate config or migrate manually.

- Separated general settings from day-specific settings
- Renamed `default_periods` to `defaults.periods`
- Moved timezone from general to defaults section
```

## Common Patterns

### Bug Fixes
```
fix(login): 🐛 fix player kicked immediately after login

- Fixed race condition in LoginGuard event handler
- Added delay before checking schedule on login
- Resolves issue where players couldn't join during open hours
```

### New Features
```
feat(exceptions): ✨ add recurring date exceptions support

- Support weekly/monthly recurring exceptions
- Add new configuration syntax for recurrence
- Update exception handler to process recurring dates
- Add validation for recurring patterns
```

### Refactoring
```
refactor(core): ♻️ extract schedule logic into dedicated service

- Created ScheduleService to centralize schedule operations
- Moved calculation logic from LoginGuard to ScheduleCalculator
- Improved testability and separation of concerns
```

### Performance
```
perf(schedule): ⚡ cache timezone conversions to reduce CPU usage

- Implement timezone conversion cache
- Reduce ZonedDateTime allocations
- Benchmarked 40% improvement in schedule checks
```

## Anti-Patterns (DON'T)

❌ `updated stuff`
❌ `fix bug`
❌ `feat: added new feature` (missing scope)
❌ `FIX(LOGIN): Fixed login` (wrong case)
❌ `feat(command): Add feature` (missing emoji)
❌ `wip` (not descriptive)

## Good Examples (DO)

✅ `feat(command): ✨ add /hours status command with detailed server info`
✅ `fix(schedule): 🐛 fix midnight-spanning time range calculation`
✅ `docs(readme): 📚 update quick start guide with v1.0.1 changes`
✅ `perf(events): ⚡ optimize tick scheduler to run every 20 ticks instead of 1`
✅ `chore(release): 🔧 prepare v1.0.2`

## Forge Mod Specific Tips

- Always test changes on a running server before committing
- Update relevant documentation when changing features
- Update language files when adding new messages
- Bump version in build.gradle for releases
- Update CHANGELOG.md before release commits
- Run `./gradlew build` to ensure no build errors