docs: add deprecate/disable/removal documentation #10144
Conversation
Rylan12
added
discussion
|
Review period will end on 2020-12-28 at 03:47:53 UTC. |
1 similar comment
|
Review period will end on 2020-12-28 at 03:47:53 UTC. |
BrewTestBot
added
the
waiting for feedback
|
Thanks for this, @Rylan12! |
Co-Authored-By: Carlo Cabrera <[email protected]>
|
Can you add links to this in the formula cookbook as well, since that is supposed to be a complete list of syntax references IMHO. |
|
|
||
| If these pre-existing reasons do not fit, a custom reason can be specified. These reasons should be written to fit into the sentence `<formula> has been deprecated/disabled because it <reason>!`. | ||
|
|
||
| Here are examples of a well-worded custom reason: |
There was a problem hiding this comment.
I'm not sure we have to teach people grammar in the homebrew documentation.
There was a problem hiding this comment.
I agree this may be too much handholding but we do have a few issues currently in homebrew/core so I don't think this part should totally be removed.
See liblwgeom:
Warning: liblwgeom has been deprecated because it liblwgeom headers are not installed anymore, use librttopo instead!
And exomizer:
Error: exomizer has been disabled because it custom license!
There was a problem hiding this comment.
I think a formula author/maintainer would reasonably expect:
... because: "<reason>"
to produce the message:
[This is happening] because <reason>.
rather than:
[This is happening] because it <reason>!
In the case of exomizer, "because it custom license" is just wrong, but "because custom license" accords with modern usage, though it's anathema for grammar pedants. 😆
There was a problem hiding this comment.
@gromgit I agree that this makes sense. This is how I initially created it, but at some point, it was decided that since most of the reasons already started with "it", the "it" should be added by default. See #8549 (comment) and Homebrew/homebrew-core#60321 (comment). TBH I think it could be changed, now that we have the symbols available.
There was a problem hiding this comment.
Some comments here but this is fantastics, great work @Rylan12!
Co-Authored-By: Seeker <[email protected]> Co-Authored-By: Sean Molenaar <[email protected]> Co-Authored-By: Mike McQuaid <[email protected]> Co-Authored-By: Michka Popoff <[email protected]>
|
Thanks for the reviews, everyone! I made some changes (I removed the highly contentious "serious issues" phrase). There are a few comments that I left unresolved because I needed more clarification or wasn't quite in agreement with everyone involved. |
Co-Authored-By: Carlo Cabrera <[email protected]>
Co-Authored-By: Adrian Ho <[email protected]>
|
Review period ended. |
BrewTestBot
removed
the
waiting for feedback
Co-Authored-By: Mike McQuaid <[email protected]> Co-Authored-By: Michka Popoff <[email protected]> Co-Authored-By: Carlo Cabrera <[email protected]>
Co-Authored-By: Mike McQuaid <[email protected]>
|
Thanks, everyone! |
that is very nice!! |
It would be even nicer if that final check would run... 😉😭 |
brew stylewith your changes locally?brew typecheckwith your changes locally?brew testswith your changes locally?brew manlocally and committed any changes?We don't have any official documentation about deprecating, disabling, and removing formulae. I've tried to document my thought process (which I think mirrors several that of several other maintainers). This is prompted by Homebrew/homebrew-core#66360 where @bayandin and @SMillerDev shared their thoughts. My thoughts aligned with theirs, so this PR is a conglomeration of our ideas.
I'd like to get feedback from other @Homebrew/core maintainers to make sure that everyone is on the same page about what's in the documentation. If I've written something that not everyone agrees with, we should come to a consensus to clarify expectations for all maintainers (and users).