admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity
brew/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
Andrew Janke 496fff643f doco: more updates for core/formula separation 
Closes #71.

Signed-off-by: Andrew Janke <andrew@apjanke.net>
2016-04-11 19:29:42 -04:00

4.6 KiB
Raw Blame History

How To Open a Homebrew Pull Request (and get it merged)

The following commands are used by Homebrew's contributors to setup a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request of the changes in that branch.

Depending on the change you want to make, you need to send the pull request to the corresponding repository. If you want to submit a change in Homebrew core code, you should open the pull request at Homebrew/brew. If you want to submit a change for a formula, you could open the pull request at Homebrew core tap or any other official taps based the formula type.

Set up your own fork of the Homebrew repository

Core code related pull request

  1. Change to the directory containing your Homebrew installation with cd $(brew --repository)
  2. Fork the Homebrew/brew repository on GitHub. This creates a pushable, personal remote repository. This is needed as only Homebrew maintainers have push access to the main repository.
  3. Add the pushable forked repository with git remote add YOUR_USERNAME https://github.com/YOUR_USERNAME/brew.git

Formulae related pull request

  1. Change to the directory containing Homebrew formulae with cd $(brew --repository homebrew/core)
  2. Fork the Homebrew/homebrew-core repository on GitHub. This creates a pushable, personal remote repository. This is needed as only Homebrew maintainers have push access to the main repository.
  3. Add the pushable forked repository with git remote add YOUR_USERNAME https://github.com/YOUR_USERNAME/homebrew-core.git

Create your Pull Request from a new branch

To make a new branch and submit it for review:

  1. Checkout the master branch with git checkout master
  2. Retrieve new changes to the master branch with brew update (which calls git pull)
  3. Create a new branch from the latest master branch with git checkout -b YOUR_BRANCH_NAME origin/master
  4. Make your changes to any Homebrew formula with brew edit (following all the requirements in the Formula Cookbook). Run brew audit ANY_CHANGED_FORMULA, brew tests and brew install ANY_CHANGED_FORMULA && brew test ANY_CHANGED_FORMULA and ensure all of these pass without issue. If there's a bottle do block in the formula: don't remove it; we'll update it when we pull it.
  5. Make a separate commit for each changed formula with git add and git commit.
  6. Upload your new commits to the branch to your fork with git push --set-upstream YOUR_USERNAME YOUR_BRANCH_NAME
  7. Go to https://github.com/Homebrew/homebrew-core and create a pull request to request review and merge of commits in your pushed branch. Make sure you explain why the change is needed and, if fixing a bug, how to reproduce the bug. Please note that the preferred commit message format for simple version updates is "FORMULA_NAME NEW_VERSION", e.g. "source-highlight 3.1.8". devel version bumps should have the commit message marked with addtional (devel) suffix like "nginx 1.9.1 (devel)". Await feedback or a merge from Homebrew's maintainers.

Following up

To respond well to feedback:

  1. Ask for clarification of anything you don't understand and help with anything you don't know how to do.
  2. Post a comment on your pull request if you've provided all the requested changes/information and it hasn't been merged after a week. Post a comment on your pull request if you're stuck and need help.
  3. Keep discussion in the pull request unless requested otherwise (i.e. do not email maintainers privately).
  4. Do not continue discussion in closed pull requests.
  5. Do not argue with Homebrew maintainers. You may disagree but unless they change their mind please implement what they request. Ultimately they control what is included in Homebrew as they have to support any changes that are made.

To make changes based on feedback:

  1. Checkout your branch again with git checkout YOUR_BRANCH_NAME
  2. Make any requested changes and commit them with git add and git commit
  3. Squash new commits into one commit per formula with git rebase --interactive origin/master
  4. Push to the fork's remote branch and the pull request with git push --force

Once all feedback has been addressed and if it's a change we want to include (we include most changes) then we'll add your commit to Homebrew. Note it will not show up as "Merged" because of the way we include contributions.

Well done, you are now a Homebrew contributor!