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:

```bash
./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

```bash
$ ./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:

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

Also update `README.md` first line:
```markdown
# FlexLöve v0.3.0
```

### 2. Commit and Tag

```bash
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:

```bash
./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

```bash
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](https://semver.org/):

- **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`:

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

```bash
# 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)