Release Instructions for Buffit#

How to build and release a new version of Buffit on GitHub.

Prerequisites#

Xcode installed
GitHub repository set up
Version number ready (use semantic versioning: v1.0.0, v1.0.1, etc.)

Step 1: Update Version#

Update the app version in Xcode:

Open BufferQueue.xcodeproj
Select the BufferQueue target
Go to Build Settings
Search for "Version" and update:
- Marketing Version (e.g., 1.0.0)
- Build Number (e.g., 1)

Or edit Info.plist:

<key>CFBundleShortVersionString</key>
<string>1.0.0</string>

Step 2: Build Release#

Run the build script:

cd /Volumes/Media/xcode/BufferQueue/BufferQueue
./build-release.sh

This will:

✅ Compile the app in Release mode (optimized)
✅ Create Buffit.dmg (distribution package)
✅ Create release/Buffit.app (direct app)

Step 3: Test the DMG#

Before releasing, test installation:

Mount the DMG: Open Buffit.dmg
Drag Buffit to Applications
Open System Settings → Privacy & Security
Click "Open Anyway" if prompted
Test core functionality:
- Connect with Buffer API key
- Select channels
- Compose and upload image
- Post to Buffer

Step 4: Create GitHub Release#

Via GitHub Web:#

Go to your GitHub repository
Click Releases (right sidebar)
Click Create a new release

Set release info:

Tag version: v1.0.0 (must match app version)
Release title: Buffit v1.0.0

Description:

## 🎉 Buffit v1.0.0

### Features
- ✨ New feature here
- 🐛 Fixed bug here

### Installation
1. Download `Buffit.dmg`
2. Open DMG and drag to Applications
3. Open Buffit from Applications
4. Approve in System Settings if prompted
5. Add your Buffer API key and enjoy!

### System Requirements
- macOS 12.0 or later

See [README.md](README.md) for full installation instructions.

Click Choose Files (or drag):
- Upload Buffit.dmg
Click Publish release

Via GitHub CLI:#

# Create release with DMG
gh release create v1.0.0 \
  --title "Buffit v1.0.0" \
  --notes "See README.md for installation instructions" \
  ./Buffit.dmg

Step 5: Distribute#

Share the release link:

Direct: https://github.com/yourusername/BufferQueue/releases/tag/v1.0.0
Direct DMG: https://github.com/yourusername/BufferQueue/releases/download/v1.0.0/Buffit.dmg

Important Notes#

Code Signing#

Since you're not using an Apple Developer Account:

⚠️ The app will be unsigned
✅ Users will see a security warning on first launch
✅ Users can approve it in System Settings → Privacy & Security
✅ This is normal for unsigned Mac apps

Apple Notarization#

Notarization requires a paid developer account ($99/year). Without it:

Users may see "Cannot verify developer" message
This is expected and normal for free, open-source apps
Users can still run it by clicking "Open Anyway" in System Settings

Future: If You Pay for Developer Account#

If you ever get an Apple Developer Account:

Code sign the app with your certificate
Notarize it with Apple
Users can then open it without warnings

Troubleshooting#

"App is corrupted" error on user's Mac

This is normal for unsigned apps
User should: System Settings → Privacy & Security → Click "Open Anyway"
Or: xattr -d com.apple.quarantine ~/Applications/Buffit.app

DMG won't open

Rebuild: ./build-release.sh
Check disk space (DMG creation needs space)

Build fails with architecture errors

Make sure build script has both arm64 and x86_64
Run: xcode-select --install to update Xcode command line tools

Version Bumping Checklist#

Before each release:

Update version in Xcode
Update version in Info.plist
Test on macOS 12.0+ (compatibility)
Update CHANGELOG.md with changes
Run ./build-release.sh
Test DMG installation
Create GitHub release
Share with users

Next Release Cycle#

Repeat steps 1-5 for each new version.

Good luck shipping! 🚀

Configure Feed