From e21453d1944dd40a9758b6ea11ddb7a5ce08db29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mr=C2=A4KayJayDee?= Date: Fri, 24 Oct 2025 00:16:10 +0200 Subject: [PATCH] =?UTF-8?q?chore(cursor):=20=F0=9F=94=A7=20add=20cursor=20?= =?UTF-8?q?rules=20for=20changelog=20and=20commit=20message=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added changelog.mdc rule for CHANGELOG.md management - Defines structure with newest releases at top - Integrates with Gitea release workflow automation - Provides section headers and examples - Added commits.mdc rule for standardized commit formatting - Defines type(scope): emoji description format - Includes mod-specific scopes (command, config, schedule, etc.) - Provides examples for each feature area - Documents emoji conventions for each commit type - Both rules ensure consistency across development workflow --- .cursor/rules/changelog.mdc | 99 +++++++++++++++ .cursor/rules/commits.mdc | 247 ++++++++++++++++++++++++++++++++++++ 2 files changed, 346 insertions(+) create mode 100644 .cursor/rules/changelog.mdc create mode 100644 .cursor/rules/commits.mdc diff --git a/.cursor/rules/changelog.mdc b/.cursor/rules/changelog.mdc new file mode 100644 index 0000000..0826291 --- /dev/null +++ b/.cursor/rules/changelog.mdc @@ -0,0 +1,99 @@ +--- +globs: CHANGELOG.md +alwaysApply: false +--- + +# Changelog Management + +## Overview +The changelog is located at `docs/CHANGELOG.md` and follows a structured format that integrates with the automated release workflow. + +## Structure +- Newest releases at the **TOP** of the file +- Each release has a `## [version] - date` header +- Follow semantic versioning: `[MAJOR.MINOR.PATCH]` +- Use ISO date format: `YYYY-MM-DD` + +## Adding New Releases + +### Before Creating a Release +1. **Update `docs/CHANGELOG.md`** - Add new version section at the TOP +2. **Use this format:** +```markdown +## [X.Y.Z] - YYYY-MM-DD + +### ๐ŸŽ‰ Added +- New features + +### ๐Ÿ”ง Changed +- Modifications to existing features + +### ๐Ÿ› Fixed +- Bug fixes + +### ๐Ÿ—‘๏ธ Removed +- Deprecated features removed + +### โš ๏ธ Breaking Changes +- Changes that break backward compatibility +``` + +### Section Headers (pick what's relevant) +- `### ๐ŸŽ‰ Added` - New features +- `### ๐Ÿ”ง Changed` - Changes to existing functionality +- `### ๐Ÿ› Fixed` - Bug fixes +- `### ๐Ÿ—‘๏ธ Removed` - Removed features +- `### โš ๏ธ Breaking Changes` - Breaking changes +- `### ๐Ÿ”’ Security` - Security fixes +- `### ๐Ÿ“š Documentation` - Documentation changes +- `### โšก Performance` - Performance improvements + +## Workflow Integration + +The release workflow (`.gitea/workflows/release.yml`) automatically: +1. Extracts the **latest/topmost** changelog section (between first `##` and second `##`) +2. Uses it as the release notes on Gitea +3. Attaches the built JAR file + +**Only the most recent section is extracted** - previous releases stay in the file for history. + +## Example + +```markdown +# Changelog + +## [1.0.2] - 2025-10-24 + +### ๐Ÿ› Fixed +- Fixed permission check timeout issue +- Resolved MOTD formatting bug + +### โšก Performance +- Optimized schedule calculation + +## [1.0.1] - 2025-10-23 + +### ๐ŸŽ‰ Added +- Added French language support +- New command `/hours status` + +### ๐Ÿ”ง Changed +- Improved error messages +``` + +## Release Process + +1. **Update changelog:** Add new `## [X.Y.Z]` section at top of `docs/CHANGELOG.md` +2. **Commit changes:** `git add -A && git commit -m "docs(changelog): update for vX.Y.Z"` +3. **Run release script:** `./release.sh patch` (or `minor`/`major`) +4. **Workflow handles the rest:** Extracts changelog, builds, creates release + +## Important Rules + +- โœ… **DO:** Add new releases at the TOP +- โœ… **DO:** Use consistent section headers +- โœ… **DO:** Include date and version number +- โœ… **DO:** Keep old releases for history +- โŒ **DON'T:** Edit old release sections +- โŒ **DON'T:** Delete previous releases +- โŒ **DON'T:** Add entries at the bottom diff --git a/.cursor/rules/commits.mdc b/.cursor/rules/commits.mdc new file mode 100644 index 0000000..c3d4c05 --- /dev/null +++ b/.cursor/rules/commits.mdc @@ -0,0 +1,247 @@ +--- +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 ` + +## Multi-Feature Commits + +When committing multiple changes: + +``` +feat(command,config): โœจ add support for per-player schedule overrides + +- Added new command `/hours player 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