improve docs for adding/updating casks/formula #16327
Conversation
0xdevalias
changed the title
There was a problem hiding this comment.
Thanks for the PR @0xdevalias! This is a step in the right direction but a heads-up this may take a few rounds of review to get it just right. Apologies where I've critiqued the existing documentation rather than your changes; it's hard to see and keep track of exactly what is from where (thanks git) but, either way, the documentation will be much better once this is merged.
I also wanted to note explicitly: I had asked you to adjust your tone previously and it seems from this PR that you have taken that feedback on board and very much improved. Thanks you for that: it's both noticed and appreciated ❤️
Note: there's a CI failure on the documentation wording here: https://github.com/Homebrew/brew/actions/runs/7192752171/job/19589809480?pr=16327
| **Note:** Before taking the time to craft a new formula: | ||
|
|
||
| * make sure it can be accepted by checking [Acceptable Formulae](Acceptable-Formulae.md). | ||
| * check that the formula was not [already refused](https://github.com/Homebrew/homebrew-core/search?q=is%3Aclosed&type=Issues). | ||
| * if you are just updating the version of an existing formula, see the streamlined method in ['submit a new version of an existing formula'](How-To-Open-a-Homebrew-Pull-Request.md#submit-a-new-version-of-an-existing-formula). | ||
|
|
There was a problem hiding this comment.
The first and last bullet here repeat links stated in the section before so feel a little redundant.
There was a problem hiding this comment.
Yeah, I thought about that. Originally the content was at the top of the page only. Which in one sense is good, as that's the first place people will look. But then sometimes I know that I will skip straight to the cask/formula section and not look at the rest of the page (doubly so because so many of the Homebrew docs pages are super long/convoluted, so I just try and skim to the bits that seem relevant at the time)
I don't have particularly strong feelings one way or the other here. Whichever is most likely to be seen/followed by the larger number of people was my intent.
Note: Whatever we do here, we should also mirror in #16327 (comment)
There was a problem hiding this comment.
@MikeMcQuaid Do you have a preference based on my comments above? Should we keep this once at the top of the file, or at the top of each cask/formula section?
Particularly noting that at least in my usage, I would normally jump straight to the cask section and not look at the top of the file; and I believe we directly link to the sections from other docs in some cases as well; so my preference would probably be to keep it at the top of the cask/formula sections; and remove it from the top of the file.
There was a problem hiding this comment.
Should we keep this once at the top of the file, or at the top of each cask/formula section?
I don't have strong feelings either way beyond: let's not do it in both places.
There was a problem hiding this comment.
Ok :) Barring anyone expressing strong feelings otherwise, I'll remove it from the top area, and keep the ones in the Formula/Cask sections.
|
Thanks for looking at this @0xdevalias - I will endeavour to have a more thorough read through in the next 24 hours |
|
|
||
| If you've made it this far, congratulations on successfully submitting a Homebrew cask! Your dedication and hard work are highly valued. Take satisfaction in knowing that your contribution provides a valuable addition that will benefit many Homebrew users. | ||
|
|
||
| #### Commit Messages for Homebrew Cask |
There was a problem hiding this comment.
Ultimately I feel like this section should be moved into the Cask Cookbook; similar to how I believe the Formula Cookbook defines its rules there.
Alternatively, moved from both to the 'how to PR' file or similar.
| @@ -186,6 +237,24 @@ Other commonly used stanzas are: | |||
|
|
|||
| Additional [`artifact` stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional Stanzas](Cask-Cookbook.md#optional-stanzas). | |||
|
|
|||
| #### Generating a token for the cask | |||
There was a problem hiding this comment.
This section should be moved to the Cask Cookbok IMO; maybe still linked to as a 1-liner here if super relevant.
This is something I never really think about these days as I just use 'brew create'.
There was a problem hiding this comment.
Agreed, this feels like it could be dropped from the documentation entirely and probably predates brew create being as smart as it is (or maybe even supporting casks at all)
There was a problem hiding this comment.
I'm inclined not to remove it entirely, as there may be cases where this level of knowledge is useful to know; and that feels like it belongs in a section of the Cask Cookbook.
I wish more of the dev tools were explicitly mentioned/documented in the Cookbooks/relevant docs, rather than seemingly only stumbling upon them by accident when someone tells me about it, or I decide to read through the code, etc.
There was a problem hiding this comment.
and that feels like it belongs in a section of the Cask Cookbook.
Agreed.
There was a problem hiding this comment.
I wish more of the dev tools were explicitly mentioned/documented in the Cookbooks/relevant docs
Although: I'm not sure this one needs to exist at all. I've made a bunch of casks and never once used or known about this tool until today. CC @homebrew/cask folks for thoughts if we need to maintain this code.
There was a problem hiding this comment.
I think brew create gets you to the same place as the script.
There was a problem hiding this comment.
I think
brew creategets you to the same place as the script.
brew create seems to use token = Cask::Utils.token_from(name):
Which is defined here:
Whereas generate_cask_token is defined here:
And has a TODO note about merging into brew create:
# generate_cask_token
#
# todo:
#
# detect Cask files which differ only by the placement of hyphens.
#
# merge entirely into "brew create" commandFrom a quick skim, generate_cask_token seems more comprehensive currently.
There was a problem hiding this comment.
I think the documentation still shouldn't reference this any more. After this PR is merged and the reference is removed, an issue can be created to migrate this logic to brew create.
There was a problem hiding this comment.
@MikeMcQuaid If that's opinion only, then I disagree, and feel that the correct time to remove it would be when that functionality has been migrated, as part of that migration.
If that is a "direct order/overruling my judgement" and a blocker on this PR landing.. I'll begrudgingly accept it.
There was a problem hiding this comment.
If that is a "direct order/overruling my judgement"
Yes. Maintainers' judgement trumps yours here, please.
| ``` | ||
|
|
||
| If the `generate_cask_token` script does not work for you, see [Cask Token Details](#cask-token-details). | ||
|
|
||
| #### Cask token details |
There was a problem hiding this comment.
This section should definitely be moved to the Cask Cookbook; maybe still linked to as a 1-liner here if super relevant.
There is an existing section in the Cask Cookbook for this sort of thing; and this rule adds relevant nuance that is currently ambiguous there (assuming this is accurate)
| 8. Go to the relevant repository (e.g. <https://github.com/Homebrew/brew>, <https://github.com/Homebrew/homebrew-core>, etc.) and create a pull request to request review and merging of the commits from your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR. | ||
| If you are using [GitHub two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) and have set your remote repository as HTTPS you will need to [set up a personal access token](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors#provide-an-access-token) and use that instead of your password. | ||
|
|
||
| 8. To create a pull request on GitHub for your changes, you can follow one of these methods: |
There was a problem hiding this comment.
I wonder if we should be so explicit about detailing how to use git here; or if we could just link off the relevant page on GitHub's own help docs.
There was a problem hiding this comment.
If there's one as relevant as these steps: I'm open to exploring that.
There was a problem hiding this comment.
I haven't looked through all of this specifically yet, but this is the vague space of things I was thinking of:
- https://docs.github.com/en/pull-requests
- https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository
- https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
- https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
- etc
I think it's fine for the Homebrew docs to have some quick copy/pasteable 'basic git' commands, and maybe some very slight explanation for it; but it doesn't seem like it should try and handhold users through every possible nuance of learning/using git/GitHub/Pull Requests/etc; which is where I think there is benefit in linking out to the relevant GitHub help docs where they can be way more verbose/explicit/hand holdy.
There was a problem hiding this comment.
I dunno. Reading this again: I think I'd rather we did keep these docs here. They are already written, correct, specific and helpful in a way GitHub's documentation is not.
There was a problem hiding this comment.
@MikeMcQuaid nods fair enough. Do you think we need to keep the full "here are 10 different ways to do it via git" stuff? Or is the simpler stuff that existed before this PR pulled the extra bits over from the older cask section good enough?
I haven't read through this part for a while, but if it fits in with the content that's here well, would you be happy with some kind of short "if you want to know more about THIS_GITHUB_THING, you can read about it in their help docs [LINK]".
Generally when I write technical documentation I like to assume the person knows nothing, and make it as easy as possible to either give them the information, or point them to a canonical source where they can learn more themselves.
There was a problem hiding this comment.
Yes, I think it would be reasonable to slim this down to a single path and remove the alternatives.
There was a problem hiding this comment.
@MikeMcQuaid Can do.
Do you have an opinion on what I mentioned above RE: referencing GitHub's docs? (unless you also intended that by your above comment, but if so, it was unclear)
There was a problem hiding this comment.
Do you have an opinion on what I mentioned above RE: referencing GitHub's docs? (unless you also intended that by your above comment, but if so, it was unclear)
I don't think there's any need. I'm happy to see this slimmed this down to a single path but I don't think GitHub's docs are necessary or helpful here, really.
|
|
||
| 1. It's important to include a good test in your cask. Since the Cask Cookbook doesn't provide specific guidance on this, you can refer to the [Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula) section in the Formula Cookbook for assistance. |
There was a problem hiding this comment.
| 1. It's important to include a good test in your cask. Since the Cask Cookbook doesn't provide specific guidance on this, you can refer to the [Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula) section in the Formula Cookbook for assistance. |
We don't have separate tests for casks.
There was a problem hiding this comment.
What do you mean? These docs are partitioned into "things to be done for Formula" and "things to be done for Casks"; there is no "separate things to be done for both" as that would clutter the way it is currently laid out and make it harder to follow (though adds some duplication)
Tests are required for casks, but the Cask Cookbook doesn't explicitly talk about implementing them; therefore this step is directing the user to the Formula Cookbook for the specifics on implementing them in a Cask; specifically because they aren't 'separate'.
There was a problem hiding this comment.
Tests are required for casks
Actually... now i'm not sure if this is true.. I thought I had to implement them recently.. but thinking more about it.. I think those were Formula.
So to clarify, by "We don't have separate tests for casks" do you mean that individual casks don't implement tests at all?
If so, fair; but then rather than removing this point, I would probably adapt it to say something explicit like (wording to be improved):
Unlike Formula, there is no need to implement a test block for a Cask.
That way a user isn't left wondering why there is a difference between Formula and Casks, if the docs are just outdated, etc.
There was a problem hiding this comment.
Casks do not implement tests like Formula
There was a problem hiding this comment.
@krehel Thanks for confirming.
In that case, I will change this section to mention that as outlined above.
| end | ||
| ``` | ||
|
|
||
| 1. You will now have to develop the boilerplate code from `brew create --cask` into a complete cask. Your main references will be the [Cask Cookbook](Cask-Cookbook.md), similar existing casks, and the official documentation of the software you're packaging. |
There was a problem hiding this comment.
Not sure if we want to add this here or in the cookbook/acceptable casks, but I would want to mention that new casks should contain a working livecheck and a zap.
There was a problem hiding this comment.
Agree that it is definitely worth mentioning. Not sure off the top of my head whether here or Cask Cookbook makes more sense; but I am somewhat leaning towards Cookbook (unless it's a short line that then links to the section of the cookbook for more details).
Particularly as I would prefer to slim the Cask section of this doc down even more to make it closer to the bullet point list of the Formula section.
I also feel like the Cask Cookbook should be the canonical source for all of these details and snippets; and other places should only briefly reference them and link to it in general. Otherwise information ends up too fragmented across different documents, as it currently is; and then it gets ambiguous when things get out of sync between them all + harder to update and maintain them in general.
There was a problem hiding this comment.
@razvanazamfirei Does brew create add those lines? If not, it should. If so (and enforced by brew audit which we point to): it seems fine as-is.
There was a problem hiding this comment.
I also feel like the Cask Cookbook should be the canonical source for all of these details and snippets; and other places should only briefly reference them and link to it in general.
Agreed.
There was a problem hiding this comment.
Does
brew createadd those lines? If not, it should. If so (and enforced bybrew audit
@MikeMcQuaid @razvanazamfirei To my knowledge, it doesn't currently. I raised this (and some other related frictions) in an issue I opened today:
|
|
||
| Keep in mind that these checks will happen automatically when you submit your pull request. Completing them beforehand not only saves time but also makes the whole process smoother for everyone. | ||
|
|
||
| If your application and Homebrew Cask do not work well together, feel free to [file an issue](https://github.com/Homebrew/homebrew-cask#reporting-bugs) after checking out open issues. |
There was a problem hiding this comment.
Would suggest opening a discussion instead.
There was a problem hiding this comment.
See discussion about this for the Formula section here:
Given homebrew-cask explicitly mentions this section in the README, and this was what was linked to in these docs originally/before this PR, why would we not point to it and instead point to discussions?
And if that isn't the correct place to direct people to; then should the README there also be updated/that section removed?
One of my current issues is that there is a lot of fragmentation and lack of consistency across the README, CONTRIBUTING, PR Templates, Docs, etc; which makes it ambiguous and confusing for someone to try and figure out the right way to do things.
So whatever the ultimate decision here ends up being; I want it to be aligned and consistently communicated in docs/README/etc
There was a problem hiding this comment.
Given
homebrew-caskexplicitly mentions this section in the README, and this was what was linked to in these docs originally/before this PR, why would we not point to it and instead point to discussions?
This documentation is outdated before we had discussions. We don't want these sorts of discussions in issues any more.
then should the README there also be updated
Yes.
So whatever the ultimate decision here ends up being; I want it to be aligned and consistently communicated in docs/README/etc
Agreed 👍🏻
There was a problem hiding this comment.
This documentation is outdated before we had discussions. We don't want these sorts of discussions in issues any more.
@MikeMcQuaid Are you sure that's accurate to what's being talked about here?
The Homebrew Cask README 'Reporting Bugs' section seems to be a bunch of troubleshooting things:
That as it's very last entry links to:
[My problem isn't listed](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.yml)
That bug report template seems to exist and be valid still.
And it's the same place I end up if I start at the 'new issue chooser':
And click 'Reproducible Bug Report'
So as I see it, either your comments above are inaccurate/don't apply to what's being talked about here; or all of those things are wrong and need to be changed.
If the latter, then it's also potentially wrong here too, as they all contain the same 'Reproducible Bug Report' entry:
There was a problem hiding this comment.
@0xdevalias This is specifically related to when there are questions/incompatibilities that arise due to the specific app/formula that is being submitted to homebrew-cask/homebrew-core. In this instance, opening a discussion as opposed to an issue is preferred, as it isn't a "bug" per se, but assistance/discussion being sought to help create a cask/formula that works in the specific situation.
There was a problem hiding this comment.
@bevanjkay So for homebrew-cask, are you saying:
- that these docs should point directly to discussions, or to the 'Reporting Bugs' section of the README, or to the 'issue chooser'?
- that the "My problem isn't listed" link in the 'Reporting Bugs' section of the README should point to discussions, or the existing bug report template, or the issue chooser?
Personally, I feel the issue chooser is a good canonical place to point to, that already specifically includes all of the relevant information and links someone could want; and so it seems like a far better place than to link directly to discussions.
I already raised that case earlier and seems I am overruled, but to try one final time: confirming that the 'official decision' here is that we want to create multiple places that link to different things that can get out of sync and will increase maintainer burden, rather than just pointing to a single canonical location that will by definition stay in sync and correct without anyone having to do anything?
There was a problem hiding this comment.
- that these docs should point directly to discussions
When it's "assistance/discussion being sought to help create a cask/formula that works in the specific situation": it should be a discussion. When it's a bug with an existing formula: it should be a bug.
here is that we want to create multiple places that link to different things that can get out of sync and will increase maintainer burden
@0xdevalias I appreciate your intent here but, respectfully, we have a much better idea of the things that will increase maintainer burden than you do. You are not factoring in the number of people who, when presented with an issue chooser, will intentionally or unintentionally choose the wrong item. Being pointed to discussions means they will not accidentally open an issue. When it "seems I am overruled": please leave it at that and let's move on to the other bits on this PR so it can get merged, thanks ❤️
There was a problem hiding this comment.
When it "seems I am overruled": please leave it at that and let's move on to the other bits on this PR
@MikeMcQuaid There were 2 parts in my above comment; one seeking explicit clarification required before I can action this step; the other the bit you highlighted here. While I understand your intent with it, this feels like another case of 'over reacting' (for lack of a better term) to something that a simple "yes, confirming that we accept that risk" would have sufficed.
When it's "assistance/discussion being sought to help create a cask/formula that works in the specific situation": it should be a discussion. When it's a bug with an existing formula: it should be a bug.
@MikeMcQuaid I'll have to re-read this section again to say for sure; but from what I remember of it, that does nothing to remove the ambiguity I was seeking to clarify above (as it specifically relates to this section)
Unless you're telling me to add 2 lines/links here; but I don't think that is your intent?
There was a problem hiding this comment.
Do this please:
| If your application and Homebrew Cask do not work well together, feel free to [file an issue](https://github.com/Homebrew/homebrew-cask#reporting-bugs) after checking out open issues. | |
| If your application and Homebrew Cask do not work well together, feel free to [open a discussion](https://github.com/orgs/Homebrew/discussions/new/choose) to get help. |
|
RE: #16327 (review)_
@MikeMcQuaid No worries :) I expected a change like this would take some time in review; but it will ultimately make my (and others) lives easier; which is why I chose to do it.
@MikeMcQuaid On one level, I appreciate this acknowledgement; though on another, it feels disingenuine to accept it without sharing my truth alongside doing so. It's off-topic of this PR, so I will put it in an expandable; and I wanted to note up front that I share this with genuine good intent, in the hopes that like my efforts on the documentation in this PR, my feedback below will improve Homebrew for everyone. I don't have any particular desire to have a deep back and forth about it, and ultimately whether you take the feedback on board or not is beyond the scope of my control. It's provided from my perspective, and may not be representative of 'the whole', nor of 'objective truth'; take what works and leave the rest; there will be no ill will on my side either way. FeedbackI want to start by saying that based on our past interactions, and the feeling that that left with me, I spent a lot of time umming and ah'ing as to whether I would even be able to share this without it being blown out of proportion, and potentially this whole PR closed and discarded in 'retaliation'. That may seem overblown, or not match your perspective of the situation; but that is the genuine feeling I was left with after our last interactions, and that 'trauma' (for lack of a better word) continues to exist now. This PR demonstrates there is no issue communicating in more general cases, particularly about the code/docs/etc, but my fear is that direct feedback will be received 'poorly', based on those recent interactions. I hope I am proved wrong. -- RE: my originally expressing frustration in a suboptimal way (Ref); yes, I potentially could have found a way to communicate it better; but that doesn't change the core of the issue I was attempting to communicate; which was the genuine friction and frustration with how some things are done in Homebrew; and how that dampens my desire to contribute due to it feeling like it is made harder than it needs to be. I understand why you jumped in and commented as you did (Ref), but I also want to say that in doing so, it sort of had an 'escalating' effect on things. One way that that interaction would have been improved, from my perspective, could have been opening with "I can see that you are frustrated by the Homebrew's processes here, but...", and even if you then sent the rest of your comment as it was written, it would have come across far better. From my perception, after that comment, you jumped across to another unrelated issue I had open, and (again, from my perspective), appeared to close it (Ref) without fully addressing the most up to date point of improving the docs (Ref). I tried to communicate that (Ref), which you appeared then seemed to read a 'tone' in my messages that I wasn't intending to exist (Ref). The conversation then further de-railed as (from my perspective) I tried to explain my intent and rectify what appeared to be a misunderstanding/miscommunication (Ref), and ask you to consider the possibility that there was a misunderstanding. Your first reply (Ref) to that seemed somewhat productive; but also seemed to double down on essentially (as I perceived it) "i am important, you are not", "my feelings are important, yours are not", "there is zero change I could have misperceived something, so it's your problem to try and fix it", etc. Regardless of how I felt about those concepts (as I perceived them to exist), I know that ultimately me disagreeing won't change things if the other party is unwilling to engage about them, so I changed tacts to trying to avoid 'triggering' your perception of 'bad tone' in my writing. I did that by using a method I have used effectively in the past, 'translating' my normal way of writing through ChatGPT to reduce the chance of someone misinterpreting it (as text is a poor form of conveying the richer nuances of communication). (Ref) I chose to explicitly mention the fact I did that as context, as I believe open and transparent communication is important, and with the hopes that in doing so you would see that I was trying to make an effort to adjust my style in a way that you would be able to receive it better, even if I disagreed with your reasoning. I then used that method to take my 'raw' replies, 'translate' them into a style that hopefully would be interpreted better and then checked/reviewed/reiterated/tweaked the output to ensure it conveyed the truth of what I wanted to say. The feedback there was given in the same form as this feedback here is (with the same intent/caveats/etc I described in the intro of this comment); and with the genuine desire to improve the Homebrew experience for everyone. I stand by that feedback as much now as I did then. My attempt to adapt and improve my style to reduce miscommunications seemed to have the opposite effect; and your next/last reply (Ref) seemed to miss the genuine attempt I was making, and somewhat amusingly, seeming to hold a double standard to how you were interpreting/responding to me, without (from my perception) applying those same standards to how you were responding. You appeared to take my attempt to reduce the miscommunication as some kind of 'negative'/attack'/similar; and then took essentially (what comes across as, from my perception) a 'dictator' / 'schoolyard bully' approach of locking the 2 issues, and threatening to ban me if I attempt to use ChatGPT as a communication aid in future. (Ref). Throughout the process (with the exception of my first inarticulate signal of frustration), I was attempting to identify what appeared to be cases of miscommunication, try and understand and communicate where they appeared to be, and attempt to provide relevant context that I hoped would resolve the miscommunication. Even before using ChatGPT to translate my writing style, I changed it to be more explicit and articulate (including pointing out where it may have been my own perception, and not an objective reality, etc), in the hopes that that would reduce the miscommunications. That is also the style I have taken in writing this feedback here today. (Which is written by my own hand, and not 'translated' through ChatGPT). This is a mini tweet thread I wrote shortly after that (Ref), in which I attempted to briefly (3 short tweets) summarise the issues of written communication, neurodiverse brains, empathy, and aides; in the space of diversity / inclusivity, and not discriminating against/punishing people for using aides, or who don't perfectly conform to your desired style. Separately, while I don't know the specifics of the individual situations, and I don't generally base my opinions on 'hearsay' / 'gossip' / etc; after those interactions I did stumble upon a few cases where others seemed to have disagreements/miscommunications/etc with you in the past; and who seemed to feel that they were also unfairly dismissed in a 'heavy handed' way. I share this here only to highlight that there is a possibility that my feedback isn't just representative of only my own single perspective. I may be wrong in believing that; those other peoples stories may be completely different, or they may have been entirely in the wrong; and if that is the truth of it, then that's fine, and you can disregard this point. I'm not asking for an apology; as I personally put very little value in (potentially empty) words like 'sorry'. What I find more important is people being open to receiving feedback, genuinely listening to it, genuinely reflecting on it, and when appropriate, acknowledging the mistakes/miscommunications/etc and taking action to improve that for future. That is the spirit that this feedback is shared in, and the hope that I have for it; but ultimately, whether you read/reflect/potentially change is outside of my control, and I accept that. I also accept that my feedback may entirely be my own perceptions that aren't matched by others, or by an objective view of things; and I also accept that possibility. Anyway, now that I have articulated that and shared my truth; back to the PR in general. |
@0xdevalias Glad to hear it! On the feedback section: I'm happy to discuss more of it privately if there's a better forum for that (e.g. email) but am a bit cagey about putting some personal details that may be illuminating on the public internet. One bit I do want to touch on:
Regardless: I am sorry that my communication was non-ideal and that it negatively affected you. This was not my intention and I'm glad we've been able to get to a better place in this PR. I think we're mostly aligned/agreed here. Where we do differ is that I put a lot of value in words like "sorry" or "I apologise" and am willing to cut people a lot more slack when they seem to be trying to communicate an apology. In our previous interactions: it did not seem to me that you were trying to apologise or had taken my feedback on board and if I had perceived that it would have gone pretty differently. I may well have been completely wrong there, sorry if so, but acting at the volume and with the number of bad actors (to be clear: you are not one) that Homebrew does/has for over a decade has made me lean on pattern-matching instead of being able to give each situation the nuance it ideally would receive in a perfect world. |
Co-authored-by: Mike McQuaid <[email protected]>
…n formula cookbook
@MikeMcQuaid nods Understandable. Happy for you to email me on my git commit address.
@MikeMcQuaid Agreed.
@MikeMcQuaid Fair enough, and understandable. I guess that was what I was trying to get across in some of my original comments as well, that it can be useful and important to take a step back sometimes, and consider alternate viewpoints/possibilities from our default; lest it lead to misunderstandings and miscommunications that were otherwise avoidable. Also sometimes knowing when to just walk away from the keyboard/take a breath when things feel too stressful/emotions feel high; as otherwise that can lead to reactions/interpretations made from a place other than our highest/best mind.
@MikeMcQuaid nods, again, I can totally understand why that would be the case. I don't really have a 'good solution'; but hopefully you're able to find a middle ground between the black/white of those extremes, where you're not spending unnecessary time/energy on 'bad actors'; but that also allows you to not push away the good potentials by jumping to a conclusion too quickly. |
@0xdevalias Thanks, I hope so too. Just to be very explicit about where we are at: I appreciate this PR here but I am definitely having to spend too much time/energy right now trying to convince you to argue less, give me less life/open source maintenance advice and seek clarification without needing to critique my communication many of the times. |
@MikeMcQuaid For continuity, bundled this here (Ref) so as not to fragment/have either of us need to spend more time on it than needed. |
|
Will reconsider these changes post-block. For more context, see here: #16342 (comment) |
brew stylewith your changes locally?brew typecheckwith your changes locally?brew testswith your changes locally?I've generally found that there is a lot of confusion/repetition/occasional conflicts in the Homebrew documentation that can make it ambiguous and sometimes confusing for new contributors. The duplication/spread of information also likely makes it harder for maintainers to ensure it is kept up to date.
This is my first pass attempt at cleaning up/unifying some of the Formula / Cask docs for Adding/Updating/etc.
My intent with this PR was primarily to align the Formula / Cask sections in
docs/Adding-Software-to-Homebrew.mdso they follow roughly the same flow/language/etc; and secondarily to move some of the 'extra' information that was under the 'Casks' section either further down into the 'Additional Cask Details and Examples' section, or intodocs/How-To-Open-a-Homebrew-Pull-Request.md.I also updated some outdated references to
--new-formula/--new-caskas per:--new-formula/--new-caskoptions. #16297--new-caskin PR template homebrew-cask#161724If this
brew install --localwork lands before this PR, then we should make further changes to theHOMEBREW_NO_INSTALL_FROM_API=1parts in these docs:brew install --localflag #16325There is no doubt further cleanup that could be done to the docs in general (eg. moving more of the Cask specifics into the Cask Cookbook, further reducing duplication, etc), but unless it's strictly related to the changes being made here, I'd like to suggest that those changes get made in future PRs (as I am wary of the potential for scope creep / getting busy / etc and these improvements never landing)
These are also tangentially related to improving usability/guiding users:
--helpdocs to denote which commands/flags apply to Formula, which to Casks, and which to both #16334brew create --cask+ related tools/docs to reduce friction/manual effort/prior knowledge required #16342