v0.2.1 release

docs/WORKFLOW.md

@@ -0,0 +1,153 @@
+# Documentation Workflow
+
+## Overview
+
+FlexLöve's documentation system automatically manages versioning and archival. When you generate new documentation, the previous version is automatically archived.
+
+## How It Works
+
+### 1. Manual Documentation Updates (No Version Change)
+
+When you update annotations without bumping the version:
+
+```bash
+./scripts/generate_docs.sh
+```
+
+**What happens:**
+- Script detects current version (e.g., v0.2.0) from `docs/api.html`
+- Compares with `FlexLove.lua` version
+- If versions match: **Overwrites** `docs/api.html` (same version)
+- Previous archived version remains unchanged
+
+**Use case:** You added better documentation, fixed typos, or improved examples without releasing a new version.
+
+### 2. Version Bump (New Release)
+
+When you bump the version in `FlexLove.lua`:
+
+```bash
+# 1. Update version in FlexLove.lua
+# flexlove._VERSION = "0.3.0"
+
+# 2. Generate documentation
+./scripts/generate_docs.sh
+```
+
+**What happens:**
+- Script detects old version (v0.2.0) from `docs/api.html`
+- Compares with new version (v0.3.0) from `FlexLove.lua`
+- **Archives** old `docs/api.html` → `docs/versions/v0.2.0/api.html`
+- Generates new `docs/api.html` for v0.3.0
+
+### 3. Automated Release (via GitHub Actions)
+
+When you push a git tag:
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+**What happens:**
+1. GitHub Actions workflow triggers
+2. Archives previous documentation version
+3. Generates new documentation for v0.3.0
+4. Commits both archived and new docs to repository
+5. Creates release package with checksums
+6. Creates GitHub release with assets
+
+## Directory Structure
+
+```
+docs/
+├── api.html                    # Always the LATEST version
+├── index.html                  # Landing page
+└── versions/
+    ├── v0.1.0/
+    │   └── api.html           # Documentation for v0.1.0
+    ├── v0.2.0/
+    │   └── api.html           # Documentation for v0.2.0
+    └── v0.3.0/
+        └── api.html           # Documentation for v0.3.0
+```
+
+## Version Detection
+
+The system automatically detects versions by:
+1. **Current docs version**: Reads from `docs/api.html` header (`FlexLöve v0.2.0`)
+2. **Code version**: Reads from `FlexLove.lua` (`flexlove._VERSION = "0.2.0"`)
+
+### Behavior Matrix
+
+| Old Version | New Version | Action |
+|-------------|-------------|--------|
+| v0.2.0      | v0.2.0      | Overwrite current (same version update) |
+| v0.2.0      | v0.3.0      | Archive v0.2.0, generate v0.3.0 |
+| None        | v0.2.0      | Generate v0.2.0 (first time) |
+
+## Examples
+
+### Scenario 1: Fix Documentation Typo
+
+```bash
+# Fix typo in annotations
+# Version still 0.2.0 in FlexLove.lua
+
+./scripts/generate_docs.sh
+# Output: "Same version (v0.2.0), will overwrite current documentation"
+# Result: docs/api.html updated, no archival
+```
+
+### Scenario 2: Release New Version
+
+```bash
+# Update FlexLove.lua
+# flexlove._VERSION = "0.3.0"
+
+./scripts/generate_docs.sh
+# Output: "Found previous version v0.2.0, archiving before generating new docs..."
+# Output: "✓ Archived previous documentation to docs/versions/v0.2.0/"
+# Result: 
+#   - docs/versions/v0.2.0/api.html (archived)
+#   - docs/api.html (new v0.3.0)
+```
+
+### Scenario 3: Automated Release
+
+```bash
+# Tag and push
+git tag v0.3.0
+git push origin v0.3.0
+
+# GitHub Actions will:
+# 1. Archive v0.2.0 automatically
+# 2. Generate v0.3.0 docs
+# 3. Commit both to repository
+# 4. Create GitHub release
+```
+
+## Benefits
+
+✅ **No manual archival needed** - Automatically handled  
+✅ **Safe overwrites** - Same version updates won't create duplicate archives  
+✅ **Version history preserved** - All previous versions accessible  
+✅ **Seamless workflow** - Just run `./scripts/generate_docs.sh`  
+✅ **Automated releases** - Tag and forget
+
+## Version Dropdown
+
+Users can access any version via the dropdown in the documentation header:
+- Current version shows "(Latest)" badge
+- Previous versions listed chronologically
+- Click to navigate to archived documentation
+
+## Manual Archival (If Needed)
+
+If you ever need to manually archive a version:
+
+```bash
+./scripts/archive-docs.sh
+```
+
+This creates `docs/versions/v{version}/api.html` based on the current `FlexLove.lua` version.