---
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