Documentation

[lhazlewood]

Hello!

homebrew-bundle looks great, but I have no idea how to use it effectively.

For any given line item in a Brewfile:

• what does it do?
• what are all the various options supported by that line command and what does each one do?

I see this example in the Readme's Usage section:

brew "mysql@5.6", restart_service: true, link: true, conflicts_with: ["mysql"]

How would I know that link or conflicts_with were options if it weren't for this example? Also what does each do? Are there any other options that a brew line supports? How would I find out?

While I am an experienced software engineer, I've never programmed anything in Ruby more than a single file to get a feel for some of the language idioms, so dumpster diving in the source code to try and figure out if/how/when things might be supported isn't really a great option.

Anyway, keep up the great work - I'm just trying to get some guidance here to help me understand how to use homebrew-bundle effectively. Any pointers?

[MikeMcQuaid]

brew bundle --help and the README are the limits of our current documentation, sorry.

[lhazlewood]

@MikeMcQuaid wouldn't you want to keep this issue open as a tracker so that proper documentation could be established? I don't understand the speed at closing an issue that clearly represents something that is needed for the project?

[MikeMcQuaid]

@lhazlewood I'm afraid I don't agree that this project is lacking in proper documentation or that it's clearly needed. I'm open to accepting any pull requests from you or others to improve the documentation but it seems most people using the tool above have been able to answer the questions you've asked from the documentation.

As another aside, your question is more along the lines of a support request ("please help me X") rather than a bug ("I ran X and it threw an exception") or an actionable documentation issue ("X is undocumented") and Homebrew and/or my open source projects tend not to provide support requests or keep issues open that affect a single user (when the tool has many users).

[lhazlewood]

With respect, this isn't a 'help me do X'. The action item is:

Please document each bundle command and option available to use for that command in a Brewfile.

That doesn't seem like a far-fetched request right?

In other words, when I author a Brewfile, how do I know what I can do for each line that starts with brew, cask or mas?

There isn't any documentation in the project anywhere that indicates what each option is and what each option does for said line prefixes.

Does this make sense? I'm not trying to be difficult - I'm trying to get to the root of the issue that examples are not actual documentation for commands and options.

I'd be happy to issue a PR, but I have no clue what the options are, or what each option does and/or why it exists. If you can show me that, I'd be more than happy to submit one :)

HTH.

[lhazlewood]

To make this more concrete, I'll show this example from the Readme again:

brew "mysql@5.6", restart_service: true, link: true, conflicts_with: ["mysql"]

• what does restart_service do, and under which circumstances is it valid? (is it always valid? what if the brew package doesn't represent a service?).

• what does the link option do? What impact does it have on the underlying homebrew installation? If it's a passthrough to a Homebrew command-line flag, can a link be provided to that flag's documentation so we know what does?

• what does conflicts_with do? what happens if there is a conflict? Even a passthrough link would be helpful.

• does a brew line in a Brewfile support any other options other than restart_service, link and conflicts_with? If so, what are they and what do they do?

Hopefully this makes more sense.

EDIT: cc'ing @MikeMcQuaid to see if this qualifies as actionable work per your last comment.

[MikeMcQuaid]

Please document each bundle command and option available to use for that command in a Brewfile.

We've documented each bundle command. Not every option is documented but I don't think they need to be as brew bundle dump outputs them when needed. If you disagree: you can read the code and submit a pull request to the README and --help documentation.

I'd be happy to issue a PR, but I have no clue what the options are, or what each option does and/or why it exists. If you can show me that, I'd be more than happy to submit one :)

It's all in the code and this is not a large project. If someone else reads this thread and wants to answer the specific questions that's 🆒 but I can't personally justify it until we have (a lot) more people asking the same questions and it becomes clear that no-one else can understand the code.

[lhazlewood]

Thanks for the reply @MikeMcQuaid - I appreciate it.

I can't say I'm not disheartened and a little shocked by the reply however - the point of documentation is so that users (especially those who don't program in Ruby for a living) don't need to dumpster dive through code just to learn how to author a Brewfile.

Think of if you had to author a .travis.ymlfile without having https://docs.travis-ci.com/user/customizing-the-build to reference. Or a docker-compose.yml file without https://docs.docker.com/compose/compose-file/ And then if those project teams told you "sorry, go look at the source code to figure out what options exist". That'd feel pretty rough, no?

The reason why the command line call reference of brew bundle dump isn't good enough in this case is that the user interface experience is not command-line based when authoring content files. You use a text editor. That's a critical difference because the information/troubleshooting flow is a totally different experience.

So I have a request: Can you please re-open this issue as an actionable work item with a tag like 'Help Wanted' (or similar)? If you consider it a low priority and personally don't want to work on it, that's totally cool, but while this remains closed, anyone looking to help the project (if they feel so inclined) wouldn't even know that this help would be appreciated.

Thanks for your consideration - all the best!

[MikeMcQuaid]

I can't say I'm not disheartened and a little shocked by the reply however - the point of documentation is so that users (especially those who don't program in Ruby for a living) don't need to dumpster dive through code just to learn how to author a Brewfile.

You're being hyperbolic here; I'm only suggesting you need to go through the code to understand what every possible option does if you wish to use and document them. Every command is documented and brew bundle dump means you never need to author a Brewfile yourself, anyway.

Think of if you had to author a .travis.ymlfile without having https://docs.travis-ci.com/user/customizing-the-build to reference. Or a docker-compose.yml file without https://docs.docker.com/compose/compose-file/

It's a good thing that you raised those examples; those are both for-profit companies with paid engineers. Additionally, there are undocumented behaviours in both of those YAML files that require you to look at the source anyway.

I'm pretty much the sole developer at this point of Homebrew Bundle, I'm on paternity leave from my job and I have never made a penny/cent from Homebrew's development.

The reason why the command line call reference of brew bundle dump isn't good enough in this case is that the user interface experience is not command-line based when authoring content files. You use a text editor. That's a critical difference because the information/troubleshooting flow is a totally different experience.

If you wish to work that way that's up to you. That's not how it's designed to be used.

Can you please re-open this issue as an actionable work item with a tag like 'Help Wanted' (or similar)?

I'm still not sure what the actionable item is because you keep implying Homebrew Bundle is completely lacking in sufficient documentation. If you have a narrower ask ("please document in the README each option used in the README" or "please document in the README each option that brew bundle dump may output: maybe; it depends on whether I think there's people who are willing to read through the source and figure this out (as you are not, it seems). If the end result of opening that issue is "@MikeMcQuaid needs to read through the source and explain what all the options are and mean" then it's essentially asking me to do all the work myself (as it would be significantly more time efficient than explaining, reviewing and merging a PR).

anyone looking to help the project (if they feel so inclined) wouldn't even know that this help would be appreciated.

I don't agree with you that a closed issue means that no-one would find this issue.

Finally, as I've said above: I'm not convinced that this is a problem that is experienced my many people who aren't you. To use the Travis CI or Docker examples before: would you expect for-profit companies to add something to the product roadmap (that's essentially what a help wanted issue is for open source projects) due to the request of a single person?

If others do think that this documentation is badly needed but are also unable or unwilling to read through the source: please comment on this issue.

[ghost]

I actually put much effort into understanding homebrew and tried to read the source code, even learned ruby but homebrew itself was just way to undocumented for me to even get a grip. There seems to be no documentations about the underlying control flow, how formulas are managed internally.

About this specific issue with homebrew bundle, I agree with the OP that the options should be documented properly and I think this should be part of every initial commit and not a hindsight but now it is the it is so maybe someone can improve it.

It's also definitely clear that your time is limited and this is an OS project with no guarantees.

[lhazlewood]

Thanks for the reply @MikeMcQuaid ! This provides some really useful insight into the state of things that I wasn't aware of. FWIW, when I open an issue for a command available in homebrew by default, I'm assuming (due to the huge size of the user base) that there are a few (or more) people that might be able to help - I'm definitely not jumping on you nor criticizing your (awesome) contribution to the brew community overall - I was just trying to be helpful in explaining that I think there are some gaps that could benefit people (IMO at least).

Some notes:

If you wish to work that way that's up to you. That's not how it's designed to be used.

I thought I needed a reference on what/when options can be used because the Usage documentation section currently looks like this:

This seemed pretty clear to me as a new bundle user that I'm supposed to author the files myself (where an option reference would be important).

please document in the README each option that brew bundle dump may output

Yes, this, exactly :)

it depends on whether I think there's people who are willing to read through the source and figure this out (as you are not, it seems)

It's definitely not that I'm not willing - I'm totally willing when I can scrape some time for this (we share a lack-of-free-time predicament ;) ). Because I've never worked with Ruby for anything beyond toy testing, I was trying to avoid the potential hours of trying to figure out what stuff does and how it works. I was pretty sure that one of the authors of bundle (which only now I understand is just you) could do that in a matter of minutes (or at least point out what they are so I can look further), so I didn't think it something too burdensome to ask.

In any event, I definitely have a much better feel for your thoughts, and I'm sorry to take up your time while on paternity leave. Hopefully I (or others) will be able to submit a PR if I/they can find the time. Please enjoy your time off, and thanks again for the work you do for Homebrew and for the help you are able to give. I for one greatly appreciate it.

[johnthagen]

If you are looking for how to add the --HEAD option to dependency within a Brewfile see this SO post.

I couldn't figure this out until I read this thread and saw that rather than find documentation on how to write Brewfiles, brew dump should be used to generate them.