# PlayHours Release Guide

This guide explains how to create releases for PlayHours, both manually and automatically.

## Prerequisites

- Git repository with proper remote configuration
- Gradle build system
- Access to your Gitea instance
- Java 17+ installed

## Manual Release Process

### Option 1: Using Release Scripts

#### Windows
```cmd
scripts\release.bat
```

#### Linux/macOS
```bash
./scripts/release.sh
```

### Option 2: Using Gradle Tasks

1. **Bump version** (optional):
   ```bash
   ./gradlew bumpVersion
   ```

2. **Create release**:
   ```bash
   ./gradlew release
   ```

### Option 3: Manual Steps

1. **Update version** in `gradle.properties`:
   ```
   mod_version=1.0.1
   ```

2. **Build the project**:
   ```bash
   ./gradlew clean build
   ```

3. **Create and push git tag**:
   ```bash
   git tag -a v1.0.1 -m "Release v1.0.1"
   git push origin main
   git push origin v1.0.1
   ```

4. **Create release on Gitea**:
   - Go to your repository on Gitea
   - Click "Releases" → "New Release"
   - Select tag `v1.0.1`
   - Upload JAR file from `build/libs/playhours-1.0.1.jar`
   - Add release notes

## Automated Release Process

### Using Gitea Actions

The project includes automated workflows that trigger on:

1. **Tag pushes**: When you push a tag starting with `v` (e.g., `v1.0.1`)
2. **Manual dispatch**: Through the Gitea Actions interface

#### Setting up Gitea Actions

1. **Enable Actions** in your Gitea repository settings
2. **Configure secrets** (if needed):
   - `GITEA_TOKEN`: For Gitea API access
   - `GITEA_API_URL`: Your Gitea instance URL (optional, defaults to your current instance)

#### Workflow Files

- `.gitea/workflows/ci.yml`: Continuous integration on pushes/PRs
- `.gitea/workflows/release.yml`: Automated release builds

### Automated Release Steps

1. **Create and push a tag**:
   ```bash
   git tag -a v1.0.1 -m "Release v1.0.1"
   git push origin v1.0.1
   ```

2. **Gitea Actions will automatically**:
   - Build the project
   - Create a release
   - Upload the JAR file
   - Generate release notes

## Version Management

### Semantic Versioning

PlayHours uses semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Version Bumping

Use the Gradle task to automatically bump the patch version:
```bash
./gradlew bumpVersion
```

For major/minor version changes, manually edit `gradle.properties`.

## Release Checklist

Before creating a release:

- [ ] Update `CHANGELOG.md` with new features/fixes
- [ ] Update version in `gradle.properties`
- [ ] Test the build locally
- [ ] Commit all changes
- [ ] Create and push tag
- [ ] Verify release on Gitea

## Troubleshooting

### Common Issues

1. **Build fails**: Check Java version (17+) and Gradle configuration
2. **Tag already exists**: Delete the tag and recreate, or use a new version
3. **Push fails**: Check git remote configuration and permissions
4. **Actions don't trigger**: Ensure Actions are enabled in repository settings

### Manual Recovery

If automated release fails:

1. Build manually: `./gradlew clean build`
2. Create release manually on Gitea
3. Upload JAR from `build/libs/`

## Advanced Configuration

### Custom Release Notes

Edit the release body template in `build.gradle`:
```gradle
body = """
## PlayHours v${mod_version}
Your custom release notes here...
"""
```

### Custom Gitea Instance

If your Gitea instance is not at the default URL, set the `GITEA_API_URL` secret:
- Go to repository settings → Secrets
- Add `GITEA_API_URL` with your instance URL (e.g., `https://your-gitea.com`)

## Security Notes

- Never commit API tokens or passwords
- Use repository secrets for sensitive data
- Regularly rotate access tokens
- Review release permissions carefully