Skip to content

github-release-guide.md

Latest commit

 

History

History
246 lines (162 loc) · 4.86 KB

github-release-guide.md

File metadata and controls

246 lines (162 loc) · 4.86 KB
Raw

Topleaf GitHub Release Guide

Last updated: 2026-04-13

What this covers

This document answers two practical questions:

  1. how to publish a GitHub Release for Topleaf
  2. what release automation is already wired into this repository

What is already automated

The repository now includes two GitHub Actions workflows:

  • CI
    • file: .github/workflows/ci.yml
    • purpose:
      • checks formatting
      • regenerates the Xcode project
      • builds the app and test targets
  • Release
    • file: .github/workflows/release.yml
    • purpose:
      • runs automatically when you push a v* tag
      • builds a Release configuration
      • packages both a zip and a dmg
      • includes an uninstall helper
      • generates a sha256 checksum file
      • creates or updates the GitHub Release

What a release currently produces

Each automated GitHub Release uploads:

  • Topleaf-macOS-unsigned-vX.Y.Z.zip
  • Topleaf-macOS-unsigned-vX.Y.Z.dmg
  • Topleaf-Uninstall-vX.Y.Z.command
  • Topleaf-macOS-unsigned-vX.Y.Z.sha256

The practical split is:

  • the dmg is the most convenient install format for direct download
  • users can drag Topleaf.app into Applications
  • the release also includes Topleaf Uninstall.command
  • that helper removes the standard app-install path plus the app’s local data locations

Important:

  • the current artifact is unsigned
  • it is not notarized
  • regular end users will still see Gatekeeper friction
  • so a dmg improves the install shape, but it does not replace proper signing and notarization

This is a good fit for the current phase:

  • open-source distribution
  • technical testers
  • early GitHub-based release flow

If you later want smoother end-user downloads, you still need:

  • Developer ID signing
  • notarization
  • the related GitHub Secrets
  • optionally a branded DMG layout

Normal release flow

1. Update the version

Version metadata currently lives in:

  • project.yml

You will usually update:

  • MARKETING_VERSION
  • CURRENT_PROJECT_VERSION

Example:

  • MARKETING_VERSION: 0.1.0
  • CURRENT_PROJECT_VERSION: 1

2. Commit and push

git add .
git commit -m "Prepare v0.1.0"
git push origin main

3. Create and push a tag

git tag v0.1.0
git push origin v0.1.0

Once the tag reaches GitHub, the release workflow starts automatically.

4. Check Actions

Open:

  • Actions

Then watch:

  • Release

5. Check Releases

Open:

  • Releases

You should see:

  • a new v0.1.0 release
  • generated release notes
  • uploaded zip and checksum assets

Manual reruns

Two common options:

Option A: delete the GitHub Release and rerun

Useful when:

  • the tag is already correct
  • only the uploaded assets need to be rebuilt

Option B: use workflow_dispatch

The repository already supports manual dispatch:

  • open Actions
  • choose Release
  • click Run workflow
  • enter an existing tag, for example:
    • v0.1.0

This is useful when:

  • the tag already exists
  • you want to rebuild and re-upload assets for that tag

It expects an existing tag. It does not create a new tag for you.

Local packaging

The repository also includes a local helper:

  • scripts/package-github-release.sh

You can run:

./scripts/package-github-release.sh v0.1.0

It will:

  • regenerate the Xcode project
  • build the Release app
  • package the zip and dmg
  • copy the uninstall helper
  • generate sha256

Output goes to:

  • dist/

Automatic release notes

The repository now includes:

  • .github/release.yml

This config helps GitHub group automatically generated release notes when you start using pull requests and labels such as:

  • feature
  • enhancement
  • bug
  • fix
  • documentation
  • docs
  • chore
  • refactor

Most common commands

For normal releases, these are the commands you will use most often:

git add .
git commit -m "Prepare v0.1.0"
git push origin main
git tag v0.1.0
git push origin v0.1.0

Then check:

  • Actions
  • Releases

Current limits

The current release automation does not yet cover:

  • Developer ID signing
  • notarization
  • custom DMG background and window layout
  • Sparkle updates

So it is best suited for:

  • the GitHub open-source phase
  • technical testers
  • early release distribution

About clean uninstall

Deleting Topleaf.app alone does not guarantee that the app’s local data disappears with it.

That is why each release now also includes:

  • Topleaf-Uninstall-vX.Y.Z.command

The helper tries to remove the standard locations used by the app, including:

  • /Applications/Topleaf.app
  • ~/Applications/Topleaf.app
  • ~/Library/Containers/com.c23333.Topleaf
  • ~/Library/Application Support/Topleaf
  • the related cache, preference, saved-state, and log paths

It intentionally does not delete files that live outside Topleaf’s standard locations, such as:

  • exported backups
  • exported support packages
  • user-copied files that were moved elsewhere in Finder