admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Maintainer-Guidelines: tweak guidelines

Browse Source
This commit is contained in:
Dominyk Tiller 2016-09-14 19:53:35 +01:00
parent 49e9be1970
commit de283d81c5
No known key found for this signature in database
GPG Key ID: FE19AEFCF658C6F6
1 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
share/doc/homebrew/Maintainer-Guidelines.md
View File

@ -9,17 +9,17 @@ Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)?
## Quick Checklist ## Quick Checklist
This is all that really matters: This is all that really matters:
- Ensure the name is correct. This cannot be changed later, so it must - Ensure the name seems reasonable.
be right the first time! - Add aliases.
- Add aliases - Ensure it is not an unreasonable dupe of anything that comes with OS X.
- Ensure it is not a dupe of anything that comes with OS X
- Ensure it is not a library that can be installed with - Ensure it is not a library that can be installed with
[gem](https://en.wikipedia.org/wiki/RubyGems), [gem](https://en.wikipedia.org/wiki/RubyGems),
[cpan](https://en.wikipedia.org/wiki/Cpan) or [cpan](https://en.wikipedia.org/wiki/Cpan) or
[pip](https://pip.pypa.io/en/stable/). [pip](https://pip.pypa.io/en/stable/).
- Ensure that any dependencies are accurate and minimal. We don't need to - Ensure that any dependencies are accurate and minimal. We don't need to
support every possible optional feature for the software. support every possible optional feature for the software.
- Use `brew pull` when possible to add messages to auto-close pull requests (which may take ~5m, be patient) and pull bottles built by BrewTestBot. - Use the GitHub squash & merge workflow where bottles aren't required.
- Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by BrewTestBot.
- Thank people for contributing. - Thank people for contributing.
Checking dependencies is important, because they will probably stick around Checking dependencies is important, because they will probably stick around
@ -27,35 +27,35 @@ forever. Nobody really checks if they are necessary or not. Use the
`:optional` and `:recommended` modifiers as appropriate. `:optional` and `:recommended` modifiers as appropriate.
Depend on as little stuff as possible. Disable X11 functionality by default. Depend on as little stuff as possible. Disable X11 functionality by default.
For example, we build Wireshark, but not the monolithic GUI. If users want For example, we build Wireshark, but not the heavy GTK/Qt GUI by default.
that, they should just grab the DMG that Wireshark themselves provide.
Homebrew is about Unix software. Stuff that builds to an `.app` should Homebrew is about Unix software. Stuff that builds to an `.app` should
probably be in Homebrew Cask instead. probably be in Homebrew Cask instead.
### Naming ### Naming
The name is the strictest item, because we can’t change it afterwards. The name is the strictest item, because avoiding a later name change is
desirable.
Choose a name that’s the most common name for the project. Choose a name that’s the most common name for the project.
For example, we chose `objective-caml`, but we should have chosen `ocaml`. For example, we initially chose `objective-caml` but we should have chosen `ocaml`.
Choose what people say to each other when talking about the project. Choose what people say to each other when talking about the project.
Add other names as aliases as symlinks in `Library/Aliases`. Ensure the name Add other names as aliases as symlinks in `Aliases` in the tap root. Ensure the
referenced on the homepage is one of these, as it may be different and have name referenced on the homepage is one of these, as it may be different and have
underscores and hyphens and so on. underscores and hyphens and so on.
We don’t allow versions in formula names (e.g. `bash4.rb`); these should be in We mostly don’t allow versions in formula names (e.g. `bash4.rb`); these should
the `homebrew/versions` tap. This is sometimes frustrating, but we’re trying to be in the `homebrew/versions` tap. (`python3.rb` is a rare exception, because it’s
solve this properly. (`python3.rb` is a rare exception, because it’s basically basically a “new” language and installs no conflicting executables.)
a “new” language and installs no conflicting executables.)
For now, if someone submits a formula like this, we’ll leave them in For now, if someone submits a formula like this, we’ll leave them in
their own tree. their own tree.
### Merging, rebasing, cherry-picking ### Merging, rebasing, cherry-picking
Merging is mainly useful when new work is being done. Please use `brew pull` Merging should be done in the brew repo to preserve history & GPG commit signing,
(or `rebase`/`cherry-pick` contributions) rather than fill Homebrew's Git and squash/merge via GitHub should be used for formulae where those formulae
history up with noisy merge commits. don't need bottles or the change does not require new bottles to be pulled.
Otherwise, you should use `brew pull` (or `rebase`/`cherry-pick` contributions).
Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t
`rebase` : **you’re a maintainer now!** `rebase` : **you’re a maintainer now!**