-
Notifications
You must be signed in to change notification settings - Fork 5
Collaborator Guidelines
This guide is for collaborators, these special people have write access to mxcl’s fork and help merge your contributions. You may find what is written here interesting but it is not by any means a beginner’s guide. Maybe you were looking for the Formula Cookbook?
This is all that really matters:
- Ensure the name is correct, this cannot really be changed later, so it must be right the first time!
- Add aliases
- Ensure it is not a dupe of anything that comes with OS X,
or anything that can be installed with gem, cpan or pip. - Ensure any specified dependencies are accurate.
You don’t even need to test it builds. You should. But if time is problematic its better just to get it in there and let someone else test it builds.
Checking the deps is important because they will likely stick around forever. Nobody really checks if they are necessary or not. Use the :optional and :recommended modifiers as appropriate.
Depend on as little stuff as possible. Avoid X11 functionality unless it is required. Eg. we build Wireshark, but not the monolithic GUI. If users want that, they should just grab the DMG that Wireshark provide themselves.
Homebrew is about UNIX software. Stuff that builds to a .app should be accepted frugally. That is, rarely.
The name is really the only important bit, because we can’t change it after.
Prefer the name that is most common, colloquial for the project. So we chose objective-caml, but we should have chosen ocaml. Choose what people say to each other when talking about the project.
Add other names as aliases with the aka class function. Ensure the name referenced on the homepage is one of these, as it may be different and have underscores and hyphens and such things.
We don’t allow version in the formula name, eg. python3.rb. This currently is frustrating to some extent, but we are trying to solve this problem properly. If someone submits a formula like this, then for now, we are leaving them in their tree.
Merging is mainly useful when new work is being done. Feel free to rebase or cherry-pick contributions rather than fill our tree up with noisy merge commits. Don’t rebase until you finally push. Once pushed, you can’t rebase, you’re a collaborator now.
Cherry-picking changes the date of the commit, which kind of sucks.
Don’t merge unclean branches. So if the guy clearly has some git-foo to learn and his branch is filled with nonsensical merges, then rebase and squash the commits. Our main branch history should be useful to other people and not confusing.
We need to at least check it builds.
In order to test the formula specifies its dependencies properly try to have as little installed into /usr/local as possible. Ideally we’d create some kind of `brew sandbox`…
Check the formula builds. If possible on both 10.5 and 10.6. If it doesn’t fix it if you like, or comment on the issue.
Verify the formula works if possible. If it’s some library and you can’t tell, trust the original contributor, it worked for them, so chances are it is fine. If you aren’t an expert in the tool in question, you can’t really gauge if the formula installs the product correctly. At some point an expert will come along, cry blue murder that it doesn’t work, and fix it. This is how open source works.
If the formula uses a git repo or svn etc. then the url parameter should have a tag or revision, url’s have versions and are stable (note this isn’t yet implemented)
If not completely annoying, test in both /usr/local and somewhere else. Preferably on different machines to ensure the /usr/local install doesn’t effect the other one.
The reason for this is some build systems suck and don’t work if deps aren’t installed in /usr/local, even though Homebrew goes to some lengths to try to make this work.
- Ensure you have set your username and email address properly
- Sign off cherry-picks if you amended them (GitX can do this, otherwise there is a command line flag for it)
- If the commit fixes a bug, use “Fixes #104” syntax to close the bug report and link to the commit
Often parallel builds work with two core systems, but fail on 4 core systems.
The main branch avoids dupes as much as possible. The exception is 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 some other formula.
Still determine if it possible to avoid the dupe. Be thorough. Duped libs and tools cause bugs that are tricky to solve. Once the formula is pulled, we can’t go back on that willy-nilly.
If it dupes anything ask mxcl first. Some dupes are ok, some can cause subtle issues we don’t want to have to deal with in the future.
Dupes we have allowed:
libxml <— OS X version is old and buggy
libpng <— same as above
It may be enough to refer to an issue ticket, but make sure changes that if you came to them unaware of the surrounding issues would make sense to you. Many times on other projects I’ve seen code removed because the new guy didn’t know why it was there. Regressions suck.
Amend a cherry-pick to remove commits that are only changes in whitespace. They are not acceptable because our history is important and git blame should be useful.
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 of modification that is not whitespace in it. But be careful about 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.
The network is huge, you can get an idea for that by doing:
gem install drnic-github cd `brew --prefix` gh network fetch
The github gem helps. I wouldn’t fetch the whole network into your actual homebrew that you use though.
Other useful github gem commands include fetch (makes a branch too) and fetch_all (just allows you to view the remote branches with gitx/gitk —all).
Building large projects is error prone (and blimey they can take forever to build!) We just end up with a greater support burden. Prefer binary distributions but with common sense:
1. MySQL for instance is faster due to the compile flags we use than the binary (tests done in issue#144)
2. If the extracted product is non flexible and doesn’t work well with Homebrew’s layout/mindset
3. If the binary product is missing a much needed feature.
With this in mind we should switch back to the binary Tex-live probably. And also see if we can get a precompiled binary for Qt and Boost.