# Wild Cloud Versioning

Wild Cloud uses a single VERSION file at the monorepo root. All components (API, CLI, Web, package) share the same version number.

## Release Channels

### Stable
Versioned releases following [Semantic Versioning](https://semver.org/). Tagged immutably in git as `v{VERSION}`. Published to the `stable` APT suite.

### Edge
Rolling releases built from HEAD. No version bump required — the version is derived from the build timestamp and git commit (`0.0.0~edge.{timestamp}.{hash}`). The `edge` git tag is force-pushed to HEAD on each build. Published to the `edge` APT suite as a pre-release.

## Stable Release Workflow

```bash
# 1. Bump the version
echo "0.2.0" > VERSION

# 2. Update CHANGELOG.md — rename [Unreleased] to [0.2.0] with today's date,
#    add a fresh [Unreleased] section above it

# 3. Commit the version bump
git add VERSION CHANGELOG.md
git commit -m "Release v0.2.0"

# 4. Build and release — tags HEAD as v0.2.0, pushes tag, publishes Gitea
#    release with changelog notes, and deploys to stable APT
cd dist
make package-all && make release
```

`make release` creates the `v{VERSION}` git tag automatically. If the tag already exists, it skips tagging and only updates the Gitea release assets.

## Edge Release Workflow

```bash
cd dist
make package-all && make release-edge
```

This force-pushes the `edge` git tag to HEAD, creates or updates the "edge" pre-release on Gitea, and deploys to the edge APT suite. No version file changes needed.

## Semver Guidelines (pre-1.0)

- **MINOR** (`0.x`): new features, any breaking changes
- **PATCH** (`0.1.x`): bug fixes, small improvements

## Version in Components

Version is injected at build time via `-ldflags`:

```makefile
go build -ldflags="-X main.Version=$(VERSION)"
```

The web app reads its version from the API at runtime.

## Makefile Quick Reference

```bash
make help          # Show all targets and current version info
make package-all   # Build all .deb packages
make release       # Stable release: tag + Gitea + APT stable
make release-edge  # Edge release: force-tag + Gitea + APT edge
```

Required environment variables (see `.envrc`):
- `GITEA_TOKEN` — for Gitea release publishing
- `APTLY_URL` / `APTLY_PASS` — for APT deployment (optional; skipped if unset)