worldhopper/scripts/README.md

# CI/CD Scripts

This directory contains scripts used by the Woodpecker CI pipeline and for local development.

## version.sh

Extracts version information from git tags. Outputs two lines: a version name and a version code (for Android).

### Usage

```bash
sh scripts/version.sh
```

**Output (two lines):**
1. **Version name** — `X.Y.Z` if the current commit is tagged `vX.Y.Z`, `X.Y.Z-rc.N` if tagged `vX.Y.Z-rc.N`, otherwise `X.Y.Z-dev-<short sha>` based on the latest version tag (or `0.0.0-dev-<sha>` if no tags exist)
2. **Version code** — total git commit count (monotonically increasing integer required by Android)

### Examples

Use in a Flutter build:
```bash
VERSION_NAME=$(sh scripts/version.sh | head -1)
VERSION_CODE=$(sh scripts/version.sh | tail -1)
flutter build apk --release --build-name="$VERSION_NAME" --build-number="$VERSION_CODE"
```

Quick check:
```bash
$ sh scripts/version.sh
1.2.3
42
```

### Notes

- Uses `/bin/sh` for portability (works in Alpine CI images)
- Handles shallow clones by fetching tags if needed
- When no version tag exists, falls back to `0.0.0-dev-<sha>`

## generate-changelog.sh

Generates a formatted changelog from git history by grouping commits by type.

### Usage

```bash
./scripts/generate-changelog.sh <tag> [output-file]
```

**Arguments:**
- `tag` (required): Git tag to generate changelog for (e.g., `v1.0.0`)
- `output-file` (optional): Output file path (default: `CHANGELOG.md`)

**Environment Variables:**
- `CI_FORGE_URL`: Base URL of git forge (used for comparison links)
- `CI_REPO`: Repository path (used for comparison links)

### Examples

Generate changelog for a specific tag:
```bash
./scripts/generate-changelog.sh v1.0.0
```

Generate changelog with custom output file:
```bash
./scripts/generate-changelog.sh v1.2.3 release-notes.md
```

Test changelog generation locally:
```bash
# Create a test tag (don't push)
git tag v0.0.1-test

# Generate changelog
./scripts/generate-changelog.sh v0.0.1-test

# Review output
cat CHANGELOG.md

# Clean up test tag
git tag -d v0.0.1-test
```

### Commit Format

The script recognizes conventional commit prefixes:

- `feat:` or `feat(scope):` → Features section
- `fix:` or `fix(scope):` → Bug Fixes section
- `chore:` or `chore(scope):` → Chores section
- `refactor:` or `refactor(scope):` → Refactoring section
- All other commits → Other Changes section

### Output Format

The generated changelog includes:
- Release title
- Commits grouped by type with emoji headers
- Short commit hashes for reference
- Full changelog comparison link (when in CI)

Example output:
```markdown
# Release v1.0.0

## ✨ Features
- add user authentication (abc1234)
- implement dark mode (def5678)

## 🐛 Bug Fixes
- fix crash on startup (ghi9012)

## 📝 Other Changes
- update README (jkl3456)

---
**Full Changelog**: https://forgejo.example.com/user/repo/compare/v0.9.0...v1.0.0
```

## create-release.sh

Creates a Forgejo release using the `tea` CLI tool with changelog and APK attachment.

### Usage

```bash
./scripts/create-release.sh <tag> <apk-file> <changelog-file>
```

**Arguments:**
- `tag` (required): Git tag for the release (e.g., `v1.0.0`)
- `apk-file` (required): Path to the APK file to attach as release asset
- `changelog-file` (required): Path to the changelog file to use as release notes

**Required Environment Variables:**
- `FORGEJO_TOKEN`: Personal access token with repo permissions
- `CI_FORGE_URL`: Base URL of Forgejo instance (e.g., `https://forgejo.example.com`)
- `CI_REPO_OWNER`: Repository owner/organization name
- `CI_REPO_NAME`: Repository name

### Examples

Create a release (requires valid Forgejo credentials):
```bash
export FORGEJO_TOKEN="your-token-here"
export CI_FORGE_URL="https://forgejo.example.com"
export CI_REPO_OWNER="username"
export CI_REPO_NAME="worldhopper"

./scripts/create-release.sh v1.0.0 worldhopper-v1.0.0.apk CHANGELOG.md
```

### Prerequisites

The `tea` CLI must be installed:
```bash
# Install tea CLI
# See: https://gitea.com/gitea/tea

# On macOS with Homebrew
brew install tea

# On Linux
wget https://dl.gitea.io/tea/latest/tea-linux-amd64
chmod +x tea-linux-amd64
sudo mv tea-linux-amd64 /usr/local/bin/tea
```

### Output

The script will:
1. Configure tea with Forgejo credentials
2. Create a release with the specified tag (tags matching `*-rc.*` are marked as pre-releases)
3. Set the release title to "Worldhopper {TAG}"
4. Use the changelog file content as release description
5. Attach the APK file as a downloadable release asset
6. Print the release URL on success

## CI/CD Integration

These scripts are used by `.woodpecker.yml` for automated releases. The pipeline:

1. **Build Stage**: Builds the Flutter APK
2. **Changelog Stage**: Runs `generate-changelog.sh` to create release notes
3. **Release Stage**: Runs `create-release.sh` to publish to Forgejo

See the root `.woodpecker.yml` file for the complete integration example.