opensync / rules

---
description: Changelog management for GitHub Releases automation
globs: changelog.md
alwaysApply: false
---

# Changelog Management for GitHub Releases

This project uses a GitHub Action that automatically creates GitHub Releases from changelog.md. Follow this format exactly.

## Format Requirements

The changelog MUST follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format with these rules:

### Version Header Format

```
## [X.X.X] - YYYY-MM-DD
```

- Version number in brackets: `[1.0.0]`
- Date in ISO format: `2025-01-20`
- Hyphen between version and date
- The GitHub Action parses this exact pattern to create releases

### Section Headers

Use these standard headers under each version:

```
### Added
### Changed
### Fixed
### Removed
### Deprecated
### Security
```

### Unreleased Section

Always keep an `[Unreleased]` section at the top for work in progress:

```markdown
## [Unreleased]

### Added
- New feature being developed

## [1.0.0] - 2025-01-20
...
```

## How to Create a Release

When ready to release:

1. Create a new version section with today's date
2. Move items from `[Unreleased]` to the new version
3. Keep `[Unreleased]` section (can be empty)
4. Commit and push to main

### Before Release

```markdown
## [Unreleased]

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix Z

## [0.1.0] - 2025-01-17
...
```

### After Release

```markdown
## [Unreleased]

## [1.0.0] - 2025-01-20

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix Z

## [0.1.0] - 2025-01-17
...
```

## Version Number Guidelines

Use semantic versioning:

| Change Type | Version Bump | Example |
|-------------|--------------|---------|
| Breaking changes | Major | 1.0.0 -> 2.0.0 |
| New features (backwards compatible) | Minor | 1.0.0 -> 1.1.0 |
| Bug fixes only | Patch | 1.0.0 -> 1.0.1 |

## When Adding Changelog Entries

- Add entries under `[Unreleased]` as you work
- Group by category (Added, Changed, Fixed, etc.)
- Use bullet points with clear, concise descriptions
- No need to add dates until creating a release
- Include issue/PR references when relevant: `(fixes #123)`

## Commit Message for Releases

When creating a release version, use this commit format:

```
release: v1.0.0
```

This helps identify release commits in git history.

## What Happens on Push

When you push changelog.md changes to main:

1. GitHub Action detects the change
2. Parses the latest `## [X.X.X] - YYYY-MM-DD` version
3. Extracts content between that version and the next `##`
4. Creates a GitHub Release with tag `vX.X.X`
5. Creates a GitHub Discussion in the Changelog category
6. Skips both if that release already exists

**Important:** Only versioned sections trigger releases. `[Unreleased]` content is ignored until moved to a version.

## Example Entry

```markdown
## [1.2.0] - 2025-01-21

### Added
- Real-time Platform Stats leaderboard on Login page
- Discord and Support icons in footer (fixes #5)

### Fixed
- Provider display showing "unknown" for OAuth sessions (fixes #2)
- Auth session persistence on page refresh (fixes #1)

### Changed
- Removed user email from dropdown menus for cleaner UX
```