docs/Homebrew-homebrew-cask-Maintainer-Guide.md
This guide is intended to help maintainers effectively maintain the cask repository. It is meant to be used in conjunction with the more generic Maintainer Guidelines.
Here is a list of the most common situations that arise in cask PRs and how to handle them:
version and sha256 both change (keeping the same format): Merge.sha256 changes: Merge unless the version needs to be updated as well. It’s not uncommon for upstream vendors to update versions in-place. However, be wary for times when e.g. upstream could have been hacked.livecheck is updated: Use your best judgement and try to make sure that the changes follow the livecheck guidelines.version changes or the version format changes: Use your best judgement and merge if it seems correct (this is relatively rare).If in doubt, ask another cask maintainer on GitHub or Slack.
Note that unlike formulae, casks do not consider the sha256 stanza to be a meaningful security measure as maintainers cannot realistically check them for authenticity. Casks download from upstream; if a malicious actor compromised a URL, they could potentially compromise a version and make it look like an update.
Do not deprecate, disable or remove a cask just because upstream asks us to or claims Homebrew's packaging is "broken". If our analytics show non-zero installs and our issue tracker is not receiving user reports that the cask is broken, keep it unless there is a clear enough technical, policy or project-wide reason to do otherwise.
When this happens, point upstream developers to Working with Homebrew as an Upstream Project and keep the discussion in public on GitHub.
In general, using GitHub's "Merge" button is the best way to merge a PR. This can be used when the PR modifies only one cask, regardless of the number of commits or whether the commit message format is correct. When merging using this method, the commit message can be modified if needed. Usually, version bump commit messages follow the form Update CASK from OLD_VERSION to NEW_VERSION.
If the PR modifies multiple casks, use the "Rebase and Merge" button to merge the PR. This will use the commit messages from the PR, so make sure that they are appropriate before merging. If needed, checkout the PR, squash/reword the commits and force-push back to the PR branch to ensure the proper commit format.
Finally, make sure to thank the contributor for submitting a PR!
A maintainer can easily rebase a PR onto the latest default branch by adding a /rebase comment. BrewTestBot will automatically rebase the PR and add a reaction to the comment once the rebase is in progress and complete.