Skip to content

RELEASE.md

Latest commit

 

History

History
134 lines (97 loc) · 3.87 KB

RELEASE.md

File metadata and controls

134 lines (97 loc) · 3.87 KB
Raw

Release Guide

This guide explains how to create a new release for DockCleat on GitHub.

Prerequisites

  • Git repository is set up and connected to GitHub
  • You have push access to the repository
  • Xcode is installed and configured
  • Apple Developer account (for Developer ID signing and notarization)

Setup Notarization (First Time Only)

For Developer ID signed apps, notarization is required. Set up credentials once:

Local Builds (macOS Keychain)

Run the setup script:

./scripts/setup-notarization.sh

This will:

  • Prompt for your Apple ID
  • Prompt for your Team ID (default: JDMS6RY775)
  • Prompt for an App-Specific Password
  • Store credentials securely in macOS Keychain

To get an App-Specific Password:

  1. Go to https://appleid.apple.com
  2. Sign in and navigate to "App-Specific Passwords"
  3. Generate a new password for "DockCleat Notarization"
  4. Copy the password (it's only shown once)

CI/CD (GitHub Actions)

Add the following secrets to your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. Add these repository secrets:
    • APPLE_ID: Your Apple ID email
    • NOTARY_PASSWORD: Your App-Specific Password
    • TEAM_ID: Your Team ID (optional, defaults to JDMS6RY775)

The GitHub Actions workflow will automatically use these secrets for notarization.

Manual Release Process

1. Update Version

Update the version in DockCleat.xcodeproj/project.pbxproj:

  • MARKETING_VERSION - User-facing version (e.g., "1.0.0")
  • CURRENT_PROJECT_VERSION - Build number (e.g., "1")

2. Update CHANGELOG.md

Add a new entry to CHANGELOG.md with all changes since the last release.

3. Build Release Version

Run the build script:

./scripts/build-release.sh [version]

Example:

./scripts/build-release.sh 1.0.0

This will:

  • Build the Release version
  • Create a ZIP file in the project root
  • Automatically sign with Developer ID (if available) or Apple Development
  • Submit for notarization (if credentials are set up)
  • Staple the notarization ticket to the app

Note: If you haven't set up notarization credentials, the build will still succeed but skip notarization. Run ./scripts/setup-notarization.sh to enable it.

4. Create Git Tag

# Create and push the tag
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

5. Create GitHub Release

  1. Go to your GitHub repository
  2. Click "Releases" → "Draft a new release"
  3. Select the tag you just created (e.g., v1.0.0)
  4. Fill in the release title and description (copy from CHANGELOG.md)
  5. Upload the ZIP file created by the build script
  6. Click "Publish release"

Automated Release (GitHub Actions)

If you've set up GitHub Actions (.github/workflows/release.yml), simply:

  1. Create and push a tag:

    git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

  2. GitHub Actions will automatically:

    • Build the Release version
    • Create a ZIP archive
    • Submit for notarization (if secrets are configured)
    • Create a GitHub Release
    • Upload the ZIP file

Note: Make sure you've added the required secrets (APPLE_ID, NOTARY_PASSWORD, TEAM_ID) to your GitHub repository for notarization to work.

Release Checklist

  • Update version numbers in Xcode project
  • Update CHANGELOG.md with new changes
  • Test the Release build locally
  • Commit all changes
  • Create and push git tag
  • Create GitHub Release (or let GitHub Actions handle it)
  • Verify the release is accessible
  • Update README.md if needed (e.g., new features)

Version Numbering

Follow Semantic Versioning:

  • MAJOR version for incompatible API changes
  • MINOR version for new functionality in a backwards compatible manner
  • PATCH version for backwards compatible bug fixes

Example: 1.0.0 → 1.0.1 (patch) → 1.1.0 (minor) → 2.0.0 (major)