266 lines
7.2 KiB
Markdown
266 lines
7.2 KiB
Markdown
# 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 `docs/index.html` footer version
|
|
6. Create/update rockspec file: `flexlove-{version}-1.rockspec`
|
|
7. Create a git commit: `v{version} release`
|
|
8. Create a git tag: `v{version}`
|
|
9. Push changes and tag to GitHub
|
|
|
|
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
|
|
|
|
The script will display next steps for publishing to LuaRocks (see [LUAROCKS_PUBLISHING.md](LUAROCKS_PUBLISHING.md)).
|
|
|
|
### 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`
|
|
- [ ] Rockspec created/updated (automated by `make-tag.sh`)
|
|
- [ ] 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
|
|
- [ ] Published to LuaRocks (`luarocks upload flexlove-{version}-1.rockspec`)
|
|
|
|
## 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
|
|
|
|
## Publishing to LuaRocks
|
|
|
|
After creating a GitHub release, publish to LuaRocks for easy installation:
|
|
|
|
### First-Time Setup
|
|
|
|
1. Create a LuaRocks account at [https://luarocks.org/register](https://luarocks.org/register)
|
|
2. Get your API key from [https://luarocks.org/settings/api-keys](https://luarocks.org/settings/api-keys)
|
|
3. Configure it locally:
|
|
```bash
|
|
luarocks config api-key YOUR_API_KEY_HERE
|
|
```
|
|
|
|
### Publishing a Release
|
|
|
|
The `make-tag.sh` script automatically creates the rockspec file. After the tag is pushed:
|
|
|
|
```bash
|
|
# Upload to LuaRocks
|
|
luarocks upload flexlove-{version}-1.rockspec
|
|
|
|
# Example for version 0.5.5:
|
|
luarocks upload flexlove-0.5.5-1.rockspec
|
|
```
|
|
|
|
### Verifying Publication
|
|
|
|
```bash
|
|
# Search for your package
|
|
luarocks search flexlove
|
|
|
|
# Test installation
|
|
luarocks install flexlove
|
|
```
|
|
|
|
For detailed instructions, see [LUAROCKS_PUBLISHING.md](LUAROCKS_PUBLISHING.md).
|
|
|
|
## Automated Releases (Future)
|
|
|
|
Consider adding GitHub Actions workflow to automate:
|
|
- Version extraction
|
|
- Release package creation
|
|
- Documentation deployment
|
|
- GitHub release creation
|
|
- LuaRocks publishing
|
|
|
|
See `.github/workflows/release.yml` (to be created)
|