Contributing to CaskHub

Thanks for your interest in improving CaskHub! This guide explains how to get changes merged smoothly. Reading it first saves both of us a review round-trip.

Ways to Contribute

• Code: bug fixes, features, performance work, refactors
• Bug reports: open an issue
• Feature requests: open an issue
• Documentation: fixes and improvements to the README or guides

Two kinds of problems belong elsewhere:

• Wrong category, wrong icon, or stale metadata for a cask. That data is generated by the CaskFlow pipeline, not this repo. File it on CaskFlow's issues.
• A cask that is missing, broken, or outdated in Homebrew itself. CaskHub displays Homebrew's catalog and delegates to brew. Report those to Homebrew/homebrew-cask.

Security vulnerabilities have their own process — see SECURITY.md. You must not report them in public issues or pull requests.

Before You Start

• Search existing issues and pull requests to avoid duplicating work.
• Open an issue before writing a non-trivial PR. CaskHub is maintained by a single developer in their spare time; agreeing on the direction first avoids wasted effort on both sides.
• Typo-level fixes can go straight to a pull request.

Building from Source

You need Xcode 26 or later on macOS 15.6+:

git clone https://github.com/alielsokary/CaskHub.git
cd CaskHub
brew install swiftlint
open CaskHub.xcodeproj

Select the CaskHub scheme and run (⌘R). Xcode resolves the Swift package dependencies (Sparkle, Sentry, TelemetryDeck) automatically.

Notes:

• SwiftLint is required locally — it runs as an Xcode build phase. The build warns if it is not installed.
• Configs/Secrets.xcconfig is optional. The project builds without it; analytics and crash reporting simply stay off. If you want one, copy Configs/Secrets.xcconfig.template.

Branch Model

All pull requests target the develop branch — never master.

master is release-only: it receives release/x.y.z merges from the maintainer, and each release ships from it. A PR opened against master will be retargeted or sent back.

Branches, Commits, and PR Titles

What	Convention	Example
Branch name	type prefix + kebab-case slug	fix/empty-search-results
Commit message	conventional prefix, lowercase subject	fix: handle empty search results
PR title	same prefix, Sentence-case subject	fix: Handle empty search results

Common type prefixes: feat, fix, perf, refactor, test, docs, ci, style.

Keep commits focused — one logical change per commit.

Code Style

• SwiftLint runs as a build phase (swiftlint --fix, then lint). Config lives in .swiftlint.yml.
• SwiftFormat config lives in .swiftformat and is tuned so the two tools don't fight.
• CI does not run a lint job — keep your build clean locally before pushing.

Tests

CaskHub has a unit test target, CaskHubTests. Run it from Xcode (⌘U) or:

xcodebuild test -project CaskHub.xcodeproj -scheme CaskHub -destination 'platform=macOS'

Every PR runs the test suite in CI and uploads coverage to Codecov. The patch coverage target is 80% — a PR that adds logic without tests will fail the Codecov check. Add or update tests alongside your change.

What Not to Touch

• CaskHub/Resources/categories.json and CaskHub/Resources/added_dates.json are generated artifacts from the CaskFlow pipeline. Never hand-edit or regenerate them in a feature PR — the maintainer syncs them during release preparation.
• CHANGELOG.md is maintained by the maintainer at release time. Don't add entries in feature PRs.

Review

CaskHub is maintained by a single developer, so reviews are best-effort — please allow a few days. PRs that target master, lack tests for new logic, or touch the generated files above will be sent back before a full review.

By contributing, you agree that your contributions are licensed under the MIT License.

Thank you for helping make CaskHub better!