Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add guides for common cases #6996

Open
wants to merge 5 commits into
base: master
from

Conversation

@SMillerDev
Copy link
Member

SMillerDev commented Feb 3, 2020

  • 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).

@SMillerDev SMillerDev force-pushed the SMillerDev:docs/guides branch from 0959b60 to 37d04b4 Feb 3, 2020
@SMillerDev SMillerDev requested review from EricFromCanada and MikeMcQuaid Feb 3, 2020
Copy link
Member

issyl0 left a comment

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.

docs/Addition-Guide.md Outdated Show resolved Hide resolved
docs/Addition-Guide.md Outdated Show resolved Hide resolved
docs/Addition-Guide.md Show resolved Hide resolved
docs/Addition-Guide.md Outdated Show resolved Hide resolved
docs/Update-Guide.md Outdated Show resolved Hide resolved
SMillerDev and others added 4 commits Feb 4, 2020
Co-Authored-By: Issy Long <me@issyl0.co.uk>
Co-Authored-By: Issy Long <me@issyl0.co.uk>
Co-Authored-By: Issy Long <me@issyl0.co.uk>
Co-Authored-By: Issy Long <me@issyl0.co.uk>
@SMillerDev

This comment has been minimized.

Copy link
Member Author

SMillerDev commented Feb 4, 2020

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?

Copy link
Member

MikeMcQuaid left a comment

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?

@@ -1,5 +1,11 @@
# Documentation

## What if?

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member

Feel this would be better under Users. Could maybe be grouped with a line break at first?

@@ -0,0 +1,23 @@
# What if I want software added?

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member

Can this title match the filename?

@@ -0,0 +1,5 @@
# What if I have an issue?

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member

Can this title match the filename?

@@ -0,0 +1,7 @@
# What if I want software updated?

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member

Can this title match the filename?

Nobody did? Good, you're still the best person to resolve this.

## Before you begin
Check if the software is acceptable for Homebrew by reading the [requirements](Acceptable-Formulae.md). If the software is a version of already accepted software, read the [version requirements](Versions.md).

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member
Suggested change
Check if the software is acceptable for Homebrew by reading the [requirements](Acceptable-Formulae.md). If the software is a version of already accepted software, read the [version requirements](Versions.md).
Check if the software is acceptable for Homebrew by reading the [acceptable formulae requirements](Acceptable-Formulae.md). If the software is a version of already accepted software, read the [versioned formulae requirements](Versions.md).
Check if the software is acceptable for Homebrew by reading the [requirements](Acceptable-Formulae.md). If the software is a version of already accepted software, read the [version requirements](Versions.md).

## Writing the formula
1. It's a good idea to look up some brewed software that is similar to your favorite software in language and/or build method and look at the formula code for that to gather some inspiration.

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member
Suggested change
1. It's a good idea to look up some brewed software that is similar to your favorite software in language and/or build method and look at the formula code for that to gather some inspiration.
1. It's a good idea to look up some software in Homebrew that is similar to your favorite software in language and/or build method and look at the formula code for that to gather some inspiration.

## Writing the formula
1. It's a good idea to look up some brewed software that is similar to your favorite software in language and/or build method and look at the formula code for that to gather some inspiration.
2. You can use the [create command](Manpage.md#create-options-url) to get a basic version of your new formula.

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member
Suggested change
2. You can use the [create command](Manpage.md#create-options-url) to get a basic version of your new formula.
2. You can use the [`brew create` command](Manpage.md#create-options-url) to get a basic version of your new formula.
## Writing the formula
1. It's a good idea to look up some brewed software that is similar to your favorite software in language and/or build method and look at the formula code for that to gather some inspiration.
2. You can use the [create command](Manpage.md#create-options-url) to get a basic version of your new formula.
3. With that basic version, your inspiration, [the cookbook](Formula-Cookbook.md) and the upstream documentation you are probably finish off your formula. Also note the specific comments for [python](Python-for-Formula-Authors.md) and [node](Node-for-Formula-Authors.md).

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member
Suggested change
3. With that basic version, your inspiration, [the cookbook](Formula-Cookbook.md) and the upstream documentation you are probably finish off your formula. Also note the specific comments for [python](Python-for-Formula-Authors.md) and [node](Node-for-Formula-Authors.md).
3. With that basic version, your inspiration, [the cookbook](Formula-Cookbook.md) and the upstream documentation you are probably finish off your formula. Also note the specific comments for [`python`](Python-for-Formula-Authors.md) and [`node`](Node-for-Formula-Authors.md).
1. Is your test running fine? Use `brew test <formula>`, where <formula> is the name of the formula you're writing? Make sure you have a good test. If you're not sure you can check the [cookbook](Formula-Cookbook.md#add-a-test-to-the-formula).
2. Does your build pass `brew audit --strict --new-formula --online <formula>` (after doing `brew install <formula>`)? If it doesn't, make sure you fix the issues before submitting it for inclusion.

The guide on [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md) should really be all you need to submit your formula to be used by all Homebrew users then.

This comment has been minimized.

Copy link
@MikeMcQuaid

MikeMcQuaid Feb 5, 2020

Member
Suggested change
The guide on [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md) should really be all you need to submit your formula to be used by all Homebrew users then.
The guide on [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md) should really be all you need to submit your formula for use by all Homebrew users.
@MikeMcQuaid MikeMcQuaid mentioned this pull request Feb 5, 2020
6 of 6 tasks complete
@MikeMcQuaid

This comment has been minimized.

Copy link
Member

MikeMcQuaid commented Feb 5, 2020

Unrelated test failures should be fixed by #7003

@SMillerDev

This comment has been minimized.

Copy link
Member Author

SMillerDev commented Feb 6, 2020

Easily linkable but also easily understood.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants
You can’t perform that action at this time.