Author: assaf
Date: Sun Jan 6 02:27:34 2008
New Revision: 609287
URL: http://svn.apache.org/viewvc?rev=609287&view=rev
Log:
Added recipes/troubleshooting pages, rewrote contributing/mailing list pages
Added:
incubator/buildr/trunk/doc/pages/recipes.textile
incubator/buildr/trunk/doc/pages/troubleshooting.textile
Modified:
incubator/buildr/trunk/doc/pages/contributing.textile
incubator/buildr/trunk/doc/pages/extending.textile
incubator/buildr/trunk/doc/pages/mailing_lists.textile
incubator/buildr/trunk/doc/pages/more_stuff.textile
Modified: incubator/buildr/trunk/doc/pages/contributing.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/contributing.textile?rev=609287&r1=609286&r2=609287&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/contributing.textile (original)
+++ incubator/buildr/trunk/doc/pages/contributing.textile Sun Jan 6 02:27:34
2008
@@ -1,33 +1,146 @@
h1. Contributing
-Step 1, join the "mailing list":mailing_lists.html. It's the best place to
-ask questions, report "features", submit patches and let us know how you use
-Buildr in your own projects.
+Buildr is a community effort, and we welcome all contributors. Here's your
+chance to get involved and help your fellow developers.
-Step 2, checkout "Buildr from
-SVN":http://svn.apache.org/repos/asf/incubator/buildr:
+h2. Mailing Lists
+
+We don't talk much, but when we do, we have interesting things to say, so start
+by subscribing to the "mailing lists":mailing_lists.html. It's the best place
+to ask questions, offer help and suggestions, raise new ideas, tell us how
+you're using Buildr in your own projects, and find out what other people are
+doing with Buildr.
+
+We run two mailing lists, the
+"buildr-user":mailto:[EMAIL PROTECTED] mailing list
+("subscribe":mailto:[EMAIL PROTECTED],
+"archive":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/) for
+developers working with Buildr, and the
+"buildr-dev":mailto:[EMAIL PROTECTED] mailing list
+("subscribe":[EMAIL PROTECTED],
+"archive":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/) for
+developement of Buildr itself. We also have a
+"commits":[email protected] mailing list
+("subscribe":[EMAIL PROTECTED]) if you want to
+stalk us.
+
+
+h2. Bugs (aka Issues)
+
+We really do try to keep bugs to a minimum, and anticipate everything you'll
+ever want to do with Buildr. We're also, not perfect. So you may have found a
+bug, or have an enhancement in mind, or better yet, a patch to contribute.
+Here's what you can do.
+
+If it's a bug, enhancement or patch, add it to
+"JIRA":http://issues.apache.org/jira/browse/Buildr. For trivial stuff, that's
+good enough.
+
+If it needs more attention, start a discussion over on the mailing list. We
+will still use JIRA to log the progress, but the mailing list is a better place
+for talking things through.
+
+If you have a patch to submit, do it through
+"JIRA":http://issues.apache.org/jira/browse/Buildr. We want to make sure
+Apache gets the right to use your contribution, and the JIRA upload form
+includes a simple contribution agreement. Lawyer not included.
+
+
+h2. Source Code
+
+Did we mention Buildr is an open source project? In fact, when you install
+Buildr you get all the source code, documentation, test case and everything you
+need to use it, extend it and patch it. Have a look in your Gem directory.
+
+But if you want to work with the latest and greatest, you'll want to check out
+"Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr:
{{{!sh
$ svn co http://svn.apache.org/repos/asf/incubator/buildr/trunk buildr
}}}
-You can also search the "Buildr
+You can also browse the "Buildr
repository":http://svn.apache.org/repos/asf/incubator/buildr.
-Step 3, install Buildr from your working copy:
+You can also install Buildr from your working copy:
{{{!sh
$ cd buildr
$ rake install
}}}
-(@sudo rake install@ if you're running on Linux)
+(Linux and OS/X, use @sudo rake install@)
+
+
+h2. Testing
-Step 4, send a patch to the mailing list. And please help us by providing a
-proper test case. Buildr uses "RSpec":http://rspec.rubyforge.org/ , a
-behavior-driven development test framework. Check out the existing tests
-(specs) in the @spec@ directory, and make sure they all pass by running:
+Obviously we won't turn down patches, but we'll love you even more if you
+include a test case. One that will fail without the patch, and run
+successfully with it. If not for our love, then think of the benefit to you:
+once we add that test case, we won't accidentally break that feature in the
+next release.
+
+We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test
+framework. The main difference between RSpec and xUnit is that RSpec helps you
+formulate test cases in terms of specifications: you describe how the code
+should behave, and run RSpec to make sure it matches that specification.
+"Here's an example":http://rspec.info/examples.html.
+
+You can run an individual specifications using the @spec@ command, for example:
+
+{{{!sh
+$ spec spec/compiler_spec.rb -l 409
+}}}
+
+To make sure your change did not break anything else, you can run all the
+specifications (be patient, we have a lot of these):
{{{!sh
$ rake spec
}}}
+
+We always @rake spec@ before making a release.
+
+You can also check out the "RSpec report":report.html and "test coverage
+report":coverage/index.html for the current version of Buildr. And if you
want to help us on the journey to 100% test coverage, we'll be ever so greatful!
+
+
+h2. Documentation
+
+Yes, we do make typos, spelling errors and sometimes we write things that don't
+make sense, so if you find a documentation bug, or want to help make the
+documentation even better, here's the way to do it.
+
+For simple typos and quick fixes, just send a message to the mailing list or
+log an issue in JIRA.
+
+If you end up rewriting a significant piece of text, or add new documentation
+(your rock!), send a patch. Making documentation patches is fairly easy. All
+the documentation is generated from text files in the @doc/pages@ directory, so
+all you need to do is check it out from SVN, edit, and @svn diff@ to create a
+patch.
+
+We use "Textile":http://www.textism.com/tools/textile/ as the markup language,
+it takes all of a few minutes to learn, it's intuitive to use, and produces
+clean HTML.
+
+You can always check the documentation to see which conventions we use, and
+also a couple of extensions we have for styling source code (with syntax
+highlighting!) and handling footnotes. The table of contents is auto-generated
+form H1/H2 headers.
+
+The tool we use for this is called Docter, which we developed specifically for
+Buildr, and use to create the Web site and printable PDF. If you want to try
+it out you'll need to first @gem install [EMAIL PROTECTED] To generate a copy
of the
+Web site, simple run @rake html@ .
+
+If you're thinking of editing the docs, and using @rake html@ to see what the
+HTML looks like, you may want to try something simpler. Start by running the
+Docter Web server with @rake docter@ and then point your browser at
+"http://localhost:3000":http://localhost:3000. To see your edits, simply
+refresh the page.
+
+Generating the PDF is a bit more tricky, we use the HTML in combination with
+print media CSS stylesheets and run them through the wonderful
+"PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML
+first before you can @rake [EMAIL PROTECTED]
Modified: incubator/buildr/trunk/doc/pages/extending.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/extending.textile?rev=609287&r1=609286&r2=609287&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/extending.textile (original)
+++ incubator/buildr/trunk/doc/pages/extending.textile Sun Jan 6 02:27:34 2008
@@ -16,20 +16,20 @@
Compare this:
{{{!ruby
-file("derby.sql") do
+file('derby.sql') do
requires = [
- "org.apache.openjpa:openjpa-all:jar:0.9.7-incubating",
- "commons-collections:commons-collections:jar:3.1",
+ 'org.apache.openjpa:openjpa-all:jar:0.9.7-incubating',
+ 'commons-collections:commons-collections:jar:3.1',
. . .
- "net.sourceforge.serp:serp:jar:1.11.0" ]
- ant("openjpa") do |ant|
- ant.taskdef :name=>"mapping",
- :classname=>"org.apache.openjpa.jdbc.ant.MappingToolTask",
+ 'net.sourceforge.serp:serp:jar:1.11.0' ]
+ ant('openjpa') do |ant|
+ ant.taskdef :name=>'mapping',
+ :classname=>'org.apache.openjpa.jdbc.ant.MappingToolTask',
:classpath=>REQUIRES.join(File::PATH_SEPARATOR)
- ant.mapping :schemaAction=>"build", :sqlFile=>task.name,
+ ant.mapping :schemaAction=>'build', :sqlFile=>task.name,
:ignoreErrors=>true do
- ant.config :propertiesFile=>_("src/main/sql/derby.xml")
- ant.classpath :path=>projects("store", "utils" ).
+ ant.config :propertiesFile=>_(:source, :main, :sql, 'derby.xml')
+ ant.classpath :path=>projects('store', 'utils' ).
flatten.map(&:to_s).join(File::PATH_SEPARATOR)
end
end
@@ -40,10 +40,10 @@
To this:
{{{!ruby
-file("derby.sql") do
- mapping_tool :action=>"build", :sql=>task.name,
- :properties=>_("src/main/sql/derby.xml"),
- :classpath=>projects("store", "utils" )
+file('derby.sql') do
+ mapping_tool :action=>'build', :sql=>task.name,
+ :properties=>_(:source, :main, :sql, 'derby.xml'),
+ :classpath=>projects('store', 'utils')
end
}}}
Modified: incubator/buildr/trunk/doc/pages/mailing_lists.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/mailing_lists.textile?rev=609287&r1=609286&r2=609287&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/mailing_lists.textile (original)
+++ incubator/buildr/trunk/doc/pages/mailing_lists.textile Sun Jan 6 02:27:34
2008
@@ -1,14 +1,32 @@
h1. Mailing Lists
-The following mailing-lists are open to anybody:
+*buildr-user* For developers working with Buildr:
+
+* Send messages to
+"[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED]
+
+* Subscribe by sending a message to
+"[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED]
+
+* View the "mailing list
+archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/.
+
+*buildr-dev* For development of Buildr itself:
+
+* Send messages to
+"[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED]
+
+* Subscribe by sending a message to
+"[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED]
+
+* View the "mailing list
+archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/.
+
+*buildr-commits* Commit messages from SVN and progress status from JIRA:
+
+* Subscribe by sending a message to
+"[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED]
+
+* View the "mailing list
+archives":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/.
-| Mailing-List | Address | Subscribe |
-| Users | "[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED] | "[EMAIL
PROTECTED]":mailto:[EMAIL PROTECTED] |
-| Development | "[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED] | "[EMAIL
PROTECTED]":mailto:[EMAIL PROTECTED] |
-| Commits |
"[email protected]":mailto:[email protected]
| "[EMAIL PROTECTED]":mailto:[EMAIL PROTECTED] |
-
-The archives are available below:
-
-"http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/
-"http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/
-"http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/
Modified: incubator/buildr/trunk/doc/pages/more_stuff.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/more_stuff.textile?rev=609287&r1=609286&r2=609287&view=diff
==============================================================================
--- incubator/buildr/trunk/doc/pages/more_stuff.textile (original)
+++ incubator/buildr/trunk/doc/pages/more_stuff.textile Sun Jan 6 02:27:34 2008
@@ -45,10 +45,10 @@
{{{!ruby
# Only I should know that
-repositories.upload_to[:username] = "assaf"
-repositories.upload_to[:password] = "supersecret"
+repositories.upload_to[:username] = 'assaf'
+repositories.upload_to[:password] = 'supersecret'
# Search here first, it's faster
-repositories.remote << "http://inside-the-firewall";
+repositories.remote << 'http://inside-the-firewall'
}}}
Environment variables are another way to set personal settings. Here's an
@@ -56,8 +56,8 @@
variables:
{{{!ruby
-repositories.upload_to[:username] = ENV["USERNAME"]
-repositories.upload_to[:password] = ENV["PASSWORD"]
+repositories.upload_to[:username] = ENV['USERNAME']
+repositories.upload_to[:password] = ENV['PASSWORD']
}}}
Build itself uses several environment variables, some more common, some
@@ -66,7 +66,7 @@
*JAVA_HOME* -- Points to your JDK, required for running Buildr.
*JAVA_OPTS/JAVA_OPTIONS* -- Command line options to pass to the JDK (e.g.
-@"-Xms1g"@)[1].
+@'-Xms1g'@)[1].
*HTTP_PROXY* -- URL for HTTP proxy server (see "Specifying
Repositories":artifacts.html#specifying_repositories).
@@ -176,8 +176,8 @@
require it explicitly. The proper way to do it in Ruby:
{{{!ruby
-require "buildr/cobertura"
-require "buildr/jdepend"
+require 'buildr/cobertura'
+require 'buildr/jdepend'
}}}
You may want to add those to the Buildfile. Alternatively, you can use these
@@ -210,10 +210,10 @@
just, so it's just a matter of writing a task:
{{{!ruby
-bins = file("target/bin"=>FileList[_("src/main/dist/bin/*")]) do |task|
+bins = file('target/bin'=>FileList[_('src/main/dist/bin/*')]) do |task|
mkpath task.name
cp task.prerequisites, task.name
- chmod 0755, FileList[task.name + "/*.sh"], :verbose=>false
+ chmod 0755, FileList[task.name + '/*.sh'], :verbose=>false
end
}}}
@@ -225,15 +225,15 @@
{{{!ruby
def distro(project, id)
project.package(:zip, :id=>id).path("#{id}-#{version}").tap do |zip|
- zip.include meta_inf + ["RELEASE_NOTES", "README"].map { |f| path_to(f) }
- zip.path("examples").include project.path_to("src/examples"), :as=>"."
- zip.merge project("ode:tools-bin").package(:zip)
- zip.path("lib").include artifacts(COMMONS.logging, COMMONS.codec,
+ zip.include meta_inf + ['RELEASE_NOTES', 'README'].map { |f| path_to(f) }
+ zip.path('examples').include project.path_to(:source, :examples), :as=>'.'
+ zip.merge project('ode:tools-bin').package(:zip)
+ zip.path('lib').include artifacts(COMMONS.logging, COMMONS.codec,
COMMONS.httpclient, COMMONS.pool, COMMONS.collections, JAXEN, SAXON,
LOG4J, WSDL4J, XALAN, XERCES)
- project("ode").projects("utils", "tools", "bpel-compiler", "bpel-api",
- "bpel-obj", "bpel-schemas").map(&:packages).flatten.each do |pkg|
- zip.include(pkg.to_s, :as=>"#{pkg.id}.#{pkg.type}", :path=>"lib")
+ project('ode').projects('utils', 'tools', 'bpel-compiler', 'bpel-api',
+ 'bpel-obj', 'bpel-schemas').map(&:packages).flatten.each do |pkg|
+ zip.include(pkg.to_s, :as=>"#{pkg.id}.#{pkg.type}", :path=>'lib')
end
yield zip
end
@@ -243,9 +243,9 @@
And then use it in the project definition:
{{{!ruby
-define "distro-axis2" do
+define 'distro-axis2' do
parent.distro(self, "#{parent.id}-war") { |zip|
- zip.include project("ode:axis2-war").package(:war), :as=>"ode.war" }
+ zip.include project('ode:axis2-war').package(:war), :as=>'ode.war' }
end
}}}
Added: incubator/buildr/trunk/doc/pages/recipes.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/recipes.textile?rev=609287&view=auto
==============================================================================
--- incubator/buildr/trunk/doc/pages/recipes.textile (added)
+++ incubator/buildr/trunk/doc/pages/recipes.textile Sun Jan 6 02:27:34 2008
@@ -0,0 +1,3 @@
+h1. Recipes
+
+Commond recipes for Buildr, collected from the mailing list.
Added: incubator/buildr/trunk/doc/pages/troubleshooting.textile
URL:
http://svn.apache.org/viewvc/incubator/buildr/trunk/doc/pages/troubleshooting.textile?rev=609287&view=auto
==============================================================================
--- incubator/buildr/trunk/doc/pages/troubleshooting.textile (added)
+++ incubator/buildr/trunk/doc/pages/troubleshooting.textile Sun Jan 6
02:27:34 2008
@@ -0,0 +1,25 @@
+h1. Troubleshooting
+
+Common troubleshooting tips collected from the mailing list.
+
+h2. Buildfiles
+
+h3. Bugs resulting from a dangling comma or period
+
+Ruby statements don't need a delimiter and can span multiple lines, which can
+lead to bugs resulting from dangling commas and periods left at the end of the
+line. For example:
+
+{{{!ruby
+compile.with 'org.apache.axis2:axis2:jar:1.2',
+test.with 'log4j:log4j:jar:1.1'
+}}}
+
+This is actually a single method call with two arguments, separated by a comma.
+The second argument is the result of calling @test.with@, and makes the test
+task a pre-requisite of the compile task, leading to a circular dependency.
+
+As you can imagine this happens usually after editing, specifically for commas
+and periods which are small enough that you won't notice them from a cursory
+glance at the code, so if all else fails, search for lines that end with one of
+these characters.
