Added: dev/buildr/1.5.4/site/contributing.html ============================================================================== --- dev/buildr/1.5.4/site/contributing.html (added) +++ dev/buildr/1.5.4/site/contributing.html Sun Sep 24 21:59:16 2017 @@ -0,0 +1,218 @@ + + + + buildr — Contributing + + + + + + +
+ +
+
    +
  1. Start Here +
      +
    1. Welcome
    2. +
    3. Quick Start
    4. +
    5. Installing & Running
    6. +
    7. Community Wiki
    8. +
    +
  2. +
  3. Using Buildr +
      +
    1. This Guide (PDF)
    2. +
    3. Projects
    4. +
    5. Building
    6. +
    7. Artifacts
    8. +
    9. Packaging
    10. +
    11. Testing
    12. +
    13. Releasing
    14. +
    15. Settings/Profiles
    16. +
    17. Languages
    18. +
    19. More Stuff
    20. +
    21. Extending Buildr
    22. +
    23. How-Tos
    24. +
    +
  4. +
  5. Reference +
      +
    1. API
    2. +
    3. Rake
    4. +
    5. Antwrap
    6. +
    7. Troubleshooting
    8. +
    +
  6. +
  7. Get Involved +
      +
    1. Download
    2. +
    3. Mailing Lists
    4. +
    5. Twitter
    6. +
    7. Issues/Bugs
    8. +
    9. CI Jobs
    10. +
    11. Contributing
    12. +
    +
  8. +
  9. +
    + + + Google Custom Search +
    +
  10. +
+
+
+

Contributing

+
  1. Getting involved
  2. Mailing Lists
  3. Internet Relay Chat
  4. Bugs (aka Issues)
  5. Community Wiki
  6. Contributing Code
  7. Living on the edge
  8. Tested and Documented
  9. Documentation
  10. Continuous Integration
  11. Contributors
+

Buildr is a community effort, and we welcome all contributors. Here’s your chance to get involved and help your fellow developers.

+

Getting involved

+

All our discussions are done in the open, over email, and that would be the first place to look for answers, raise ideas, etc. For bug reports, issues and patches, see below.

+

Mailing Lists

+

We run two mailing lists, the users mailing list for developers working with Buildr, that would be you if you’re using Buildr or interested in using it. There’s the dev mailing list for talking about development of Buildr itself. There’s also commits mailing list for following Git commits and JIRA issues.

+

Check the mailing lists page for more information on subscribing, searching and posting to the mailing list.

+

Internet Relay Chat

+

We are live on IRC under the buildr channel on irc.freenode.net, with a broad coverage of the US timezone. We tend to idle there, so feel free to ping the channel owner (toulmean) to make noise.

+

Our “conversations”: are logged by the echelog and irclogger bots. If you’re really curious, we also have activity statistics

+

Sincere thanks to Matzon and Christopher Schneider for setting these up!

+

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. 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.

+

When reporting a bug, please tell us which version of Ruby, Buildr and Java you are using, and also which operating system you are on:

+
$ ruby --version
+$ buildr --version
+$ java --version

Community Wiki

+

Our community Wiki.

+

Contributing Code

+

Yes, please.

+

If you have a patch to submit, do it through JIRA. 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.

+

The Perfect Patch

+

If you want to get your patch accepted quickly:

+
    +
  1. Provide a good summary of the bug/fix. We use that to decide which issue we can do quickly, and also copy and paste it into the changelog.
  2. +
  3. Provide short explanation of what failed, under what conditions, why, and what else could be affected by the change (when relevant). The helps us understand the problem and move on to the next step.
  4. +
  5. Provide a patch with relevant specs, or a fix to incomplete/broken specs. First thing we have to do is replicate the problem, before applying the change, and then make sure the change fixes that problem. And we need to have those specs in there, they make sure we don’t accidentally break it again in the future.
  6. +
  7. Provide a patch with the fix/change itself. Keep it separate from the specs, so it’s easy to apply them individually.
  8. +
+

If you don’t know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that. A spec is preferred to a fix.

+

Living on the edge

+

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.

+

GIT

+

If you want to work with the latest and greatest, you’ll want to check out Buildr from source control. You can use the official Apache Buildr Github clone. This clone is maintained by Github aand kept in sync with the ASF Git repository

+
$ git clone git@github.com:apache/buildr.git

Working with Source Code

+

To install Buildr from the source directory:

+
$ cd buildr
+$ rake setup install

When using Buildr for JRuby:

+
$ cd buildr
+$ jruby -S rake setup install

The setup task takes care of installing all the necessary dependencies used for building, testing and running Buildr. Once in a while we upgrade or add new dependencies, if you’re experiencing a missing dependency, simply run rake setup again.

+

The install task creates a Gem in your working directory (pkg/) and install it in your local repository. Since Ruby Gems uses version numbers to detect new releases, if you installed Buildr this way and want to upgrade to the latest official release, you need to use gem install buildr rather than gem upgrade.

+

Both setup and install tasks use the sudo command on platforms that require it (i.e. not Windows), so there’s no need to run sudo rake when working with the Buildr source code.

+

Tested and Documented

+

Two things we definitely encourage!

+

Testing/Specs

+

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, 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.

+

You can run an individual specifications using the spec command, for example:

+
$ spec spec/compiler_spec.rb
+$ spec spec/compiler_spec.rb -l 409

The first command will run all the specifications in compiler_spec, the second command will run only the specification identified by line 409 of that file. You can use line numbers to point at a particular specification (lines starting with it), or set of specifications (lines starting with describe). You can also use the -e command line option to name a particular specification.

+

To make sure your change did not break anything else, you can run all the specifications (be patient, we have a lot of these):

+
$ rake spec

If you get any failures, you can use rake failed to run only the failed specs, and repeat until there are no more failed specs to run. The list of failed specs is stored in the file failed.

+

We always rake spec before making a release.

+

For full test coverage:

+
$ rake coverage

Specification and coverage reports are HTML files you can view with a Web browser, look for them in the reports directory. You can also check out the RSpec report and test coverage we publish with each release.

+

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 (you 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 Git, edit, and git diff to create a patch.

+

We use 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 learn it all in a few minutes from the Textile Reference Manual. Also check out the Textile Quick Reference.

+

Syntax highlighting handled by Pygments. Use the special highlight tag to separate code sample from the rest of the text and to tell Pygments which language to use. For example:

+
+{% highlight ruby %}
+define 'project' do
+  # Just a sample
+end
+{% endhighlight %}
+

Have a look at existing documentation to see writing conventions, specifically:

+ +

To go from Textile to HTML we use Jekyll. You can use the jekyll rake task to transform the files under doc and create a copy of the Web site in the directory _site. For example:

+
$ rake jekyll
+$ open _site/index.html

There is no live editing, but you can run rake jekyll auto=true, and when you update and save a Textile page it will regenerate the corresponding HTML page.

+

To go from HTML to PDF we use PrinceXML. The target file buildr.pdf is generated by first running Jekyll and then merging the generated HTML pages into a single PDF document. For example:

+
$ rake buildr.pdf
+$ open buildr.pdf

Continuous Integration

+

Buildr uses the Jenkins continuous integration tool to perform builds, run tests and report back on problems when changes are made to the source code repository.

+

The care and feeding of the CI Jobs is the responsibility of the committers. To get access to configure the CI Jobs a committer needs to follow the directions on the jenkins documentation site.

+

You may also need to coordinate with the Apache infrastructure team to get accounts on the actual slave hosts that run the CI jobs. This access may be required to install tools and gems required to run the CI jobs. The main slave host to get access to is vesta.apache.org at the time of writing. You can also log on to the slave host, impersonate hudson and manually run tasks when you are attempting to track down build problems. Of course to impersonate hudson you will need to learn how to use OPIE.

+

Linux Setup

+

The tests on the Linux hosts rely on RVM to setup the ruby environment. At the time of writing the Linux/x86 nodes that Apache uses for CI are based of the old “Ubuntu 10.04.4 LTS (Lucid Lynx)” operating system. As it is a relatively old operating system, it requires a little bit of manual intervention to install RVM on the node. We have installed the required tools on vesta.apache.org manually. The script looks something like;

+
ssh my_username@vesta.apache.org
+sudo su - hudson
+
+curl -L https://get.rvm.io | bash -s stable
+rvm reload
+rvm pkg install readline
+rvm pkg install iconv
+rvm pkg install curl
+rvm pkg install openssl
+rvm pkg install zlib
+rvm pkg install autoconf
+rvm pkg install ncurses
+rvm pkg install pkgconfig
+rvm pkg install gettext
+rvm pkg install glib
+rvm pkg install mono
+rvm pkg install llvm
+rvm pkg install libxml2
+rvm pkg install libxslt
+rvm pkg install libyaml
+rvm install ruby-1.8.7-p358
+rvm install ruby-1.9.2-p320
+rvm install jruby-1.6.7
+rvm install ruby-1.9.3-p194

It should also be noted that jruby-1.6.7 release has a native library that is compiled using a more modern version of libc than is available on this variant of the operating system. We could download the source release and recompile the library but instead we have just avoided the need for any use of the ruby native interface library in our CI infrastructure.

+

Windows Setup

+

The ci infrastructure on the windows host (hudson-win.apache.org) is a little fragile. First you need to RDP in and download the support libraries. We have manually installed the tools in the following locations. Note: it is important to make the locations read-write access to the hudson user.

+
F:\hudson\tools\Ruby193-p194
+F:\hudson\tools\Ruby192-p290
+F:\hudson\tools\Ruby187-p370
+F:\hudson\tools\jruby-1.6.7
+F:\hudson\tools\scala-2.9.0.1

WARNING: Several attempts were made to use GEM_HOME to install the dependent gems for each test in a separate location but we were unable to figure out the mechanisms via which sub-shells would inherit the paths and the ability to run tools such as rspec.

+

Contributors

+

Here is the list of people who are actively working and committing on Buildr:

+

Assaf Arkin (assaf at apache.org)

+

Started working on Buildr because Maven was too much pain and Rake wasn’t enough. Assaf has been hanging around Apache since 1999, as founding contributor to XML Apache, Ode and Buildr. Assaf is also co-author of Ruby In Practice.

+

Alex Boisvert

+

Came to Buildr as a refuge from the Maven Uncertainty Principle. Alex has been working mostly on the Scala integration and believes Ruby scripting is a great complement to statically typed languages.

+

Matthieu Riou

+

Victor Hugo Borja (vborja at apache.org)

+

Currently a Java Developer at http://jwmsolutions.com, Victor has been enjoying and using Apache’s software since 1999 when he started with Java, now he prefers programming Ruby and is happy to help on Apache’s first ruby project.

+

Lacton (lacton at apache.org)

+

A test-infected developer since 2001, Lacton yearns for a development infrastructure that would shorten feedback loops so much that testing, building, refactoring and committing would feel as easy and natural as breathing air.

+

Daniel Spiewak (djspiewak at apache.org)

+

Daniel originally came to Buildr in search of a Scala build tool which was better than Ant. He got more than he bargained for. Now, he works to advance Buildr as the absolute best tool for supporting Scala development.

+

Antoine Toulme (toulmean at apache.org)

+

Antoine used Buildr first as an excuse to evade in Ruby land, creating plugins for Debian packaging, GWT compilation, or the NSIS installer. His main area of interest is the resolving of dependencies in the OSGi world. He works on making Buildr a standalone rock solid tool.

+

Peter Donald

+

Peter already used rake to automate jobs in his ruby and java projects. When it came time to upgrade that home grown ant/java/rake build system Buildr seemed the perfect match.

+
+ +
+ + Added: dev/buildr/1.5.4/site/css/default.css ============================================================================== --- dev/buildr/1.5.4/site/css/default.css (added) +++ dev/buildr/1.5.4/site/css/default.css Sun Sep 24 21:59:16 2017 @@ -0,0 +1,236 @@ +/* Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with this + * work for additional information regarding copyright ownership. The ASF + * licenses this file to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + */ + + +body { + background-color: #fff; + color: #000; + font-family: "Helvetica Neue", "DejaVu Sans", "Verdana", sans-serif; + text-align: center; + line-height: 150%; +} + +a:link, a:visited{ + color: #0044b3; + text-decoration: none; +} + +a:hover{ + text-decoration: underline; +} + +img { + border: none; +} + +pre, code { + font-family: "Monaco", "DejaVu Sans Mono", "Courier New", "Courier"; + font-size: 11pt; +} +pre { + margin: 0.3em 0 0.3em 0.9em; + padding: 0; + line-height: 1.8em; + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap !important; /* Mozilla, since 1999 */ +} +pre br { display: none; } + +h1, h2, h3 { + font-family: "Gill Sans"; + padding: 0; + margin: 1.6em 0 0.6em 0; + line-height: 1.25em; + letter-spacing: 0.03em; +} + +h1 { + font-size: 2em; + margin-top: 0; + padding-bottom: 0.3em; + border-bottom: 1px solid #808080; +} + +h2 { + font-size: 1.3em; + padding-bottom: 0.3em; + border-bottom: 1px solid #a0a0a0; +} + +h3 { + font-size: 1.1em; +} + +blockquote { + padding-left: 2em; + padding-right: 2em; + margin-left: 0.3em; + margin-right: 0; + font-style: italic; +} + +ul { + list-style-type: disc; +} + +ul ul { + list-style-type: disc; + padding-left: 1em; +} + +table { + border-spacing: 0; + width: 100%; + margin: 0.3em 0 0.3em 0; +} + +th, td { + padding: 0.3em 0.5em 0.3em 0.5em; + border-bottom: 1px solid #D8D8D8; + vertical-align: top; + background-color: #FFFFFF; +} + +th, thead td { + border-bottom: none; + background-color: #669966; + color: #ffffff; + text-align: left; +} + + +#wrap{ + margin: 1em auto 2em auto; + text-align: left; + width: 65em; +} + + +#header { + margin: 0 0 3em 18em; + position: relative; +} + +#header .tagline { + float: right; + font-size: 1.2em; + font-weight: bold; + position: absolute; + top: 0.6em; + right: 0; +} + + +#pages { /* Parent Wrapper for inside boxes */ +/* display: inline; */ /* IE Hack */ + width: 12em; + float: left; + margin-right: 2em; + font-family: "Gill Sans",sans-serif; + font-size: 11pt; + text-align: right; + border-right: 1px solid #ccc; + padding-right: 2em; +} +#pages ol { + list-style: none; + padding: 0; + margin: 0; +} +#pages ol li { + padding: 0.3em 0 0.6em 0em; + color: #669966; + font-weight: bold; +} +#pages ol li ol { + margin-top: 0.3em; + padding: 0.3em 0 0.9em 0.9em; +} +#pages ol li ol li { + padding: 0.3em 0 0.3em 0em; +} +#pages ol li a { + font-weight: normal; +} +#pages form { + margin-top: 2em; + padding: 0.3em 0 0.5em 0.5em; +} +#pages ol li p { + font-weight: normal; + color: #000; + vertical-align: middle; +} + + +#content { /* Parent Wrapper for inside boxes */ +/* display: inline; *//* IE Hack */ + float: left; + width: 44em; + margin-left: 0.3em; + margin-bottom: 5em; + word-wrap: break-word; /* prevents container divs from wrapping */ +} + +ol.toc { + list-style: none; + padding: 0; + margin: 0 0 2em 0; +} +ol.toc li { + padding: 0.3em 0 0.3em 0; + margin: 0; +} +ol.toc li ol.toc { + margin: 0; + padding-left: 0.9em; +} + + +#content p.tip, #content p.note { + margin: 0.9em 0 0 0; + padding: 0 0 2em 4em; +} +#content p.tip { background: url("../images/tip.png") 0 0 no-repeat; } +#content p.note { background: url("../images/note.png") 0 0 no-repeat; } + +#content .footnote { + margin-top: 2.5em; +} +#content .footnote { + padding-top: 1.5em; + border-top: 1px solid #ccc; +} +#content .footnote + .footnote { + margin-top: 0.5em; + padding-top: 0; + border: none; +} +#content .footnote sup { font-weight: bold; } + +#content .footnote-links dt { font-weight: bold; } +#content .footnote-links dt:after { content: ": " } +#content .footnote-links dd { } + + +#footer { + color: #888; + border-top: 1px solid #ccc; + font-size: 0.9em; + padding: 0.3em; + margin: 2em 0 3em 0em; + clear: both; +} Added: dev/buildr/1.5.4/site/css/print.css ============================================================================== --- dev/buildr/1.5.4/site/css/print.css (added) +++ dev/buildr/1.5.4/site/css/print.css Sun Sep 24 21:59:16 2017 @@ -0,0 +1,101 @@ +/* Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with this + * work for additional information regarding copyright ownership. The ASF + * licenses this file to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + */ + + +@media print { + @page { size: letter; } + @page:first { + @top-left { content: normal } + @top-right { content: normal } + } + @page:right { + margin: 1.25in 1in 1.5in 1.5in; + font: normal 10pt "Gill Sans" !important; + @top-left { content: string(pagetitle); } + @top-right { content: counter(page); } + } + @page:left { + margin: 1.25in 1.5in 1.5in 1in; + font: normal 10pt "Gill Sans" !important; + @top-left { content: counter(page); } + @top-right { content: string(pagetitle); } + } + + title { string-set: doctitle content(); } + + body { + font-family: "Palatino"; + margin: 0; + color: black; + background: white; + font-size: 11pt; + } + + h1 { + string-set: pagetitle content(); + page-break-before: always; + } + h1:first-child { page-break-before: avoid; } + h1, h2, h3 { + font-family: "Gill Sans"; + } + pre, p, blockquote { page-break-inside: avoid; } + pre, code { + font-family: "Monaco", "DejaVu Sans Mono", "Courier New", "Courier"; + font-size: 9pt; + } + pre br { + display: none; + } + a:link, a:visited { + background: transparent; + text-decoration: none; + } + + + #header, #pages, #footer { display: none } + #wrap, #content { + float: none !important; + color: black; + background: transparent; + width: auto !important; + margin: 0; + padding: 0; + border: 0; + } + + ol.toc a:link, ol.toc a:visited { text-decoration: none; } + ol.toc a:after { content: leader('.') target-counter(attr(href), page); } + + .title { + page-break-before: always; + border: none; + } + .title img { + display: block; + width: 80%; + margin: 2em auto 4em auto; + } + p.preface { + page-break-before: always; + padding-top: 1.5in; + } + div.preface.quotes { + page-break-before: always; + padding-top: 1in; + } + +} Added: dev/buildr/1.5.4/site/css/syntax.css ============================================================================== --- dev/buildr/1.5.4/site/css/syntax.css (added) +++ dev/buildr/1.5.4/site/css/syntax.css Sun Sep 24 21:59:16 2017 @@ -0,0 +1,23 @@ +/* Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with this + * work for additional information regarding copyright ownership. The ASF + * licenses this file to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + */ + +.highlight .k, .highlight .kp { color: blue } /* keyword */ +.highlight .no { color: darkblue } /* constant */ +.highlight .s1 { color: green } /* string */ +.highlight .n { color: black } /* identifier */ +.highlight .o, .highlight .p { color: darkblue } /* = + */ +.highlight .ss { color: darkblue } /* symbol */ +.highlight .c1 { color: gray } /* comment */