PlayHours/docs/RELEASE.md

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

scripts\release.bat

Linux/macOS

./scripts/release.sh

Option 2: Using Gradle Tasks

1. Bump version (optional):

   ./gradlew bumpVersion
   

2. Create release:

   ./gradlew release
   

Option 3: Manual Steps

1. Update version in gradle.properties:

   mod_version=1.0.1
   

2. Build the project:

   ./gradlew clean build
   

3. Create and push git tag:

   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:

   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:

./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:

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