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

Maintainer-Guidelines: general updates, cleanup.

Browse Source
This commit is contained in:
Mike McQuaid 2015-05-27 11:10:06 +01:00
parent aac0e4a878
commit ebf82e03df
1 changed files with 44 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -9,31 +9,28 @@ 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 is correct. This cannot be changed later, so it must
be right the first time! be right the first time!
- Add aliases - Add aliases
- Ensure it is not a 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/latest). [pip](https://pip.pypa.io/en/latest).
- Ensure the name is not in Ruby’s stdlib (Try - Ensure that any dependencies are accurate and minimal. We don't need to
`Formula.factory('readline')` in the `brew irb` shell) support every possible optional feature for the software.
- Ensure that any dependencies are accurate - 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.
- Thank people for contributing.
You should test the build process. But you’re really pressed for time, Checking dependencies is important, because they will probably stick around
just get it in there and let someone else test the build.
Checking deps is important, because they will probably stick around
forever. Nobody really checks if they are necessary or not. Use the 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. Avoid X11 functionality unless it Depend on as little stuff as possible. Disable X11 functionality by default.
is required. For example, we build Wireshark, but not the monolithic For example, we build Wireshark, but not the monolithic GUI. If users want
GUI. If users want that, they should just grab the DMG that Wireshark that, they should just grab the DMG that Wireshark themselves provide.
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
be accepted frugally. That is, rarely. be accepted frugally. That is, rarely.
### Naming ### Naming
@ -43,25 +40,25 @@ Choose a name that’s the colloquial (most common) name for the project.
For example, we chose `objective-caml`, but we should have chosen `ocaml`. For example, we 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 with the `aka` class function. Ensure the Add other names as aliases as symlinks in `Library/Aliases`. Ensure the name
name referenced on the homepage is one of these, as it may be different referenced on the homepage is one of these, as it may be different and have
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`). This is We don’t allow versions in formula names (e.g. `bash4.rb`); these should be in
sometimes frustrating, but we’re trying to solve this properly. the `homebrew/versions` tap. This is sometimes frustrating, but we’re trying to
(`python3.rb` is a rare exception, because it’s basically a “new” solve this properly. (`python3.rb` is a rare exception, because it’s basically
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 `rebase` or Merging is mainly useful when new work is being done. Please use `brew pull`
cherry-pick contributions rather than fill our tree up with noisy merge (or `rebase`/`cherry-pick` contributions) rather than fill Homebrew's Git
commits. history up with noisy merge commits.
Don’t `rebase` until you finally `push`. Once pushed, you can’t `rebase` Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t
: **you’re a maintainer now!** `rebase` : **you’re a maintainer now!**
Cherry-picking changes the date of the commit, which kind of sucks. Cherry-picking changes the date of the commit, which kind of sucks.
@ -73,13 +70,13 @@ not confusing.
### Testing ### Testing
We need to at least check it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this. We need to at least check it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this.
Verify the formula works if possible. If you can’t tell—for example, if Verify the formula works if possible. If you can’t tell (e.g. if it’s a
it’s a library—trust the original contributor, it worked for them, so library) trust the original contributor, it worked for them, so chances are it
chances are it is fine. If you aren’t an expert in the tool in question, is fine. If you aren’t an expert in the tool in question, you can’t really
you can’t really gauge if the formula installed the program correctly. gauge if the formula installed the program correctly. At some point an expert
At some point an expert will come along, cry blue murder that it doesn’t will come along, cry blue murder that it doesn’t work, and fix it. This is how
work, and fix it. This is how open source works. open source works. Ideally, request a `test do` block to test that
Ideally, request a `test do` block to test that functionality is consistently available. functionality is consistently available.
If the formula uses a repository, then the `url` parameter should have a If the formula uses a repository, then the `url` parameter should have a
tag or revision. `url` s have versions and are stable (not yet tag or revision. `url` s have versions and are stable (not yet
@ -106,19 +103,18 @@ try to make this work.
Often parallel builds work with 2-core systems, but fail on 4-core Often parallel builds work with 2-core systems, but fail on 4-core
systems. systems.
### Dupes ### Duplicates
The main branch avoids dupes as much as possible. The exception is The main repository avoids duplicates as much as possible. The exception is
libraries that OS X provides but have bugs, and the bugs are fixed in a libraries that OS X provides but have bugs, and the bugs are fixed in a
newer version. Or libraries that OS X provides, but they are too old for newer version. Or libraries that OS X provides, but they are too old for
some other formula. some other formula. The rest should be in the `homebrew/dupes` tap.
Still determine if it possible to avoid the dupe. Be thorough. Duped Still determine if it possible to avoid the duplicate. Be thorough. Duped
libs and tools cause bugs that are tricky to solve. Once the formula is libraries and tools cause bugs that are tricky to solve. Once the formula is
pulled, we can’t go back on that willy-nilly. pulled, we can’t go back on that willy-nilly.
If it dupes anything ask another contributor first. Some dupes are okay, If it duplicates anything ask another maintainer first. Some dupes are okay,
some can cause subtle issues we don’t want to have to deal with in the some can cause subtle issues we don’t want to have to deal with in the future.
future.
Dupes we have allowed: Dupes we have allowed:
- `libxml` \<— OS X version is old and buggy - `libxml` \<— OS X version is old and buggy
@ -135,15 +131,7 @@ Amend a cherry-pick to remove commits that are only changes in
whitespace. They are not acceptable because our history is important and whitespace. They are not acceptable because our history is important and
`git blame` should be useful. `git blame` should be useful.
Whitespace corrections (to ruby standard etc.) are allowed (in fact this Whitespace corrections (to Ruby standard etc.) are allowed (in fact this
is a good opportunity to do it) provided the line itself has some kind is a good opportunity to do it) provided the line itself has some kind
of modification that is not whitespace in it. But be careful about of modification that is not whitespace in it. But be careful about
making changes to inline patches—make sure they still apply. making changes to inline patches—make sure they still apply.
This rule is why the `case` statement in the `brew` tool is a mess.
We’ll fix such things up for v2.
### Moving formulae from one tap to another
And preserving the history. I made a
[gist](https://gist.github.com/samueljohn/5280700) about this, based on
Jack’s initial version.