FlexLove/RELEASE.md

FlexLöve Release Process

This document describes how to create and publish a new release of FlexLöve.

Automated Release (Recommended)

The easiest way to create a release is using the automated script:

./scripts/make-tag.sh

This interactive script will:

1. Show your current version
2. Ask you to select: Major / Minor / Patch / Custom version bump
3. Calculate the new version (resetting lower components to 0)
4. Update FlexLove.lua with the new version
5. Update README.md first line with the new version
6. Create a git commit: v{version} release
7. Create a git tag: v{version}
8. Prompt you to push the changes

After pushing the tag, GitHub Actions automatically:

• Archives previous documentation
• Generates new documentation
• Creates release package with SHA256 checksums
• Publishes GitHub release with download assets

Example Usage

$ ./scripts/make-tag.sh

═══════════════════════════════════════
   FlexLöve Version Bump & Tag Tool   
═══════════════════════════════════════

Current version: v0.2.0

Select version bump type:
  1) Major (breaking changes)     0.2.0 → 1.0.0
  2) Minor (new features)          0.2.0 → 0.3.0
  3) Patch (bug fixes)             0.2.0 → 0.2.1
  4) Custom version
  5) Cancel

Enter choice (1-5): 2

New version: v0.3.0

This will:
  1. Update FlexLove.lua → flexlove._VERSION = "0.3.0"
  2. Update README.md → first line version
  3. Stage changes for commit
  4. Create git tag v0.3.0

Proceed? (y/n) y

✓ Version bump complete!

Next steps:
  1. Push commit and tag:
     git push && git push origin v0.3.0

  2. GitHub Actions will automatically:
     • Archive previous documentation
     • Generate new documentation
     • Create release package with checksums
     • Publish GitHub release

Manual Release Workflow

If you need more control, follow these steps:

1. Update Version

Edit FlexLove.lua and update the version:

flexlove._VERSION = "0.3.0"  -- Update this line

Also update README.md first line:

# FlexLöve v0.3.0

2. Commit and Tag

git add FlexLove.lua README.md
git commit -m "v0.3.0 release"
git tag -a v0.3.0 -m "Release version 0.3.0"
git push && git push origin v0.3.0

3. GitHub Actions Takes Over

Once you push the tag, the automated workflow handles everything else.

Local Release Package (Optional)

To create a local release package without GitHub Actions:

./scripts/create-release.sh

Output files:

• releases/flexlove-v{version}.zip
• releases/flexlove-v{version}.zip.sha256

Verify Local Package

cd releases
shasum -a 256 -c flexlove-v0.3.0.zip.sha256
# Expected: flexlove-v0.3.0.zip: OK

Release Checklist

• Version updated in FlexLove.lua
• Documentation regenerated (./scripts/generate_docs.sh)
• Changes committed and pushed
• Release package created (./scripts/create-release.sh)
• Checksum verified (shasum -a 256 -c *.sha256)
• Release package tested
• Git tag created and pushed
• GitHub release published with zip and checksum files

Versioning

FlexLöve follows Semantic Versioning:

• MAJOR version: Incompatible API changes
• MINOR version: New functionality (backwards-compatible)
• PATCH version: Bug fixes (backwards-compatible)

Example: 0.2.0 → 0.2.1 (bug fix) or 0.3.0 (new feature)

What Gets Released

The release package includes only the files needed to use FlexLöve:

✅ Included:

• FlexLove.lua - Main library
• modules/ - All module files
• LICENSE - License terms
• README.md - Installation instructions

❌ Not included:

• docs/ - Documentation (hosted on GitHub Pages)
• examples/ - Example code (available in repository)
• testing/ - Test suite
• themes/ - Theme examples
• Development tools

Users who want examples, documentation source, or development tools should clone the full repository.

Checksum Verification

Every release includes a SHA256 checksum file for security verification.

For Developers (Creating Release)

The checksum is automatically generated when running ./scripts/create-release.sh:

./scripts/create-release.sh
# Creates:
# - releases/flexlove-v0.3.0.zip
# - releases/flexlove-v0.3.0.zip.sha256

# Verify before publishing
cd releases
shasum -a 256 -c flexlove-v0.3.0.zip.sha256
# Output: flexlove-v0.3.0.zip: OK

For End Users (Downloading Release)

After downloading a release from GitHub:

# Download both files:
# - flexlove-v0.3.0.zip
# - flexlove-v0.3.0.zip.sha256

# Verify integrity
shasum -a 256 -c flexlove-v0.3.0.zip.sha256

# If OK, safe to use
unzip flexlove-v0.3.0.zip

macOS/Linux: Use shasum -a 256 -c
Windows: Use certutil -hashfile flexlove-v0.3.0.zip SHA256 and compare manually

Automated Releases (Future)

Consider adding GitHub Actions workflow to automate:

• Version extraction
• Release package creation
• Documentation deployment
• GitHub release creation

See .github/workflows/release.yml (to be created)