From 7b0cc143cbde69a7b99322a4e4000459acf0eb12 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Sat, 27 Dec 2014 23:32:21 +0000 Subject: [PATCH] Documentation Updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Acceptable-Formulae: * Makes the language around stable versions stricter. * Fixes the Homebrew/Head-only lack-of-hyphen. * Adds Homebrew/Devel-only. Formula-Cookbook: * Adds a link to Interesting-Taps-&-Branches. * Fixes the Python language to match Tim’s latest guidelines. * Adds a note on options that aren’t ` build-with? ` or ` build-without? `. Interesting-Taps-&-Branches: * Slightly modifies the Versions language to better match what the repository actually ships. * Adds Homebrew/Devel-only to the language. Closes Homebrew/homebrew#35298. Signed-off-by: Mike McQuaid --- share/doc/homebrew/Acceptable-Formulae.md | 4 ++-- share/doc/homebrew/Formula-Cookbook.md | 6 ++++-- share/doc/homebrew/Interesting-Taps-&-Branches.md | 9 ++++++--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/share/doc/homebrew/Acceptable-Formulae.md b/share/doc/homebrew/Acceptable-Formulae.md index 92a25ec67a..ee9a4e5e96 100644 --- a/share/doc/homebrew/Acceptable-Formulae.md +++ b/share/doc/homebrew/Acceptable-Formulae.md @@ -62,13 +62,13 @@ from source. Binary-only formulae should go to [Homebrew/homebrew-binary](https://github.com/Homebrew/homebrew-binary). ### Stable versions -Formulae in the core repository should have a stable version tagged by +Formulae in the core repository must have a stable version tagged by the upstream project. Tarballs are preferred to git checkouts, and tarballs should include the version in the filename whenever possible. Software that does not provide a stable, tagged version, or had guidance to always install the most recent version, should be put in -[Homebrew/homebrew-headonly](https://github.com/Homebrew/homebrew-headonly). +[Homebrew/homebrew-head-only](https://github.com/Homebrew/homebrew-headonly) or [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only). ### Bindings First check that there is not already a binding available via diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md index 41bb00de8b..9b9b0bae5e 100644 --- a/share/doc/homebrew/Formula-Cookbook.md +++ b/share/doc/homebrew/Formula-Cookbook.md @@ -64,7 +64,7 @@ Before contributing, make sure your package: * isn't in another [Homebrew tap](https://github.com/Homebrew) * isn't already waiting to be merged (check the [issue tracker](http://github.com/Homebrew/homebrew/issues)) * is still supported by upstream -* has a stable, tagged version (i.e. not just a GitHub repository with no versions) +* has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Branches](Interesting-Taps-&-Branches.md) for where pre-release and head-only versions belong. Make sure you search thoroughly (all aliases!). We don’t want you to waste your time. @@ -242,7 +242,7 @@ class Foo < Formula end def install - resource("pycrypto").stage { Language::Python.setup_install "python", libexec/"vendor" } + resource("pycrypto").stage { system "python", *Language::Python.setup_install_args(libexec/"vendor") } end end ``` @@ -843,6 +843,8 @@ end Option names should be prefixed with one of the words `with`, `without`, `no`, or a verb in the imperative tense describing the action to be taken. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library should be named `--enable-shared` rather than `--shared`. +Note that options that aren’t ` build.with? ` or ` build.without? ` should be actively deprecated where possible. See [wget](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/wget.rb#L27-L31) for an example. + See the [graphviz](https://github.com/Homebrew/homebrew/blob/master/Library/Formula/graphviz.rb) formula for an example. diff --git a/share/doc/homebrew/Interesting-Taps-&-Branches.md b/share/doc/homebrew/Interesting-Taps-&-Branches.md index e70e868329..f70d853cbf 100644 --- a/share/doc/homebrew/Interesting-Taps-&-Branches.md +++ b/share/doc/homebrew/Interesting-Taps-&-Branches.md @@ -11,7 +11,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst - Need GDB or a newer Tk? System duplicates go here. * [homebrew/versions](https://github.com/Homebrew/homebrew-versions) - - Need e.g. older or newer versions of Python? Newer versions of GCC? + - Need e.g. older or newer versions of Postgresql? Older versions of GCC? * [homebrew/games](https://github.com/Homebrew/homebrew-games) - Game or gaming-emulation related formulae. @@ -19,8 +19,11 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst * [homebrew/apache](https://github.com/Homebrew/homebrew-apache) - A tap for Apache modules, extending OS X's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats. -* [homebrew/headonly](https://github.com/Homebrew/homebrew-headonly) - - A tap for brews that don't have stable versions. +* [homebrew/head-only](https://github.com/Homebrew/homebrew-head-only) + - A tap for brews that only have unstable, unreleased versions. + +* [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only) + - A tap for brews that only have pre-release/development versions. * [homebrew/php](https://github.com/Homebrew/homebrew-php) - Repository for php-related formulae.