Docs: Add guides for common cases

[SMillerDev]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

This adds an informal set of guides to the documentation. These guides document the most common cases why people would read the documentation (imho).

[issyl0]

Thanks Sean! I'll give this a more thorough review shortly from a content perspective. After skim-reading to suggest these branding fixes, I'm not entirely sure about the tone of this - it's a bit too sarcastic for my tastes.

[SMillerDev]

Yeah, I'm not sure about the tone either. I want it to be easy access though so I went with a very informal tone. Any suggestions on what to change?

[MikeMcQuaid]

I like this idea! If I understood our in-person conversation correctly: the purpose of this is to have something easily linkable for people, right?

[MikeMcQuaid]

Unrelated test failures should be fixed by #7003

[SMillerDev]

Easily linkable but also easily understood.

[samford]

I've added a quite a number of suggested revisions and expansions. I'll try to send the modified files to you, so you don't have to reverse engineer the Markdown from my rendered comments and can easily copy and paste as needed.

I spent about 7-8 hours between yesterday and today reviewing this, so if you end up using significant portions of my suggestions, I would appreciate if you added me as a co-author in the commit message:

Co-authored-by: Sam Ford <1584702+samford@users.noreply.github.com>

I hope this is helpful!

[samford]

There's a fair bit of detail omitted here that would be good to include. As you well know, updating a formula to a new version isn't always as simple as using bump-formula-pr or replacing the URL and sha256 and it would be helpful to provide some guidance, even if it's just "Check old PRs for the formula to see how others have updated the formula in the past".

Maybe:

"Before making changes to formulae, you will need to fork the homebrew-core (or linuxbrew-core) repository on GitHub and add your fork as a remote in your local Homebrew git repository, if you haven't already. You can find details on how to accomplish this in the How to Open a Homebrew Pull Request documentation.

For simple version changes, you can use the brew bump-formula-pr command, passing in appropriate arguments using --url, --tag, --mirror, etc. This will save you some work by automatically modifying the formula, running an audit, creating a commit, pushing a branch to your fork with the commit, and creating a pull request for the change(s).

Some formulae require modifications that bump-formula-pr can't handle itself. For example, Python formulae often have resource blocks for package dependencies and these need to be updated as well (to bring them in line with the packages and versions installed by pip). With formulae like these, you will need to modify the formula by hand, making sure to follow the instructions on creating a branch in Git for your changes.

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, so you may need to use your judgment to determine how to best proceed.

Once you've updated the formula, you will need to push the branch to your fork and create a 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!"

[samford]

Just a side note but the Co-authored-by: text in the commit message is special insomuch as GitHub parses it and also attributes the commit to the associated users in the UI (i.e., Re-authored-by: isn't parsed and doesn't have the same result). I don't mind either way but I figured it's worth mentioning for the future, since it's kind of neat.

[SMillerDev]

I kept the pull request info mostly as is so you could integrate your write-up about that at a later stage @samford. Other than that, thanks for rewriting most of my docs.

[samford]

Glad to help. I'll try to take another pass at this probably sometime tomorrow, to catch anything else that could still be improved a bit. I already noticed a few things just from a quick glance (due to my tired brain last night), so please don't merge this quite yet.

That said, the changes will be much lighter next pass and will probably just massage the wording in places to improve readability and flow. I think we took care of most of the big changes in the most recent review, so this is getting pretty close to a final draft.

[SMillerDev]

You can suggest changes in the PR UI so if you use that I can copy your version even easier 😄

[samford]

Here's another set of revisions, using real suggestions this time, ahah. Even though I'd seen suggestions in PRs before, I had totally missed that button until I looked up the GitHub documentation for it.

If these suggestions are integrated, I think we'll just need to get some other folks to give it a once over and it'll probably be good to go.

[MikeMcQuaid]

Thanks @SMillerDev, nice work!