Release Process

All releases are driven by Git tags, with CI handling builds and distribution automatically.

Core principle: Manual tag -> Automatic build -> Automatic release -> Automatic sync.

Developers only need to do one thing: create a properly formatted tag at the right time. The rest --- building, packaging, releasing, and cross-repository syncing --- is all handled automatically by GitHub Actions pipelines.

---

Part 1: Version Number Specification

Semantic Versioning (SemVer)

Format: MAJOR.MINOR.PATCH (e.g., 0.2.7)

Position	When to Increment	Example
MAJOR	Incompatible API changes, breaking changes	0.x.x -> 1.0.0
MINOR	Backward-compatible new features	0.2.x -> 0.3.0
PATCH	Backward-compatible bug fixes	0.2.6 -> 0.2.7

Pre-release identifiers are appended to the version number:

• -rc1: Release Candidate --- feature-complete, final validation stage
• -beta1: Public beta --- mostly feature-complete but may have known issues
• -alpha1: Internal test version --- features incomplete

Tag Naming Convention

• Format: v{MAJOR}.{MINOR}.{PATCH} (e.g., v0.2.7)
• Pre-release: v0.3.0-rc1
• All repositories use the v* prefix consistently

Version Number Storage Locations

Repository	Version Source	Notes
Presto main app	Git tag	git describe --tags -> -ldflags injection, no source file
Templates	manifest.json version field	Must be manually updated before tagging
Docker images	Auto-generated from tag	+ . + latest

---

Part 2: Presto Main App Release

Pre-Release Checklist

• [ ] All features merged to main
• [ ] Local make build succeeds
• [ ] security-scan has no high-severity vulnerabilities (govulncheck + npm audit)
• [ ] README updated (if new features were added)

Release Steps

# 1. Confirm you're on main branch with latest code
git checkout main && git pull

# 2. Create the tag
git tag v0.3.0

# 3. Push the tag (triggers CI)
git push origin v0.3.0

After pushing the tag, CI automatically takes over the entire subsequent process. For detailed pipeline job structure and build matrix, see the CI/CD Pipeline Documentation.

CI Automated Execution Overview

1. Frontend build (Ubuntu)
2. Multi-platform parallel builds: macOS arm64/amd64 (DMG), Windows amd64/arm64 (ZIP), Linux amd64/arm64 (tar.gz)
3. Docker multi-arch image push to GHCR (tags: version + major.minor + latest)
4. Create GitHub Release (auto-generated Release Notes + SHA256 checksums)
5. Pre-release auto-detection: tags containing -rc/-beta/-alpha are automatically marked as prerelease
6. Notify Homepage (repository_dispatch: release-published)

Post-Release Automatic Sync

• Homepage automatically mirrors the Release and updates the download page version numbers (Download.astro + Hero.astro)
• Client-side automatic update detection (in-app latest version check)

Current status: macOS code signing requires the Apple Developer Program ($99/year). When signing Secrets are not configured, CI automatically falls back to ad-hoc signing (-s -), and users need to run xattr -cr Presto.app to bypass Gatekeeper.

---

Part 3: Template Release

Applies to: Starter repositories and presto-official-templates.

Pre-Release Checklist

• [ ] make test passes completely (including security tests)
• [ ] manifest.json version field has been updated
• [ ] example.md converts correctly
• [ ] Preview in Presto looks correct

Release Steps

# 1. Update the version in manifest.json
# 2. Commit the changes
git add manifest.json
git commit -m "chore: bump version to 1.1.0"

# 3. Tag and push
git tag v1.1.0
git push origin main --tags

CI Automated Execution

• 6-platform build (darwin/linux/windows x arm64/amd64)
• Generate SHA256SUMS checksum file
• Create GitHub Release via softprops/action-gh-release (auto-generated notes)

For detailed build differences (Go / Rust / TypeScript), see the CI/CD Pipeline Documentation.

Official Template Special Notes

presto-official-templates is a monorepo with smart incremental build capabilities:

• Only builds template subdirectories with changes
• Changes to shared files (go.mod, internal/, .github/) trigger a full build of all templates
• A single tag may include updates to multiple templates
• Falls back to full build on first release or when change detection is not possible

Registry Listing

• Repository must have the presto-template topic added
• Registry CI scans daily at UTC 08:00 (up to 24h delay)
• community trust level is automatically assigned
• verified level requires submitting a PR to verified-templates.json in template-registry (currently empty --- no verified templates yet)

---

Part 4: Changelog Management

Current Approach

All repositories use GitHub auto-generated Release Notes, with no manually maintained CHANGELOG files.

• Presto main app: gh release create with --generate-notes
• Template repositories: softprops/action-gh-release with generate_release_notes: true
• Release Notes are auto-generated based on PR titles and commit messages

Recommended Commit Message Convention

To improve the readability of auto-generated Release Notes, the following prefixes are recommended:

Prefix	Purpose	Example
feat	New feature	feat: support custom font paths
fix	Bug fix	fix: fix blank page in PDF export
chore	Maintenance	chore: bump version to 1.1.0
docs	Documentation	docs: update installation guide

---

Part 5: Cross-Repository Release Coordination

Release Dependency Graph

Key Points

• Each repository can release independently with no mandatory ordering dependencies
• Cross-repository syncing is completed asynchronously via event-driven mechanisms
• After main app release, Homepage syncs automatically with no manual intervention required
• After template release, the registry picks it up on the next cron execution

Authentication Tokens

Token	Purpose	Configuration Location
PRESTO_PAT	Cross-repository API calls	Organization Secrets
HOMEPAGE_DISPATCH_TOKEN	Trigger Homepage sync workflow	Presto repo Secrets

---

Part 6: Troubleshooting

Below are the most common issues encountered during the release process and their troubleshooting steps.

CI Build Failure

Check the GitHub Actions logs. Common causes:

• Dependency download timeout (re-running the Job usually resolves this)
• Platform-specific compilation errors (check the build log for the corresponding OS/architecture)
• Frontend build failure causing all subsequent Jobs to be skipped (fix the frontend issue first)

macOS Signing Issues

Currently using ad-hoc signing. The signing step in CI is conditional: when APPLE_CERTIFICATE and other Secrets are not configured, formal signing is automatically skipped and falls back to codesign -s - --force --deep. This is not an error --- it is expected behavior.

Docker Push Failure

• Confirm that GITHUB_TOKEN has write:packages permission for ghcr.io
• Check that the GHCR repository exists and is writable

Homepage Sync Failure

• Check whether PRESTO_PAT has expired or has insufficient permissions
• Manual trigger: go to the Homepage repository Actions page and run sync-release.yml

Registry Not Listing Template

• Confirm the repository has the presto-template topic added
• Wait for the next cron execution (daily at UTC 08:00)
• Manual trigger: go to the template-registry repository Actions page and run update-registry.yml