Skip to content

Latest commit

 

History

History
191 lines (130 loc) · 5.56 KB

AGENTS.md

File metadata and controls

191 lines (130 loc) · 5.56 KB

Agent Instructions for homebrew-cask

This document helps coding agents produce high-quality PRs for Homebrew Cask contributions.

Before Any PR

  1. Check for existing PRs for the same cask: open PRs
  2. Check if previously refused: closed unmerged PRs

Golden Rules

  • One cask per PR, one intent per PR
  • Minimal diffs—change only what's necessary
  • No drive-by formatting or unrelated stanza churn
  • No verbose commentary—keep PR descriptions short
  • No non-Homebrew caveats in PR body or cask file
  • Use official sources for download URLs
  • If unsure about policy (notability, naming, livecheck), stop and ask before opening a PR

Version Updates

Preferred method for version bumps:

brew bump --open-pr <cask>

This handles version/sha256 updates, commit message, and opens the PR automatically.

Manual Version Updates

If manual editing is needed:

brew edit --cask <cask>
# Update version, url, sha256 as needed
# Do not add unrelated stanza changes

Commit message: <cask> <version> (e.g., firefox 125.0)

Cask Fixes

For bug fixes or improvements to existing casks:

brew edit --cask <cask>
# Make only the required changes

Commit message: <cask>: <description> (e.g., firefox: fix zap stanza)

New Casks

Notability Requirements

New casks will be rejected if:

  • App is too obscure (GitHub: <30 forks/watchers or <75 stars)
  • No public presence beyond "just brew install"
  • Unmaintained or has unpatched security vulnerabilities
  • Requires SIP to be disabled
  • Download requires login/registration (walled builds)
  • No compiled versions available (use homebrew/core instead)
  • Previously rejected for unfixable issues

See Acceptable Casks for full criteria.

Creating a New Cask

brew create --cask <url>
# Edit the generated cask

Commit message: <cask> <version> (new cask) (e.g., myapp 1.0.0 (new cask))

Required Elements

  • Token: Follow the token reference—lowercase, hyphens, no version numbers
  • Required stanzas: version, sha256, url, name, desc, homepage, and at least one artifact (app, pkg, etc.)
  • verified: parameter: Required when url host differs from homepage host
  • uninstall stanza: Required for pkg and installer artifacts
  • zap stanza: Recommended for thorough cleanup (preference files, caches in ~/Library)

Required Validation

For Existing Cask Changes

brew audit --cask --online <cask>
brew style --fix <cask>
brew install --cask <cask>    # or reinstall
brew uninstall --cask <cask>

For New Casks

export HOMEBREW_NO_INSTALL_FROM_API=1
brew audit --cask --new <cask>
brew style --fix <cask>
brew install --cask <cask>
brew uninstall --cask <cask>

All checks MUST pass locally before opening a PR.

PR Template Checklist

You MUST verify all items before submitting:

For all cask changes:

Additionally, for new casks:

  • Named according to token reference
  • Checked cask was not already refused
  • brew audit --cask --new <cask> worked successfully
  • HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <cask> worked successfully
  • brew uninstall --cask <cask> worked successfully

If AI-assisted:

  • Personally reviewed, tested, and verified all changes including zap stanza paths

Commit Message Format

  • Version update: appname 1.2.3
  • New cask: appname 1.2.3 (new cask)
  • Fix/change: appname: <description>
  • First line MUST be 50 characters or less

PR Hygiene

MUST

  • One cask change per PR
  • Keep diffs minimal and focused
  • Provide only essential context in PR description

MUST NOT

  • Batch unrelated cask changes
  • Include formatting-only diffs
  • Add verbose logs or AI analysis in PR body
  • Add installation caveats unless the cask DSL requires it
  • Include unrelated refactors or stanza reordering

PR Description

Keep it minimal:

Built and tested locally on [macOS version].

[One sentence if not obvious from title.]

Do NOT include:

  • Large command output or logs
  • Lengthy explanations
  • Non-Homebrew installation advice

CI Failures

  1. Reproduce failures locally with the same commands
  2. Read error messages in "Files changed" tab annotations
  3. Fix only the failing issue
  4. Push incremental commits (do not squash after opening PR)
  5. If stuck, comment describing what you've tried

AI Disclosure

If AI assisted with the PR, check the AI checkbox in the PR template. Briefly describe:

  • How AI was used
  • What manual verification was performed (especially zap paths)

References