admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Docs: Add guides for common cases

Browse Source 
Co-authored-by: Sam Ford <1584702+samford@users.noreply.github.com>
This commit is contained in:
Sean Molenaar 2020-02-03 22:25:20 +01:00
parent cf02ac9d46
commit 10f529d091
No known key found for this signature in database
GPG Key ID: 6BF5D8DF0D34FAAE
4 changed files with 56 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/Adding-Software-to-Homebrew.md Normal file
View File

@ -0,0 +1,34 @@
# Adding Software to Homebrew
Are you missing your favorite software in Homebrew? Then you're the perfect person to resolve this problem.
Before you start, please check the open pull requests for [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls) or [linuxbrew-core](https://github.com/Homebrew/linuxbrew-core/pulls), to make sure no one else beat you to the punch.
Next, you will want to go through the [Acceptable Formulae](Acceptable-Formulae.md) documentation to determine if the software is an appropriate addition to Homebrew. If you are creating a formula for an alternative version of software already in Homebrew (for example, a major/minor version that significantly differs from the existing version), be sure to read the [Versions](Versions.md) documentation to understand versioned formulae requirements.
If everything checks out, you're ready to get started on a new formula!
## Writing the formula
1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled.
1. If you're starting from scratch, the [`brew create` command](Manpage.md#create-options-url) can be used to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`.
1. You will now have to work to develop the boilerplate code from `brew create` into a fully-fledged formula. Your main references will be the [Formula Cookbook](Formula-Cookbook.md), similar formulae in Homebrew, and the upstream documentation for your chosen software. Be sure to also take note of the Homebrew documentation for writing [`Python`](Python-for-Formula-Authors.md) and [`Node`](Node-for-Formula-Authors.md) formulae, if applicable.
1. Make sure you write a good test as part of your formula. Refer to the "[Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula)" section of the Cookbook for help with this.
1. Try to install the formula using `brew install --build-from-source <formula>`, where \<formula\> is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula should install without errors by the end of this step.
If you're stuck, ask for help on GitHub or [Discourse](https://discourse.brew.sh). The maintainers are very happy to help but we also like to see that you've put effort into trying to find a solution first.
## Testing and auditing the formula
1. Run `brew audit --strict --new-formula --online <formula>` with your formula. If any errors occur, correct them in your formula and run the audit again. The audit should finish without any errors by the end of this step.
1. Run your formula's test using `brew test <formula>` with your formula. Your test should finish without any errors.
## Submitting the formula
You're finally ready to submit your formula to the [homebrew-core](https://github.com/Homebrew/homebrew-core/) or [linuxbrew-core](https://github.com/Homebrew/linuxbrew-core/) repository. If you haven't done this before, you can refer to the [How to Open a Pull Request documentation](How-To-Open-a-Homebrew-Pull-Request.md) for help. Maintainers will review the pull request and provide feedback about any areas that need to be addressed before the formula can be added to Homebrew.
If you've made it this far, congratulations on submitting a Homebrew formula! We appreciate the hard work you put into this and you can take satisfaction in knowing that your work may benefit other Homebrew users as well.

5
docs/Creating-a-Homebrew-Issue.md Normal file
View File

@ -0,0 +1,5 @@
# Creating a Homebrew Issue
First, check to make sure your issue is not listed in the [FAQ](FAQ.md) or [Common Issues](Common-Issues.md) and can't otherwise be resolved with the information in the [Tips and Tricks](Tips-N'-Tricks.md) documentation. Next, go through the steps in the [Troubleshooting guide](Troubleshooting.md).
If the preceding steps did not help, it may be appropriate to submit an issue. This can be done by navigating to the relevant repository, clicking the "Issues" link, and clicking on the "New issue" button. When creating an issue, make sure you use the provided template, as it's important in helping others to understand and potentially triage your issue efficiently.

4
docs/README.md
View File

@ -27,6 +27,10 @@
- [Xcode](Xcode.md)
- [Kickstarter Supporters](Kickstarter-Supporters.md)
- [Creating a Homebrew Issue](Creating-a-Homebrew-Issue.md)
- [Updating Software in Homebrew](Updating-Software-in-Homebrew.md)
- [Adding Software to Homebrew](Adding-Software-to-Homebrew.md)
## Contributors
- [How To Open A Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md)

13
docs/Updating-Software-in-Homebrew.md Normal file
View File

@ -0,0 +1,13 @@
# Updating Software in Homebrew
Did you find something in Homebrew that wasn't the latest version? You can help yourself and others by submitting a pull request to update the formula.
First, check the pull requests in the [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls) or [linuxbrew-core](https://github.com/Homebrew/linuxbrew-core/pulls) repositories to make sure there isn't already an open PR. You may also want to look through closed pull requests for the formula, as sometimes formulae run into problems preventing them from being updated and it's better to be aware of any issues before putting significant effort into an update.
The guide on [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md#submit-a-new-version-of-an-existing-formula) should really be all you need, this will explain how to easily change the url to point to the latest version and that's really all you need. If you want to read up on `bump-formula-pr` before using it you could check [the manpage](Manpage.md#bump-formula-pr-options-formula).
You can look back at previous pull requests that updated the formula to see how others have handled things in the past but be sure to look at a variety of PRs. Sometimes formulae are not updated properly (for example, running `bump-formula-pr` on a Python formula that needs dependency updates), so you may need to use your judgment to determine how to proceed.
Once you've created the pull request in the appropriate Homebrew repository your commit(s) will be tested on our continuous integration servers, showing a green check mark when everything passed or a red X when there were failures. Maintainers will review your pull request and provide feedback about any changes that need to be made before it can be merged.
We appreciate your help in keeping Homebrew's formulae up to date as new versions of software are released!