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 4 build profile packages (minimal, slim, default, full) with SHA256 checksums
• Publishes GitHub release with all profile packages

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 Packages (Optional)

To create local release packages without GitHub Actions:

./scripts/create-profile-packages.sh

Output files (for version 0.3.0):

• releases/flexlove-minimal-v0.3.0.zip + .sha256
• releases/flexlove-slim-v0.3.0.zip + .sha256
• releases/flexlove-default-v0.3.0.zip + .sha256
• releases/flexlove-full-v0.3.0.zip + .sha256

Verify Local Packages

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

Release Checklist

• Version updated in FlexLove.lua
• Documentation regenerated (./scripts/generate_docs.sh)
• Changes committed and pushed
• Profile packages created (./scripts/create-profile-packages.sh)
• All checksums verified (cd releases && shasum -a 256 -c *.sha256)
• All profile packages tested
• Git tag created and pushed
• GitHub release published with all 4 profile packages and checksums

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

FlexLöve is released as 4 separate profile packages, each optimized for different use cases:

Profile Packages

Each profile package includes:

✅ Included:

• FlexLove.lua - Main library
• modules/ - Profile-specific module files only
• LICENSE - License terms
• README.md - Profile-specific installation instructions
• themes/ - (default and full profiles only)

❌ Not included:

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

Package Sizes

Profile	Modules	Approximate Size
Minimal	16 core modules	~60% of full
Slim	21 modules	~80% of full
Default	23 modules + themes	~95% of full
Full	24 modules + themes	100%

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

Checksum Verification

Every profile package includes a SHA256 checksum file for security verification.

For Developers (Creating Release)

The checksums are automatically generated when running ./scripts/create-profile-packages.sh:

./scripts/create-profile-packages.sh
# Creates 4 profile packages with checksums:
# - releases/flexlove-minimal-v0.3.0.zip + .sha256
# - releases/flexlove-slim-v0.3.0.zip + .sha256
# - releases/flexlove-default-v0.3.0.zip + .sha256
# - releases/flexlove-full-v0.3.0.zip + .sha256

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

For End Users (Downloading Release)

After downloading your chosen profile from GitHub:

# Example: Verify the default profile
shasum -a 256 -c flexlove-default-v0.3.0.zip.sha256

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

macOS/Linux: Use shasum -a 256 -c
Windows: Use certutil -hashfile flexlove-<profile>-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)