Repository navigation
docs: unify formula and cask description guidelines - #24256
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info
📜 Recent review details
📝 Summary
Merge Risk: ⚪ Minimal · up to
|
| Check name | Status | Explanation |
|---|---|---|
| Title check |  |
The title clearly and concisely describes the main change: unifying formula and cask description guidelines. |
| Description check | |
The description directly explains the shared Description-Guidelines page and the purpose of the documentation changes. |
| Linked Issues check | |
Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | |
Check skipped because no linked issues were found for this pull request. |
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Comment @coderabbitai help to get the list of available commands.
![coderabbitai[bot]](/p/https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
- Configuration used: Organization UI
- Review profile: CHILL
- Plan: Advanced
- Run ID:
859184d1-00bb-48d5-bc1a-cc3a12dfd8a7
📒 Files selected for processing: 6
Library/Homebrew/cask/dsl.rbLibrary/Homebrew/formula.rbdocs/Cask-Cookbook.mddocs/Description-Guidelines.mddocs/Formula-Cookbook.mddocs/index.md
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout: 19
- GitHub Check: docker (arm64 Ubuntu 26.04)
- GitHub Check: docker (arm64 Ubuntu 24.04)
- GitHub Check: docker (x86_64 Ubuntu 24.04)
- GitHub Check: docker (x86_64 Ubuntu 26.04)
- GitHub Check: tests (load-only Linux)
- GitHub Check: docs
- GitHub Check: tests (generic OS, 2/2)
- GitHub Check: tests (generic OS, 1/2)
- GitHub Check: tests (Linux, 2/2)
- GitHub Check: tests (load-only macOS)
- GitHub Check: tests (Linux, 1/2)
- GitHub Check: tests (macOS, 1/2)
- GitHub Check: workflow_syntax
- GitHub Check: tests (macOS, 2/2)
- GitHub Check: tests (online, 1/2)
- GitHub Check: tests (no Sorbet)
- GitHub Check: tests (online, 2/2)
- GitHub Check: Analyze
- GitHub Check: syntax
🧰 Additional context used
📚 Code guidelines: 1
docs/AGENTS.md — auto-discovered
📓 Path-based instructions: 1
Source excerpt: Use the system Homebrew `brew bundle exec ...`
📄 CodeRabbit inference engine (docs/AGENTS.md)
Files:
docs/index.mddocs/Formula-Cookbook.mddocs/Cask-Cookbook.mddocs/Description-Guidelines.md
🪛 LanguageTool
docs/Cask-Cookbook.md
[style] ~583-~583: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...a single-line UTF-8 string containing a short description of the software. Follow the...
(QUICK_BRIEF)
- Move `desc` guidance into a shared `Description-Guidelines` page so formulae and casks follow one set of expectations. - Keep the principle (describe, don't sell) and replace the rigid cask-only dos and don'ts with a short list of what to leave out: marketing language, feature lists, comparisons with other projects and addressing the reader. - Leave the name and platform rules to `brew style`, which already enforces them, so the page only documents what needs judgement. - Point both cookbooks and the `desc` DSL docs at the new page.
4c7c83e to
0e7f70a
Compare
MikeMcQuaid
left a comment
MikeMcQuaid
left a comment
There was a problem hiding this comment.
Nice, love it! Unrelated note: I think it'd be nice if we can start getting descriptions for fonts too?
We used to have these, but they were mass-removed because they weren't useful. Edit: Just seeing now that you commented in favour of reverting the PR back then 😅 I don't remember seeing that at the time. I'm ok to consider it moving forward. |
descguidance into a sharedDescription-Guidelinespage so formulae and casks follow one set of expectations.This may require some tinkering/further input, but I figured that opening a PR is the best way to get the ball rolling on it.
brew benchmarkresults.brewcommands to reproduce the bug?brew lgtm(style, typechecking and tests) locally?Claude with Fable 5.1 at Extra High effort, with local review and testing.