Merge pull request #6996 from SMillerDev/docs/guides

Docs: Add guides for common cases

docs/Adding-Software-to-Homebrew.md

@@ -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](How-To-Open-a-Homebrew-Pull-Request.md) documentation 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.

docs/Creating-a-Homebrew-Issue.md

@@ -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.

docs/README.md

@@ -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)

docs/Updating-Software-in-Homebrew.md

@@ -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 (whichever apply) 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 [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple formulae updates, this typically involves changing the URL and sha256.
+
+However, some updates require additional changes to the formulae. You can look back at previous pull requests to see how others have handled things in the past but be sure to look at a variety of PRs. Sometimes formulae aren't updated properly, so you may need to use your judgment to determine how to best 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 if everything passed or a red X if 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!