buildr-gemjar 1.0.0

data/vendor/buildr/doc/releasing.textile

@@ -0,0 +1,117 @@
+---
+layout: default
+title: Releasing
+---
+
+Now that we built and tested our awesome software, let's tell the world and release it.
+
+Each buildfile can specify the current version with a constant named @VERSION_NUMBER@  or @THIS_VERSION@.
+
+{% highlight ruby %}
+THIS_VERSION = "1.0.0-SNAPSHOT"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end
+{% endhighlight %}
+
+
+h2(#default). What does a release do?
+
+The default behavior of the @Release@ task is the following:
+# Check that the version to be released and the next version are different
+# Check that the project is being tracked by Git or Subversion
+# Package, test and deploy the artifacts using @THIS_VERSION@ value minus the @-SNAPSHOT@ suffix (if any)
+# Tag the repository with the released version number
+# Update the value of @THIS_VERSION@ in the buildfile with the next version number
+
+Buildr will increment the last digit of the 3-digit versioni number if @THIS_VERSION@ ends with @-SNAPSHOT@.
+So, at the end of a release, the buildfile now looks like this:
+
+{% highlight ruby %}
+THIS_VERSION = "1.0.1-SNAPSHOT"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end
+{% endhighlight %}
+
+And the Git repository now contains two new commits and a new tag.
+
+{% highlight sh %}
+~/w/killer-app[master]$git ol -4
+c1af3d5  (HEAD, origin/master, master) Changed version number to 1.0.1-SNAPSHOT
+dd35015  (tag: 1.0.0) Changed version number to 1.0.0
+76c96e7  Last fix before the release
+{% endhighlight %}
+
+
+h2(#custom_version). How to specify my own version number scheme?
+
+If @THIS_VERSION@ does not contain @-SNAPSHOT@, Buildr delegates the resolution of the next version number to the user which has 2 differents ways to express her wishes: @Release.next_version@ or the environment variable @NEXT_VERSION@.
+
+h3(#next_version_proc). Using Release.next_version
+
+The @Release@ class can receive the next version of the buildfile. This could be a string or a proc that would receive the current version and return the next version.
+
+{% highlight ruby %}
+THIS_VERSION = "1.0.0-SNAPSHOT"
+
+# a string
+Release.next_version = "2.0.0-SNAPSHOT"
+
+# or a proc
+Release.next_version = lambda do |this_version| # 1.0.0-SNAPSHOT
+    new_version = @THIS_VERSION@.split(/\./)
+    new_version[0] = new_version[0] + 1
+    new_version
+end
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end
+{% endhighlight %}
+
+
+h3(#next_version_envvar). Using the environment variable NEXT_VERSION
+
+If the environment variable @NEXT_VERSION@ is set, Buildr will use this value to update @THIS_VERSION@ at the end of the release.
+
+For conveniency, this variable is case insensitive.
+
+So, all 3 following commands will run a release with a custom new version:
+
+{% highlight sh %}
+$ buildr release next_version="1.0.0-rc1"
+$ env next_version="1.0.0-rc1" buildr release
+$ env NEXT_VERSION="1.0.0-rc1" buildr release
+{% endhighlight %}
+
+Those commands will generate the Buildfile below:
+
+{% highlight ruby %}
+THIS_VERSION = "1.0.0-rc1"
+
+define 'killer-app' do
+
+  project.version = THIS_VERSION
+
+  # ...
+end
+{% endhighlight %}
+
+The environment variable @NEXT_VERSION@ has precedence over Release.next_version.
+
+h2(#custom_tag_and_msg). How to specify my own tag name and commit message?
+
+As explained earlier, Buildr will create two new commits and a new tag in the version control system. Similarly to @Release.next_version@, the commit message and the tag name can be customized with @Release.message@ and @Release.tag_name@. Both could be strings or procs that would receive the released version @THIS_VERSION@ without @-SNAPSHOT@.
+

data/vendor/buildr/doc/scripts/buildr-git.rb

@@ -0,0 +1,512 @@
+#!/usr/bin/env ruby
+# 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.
+
+
+# This script helps buildr developers to obtain their own git clone from
+# github, and also provides GitFlow commands to keep the git mirror in sync
+# with Apache SVN.
+#
+# If you already have a buildr clone, just do the following:
+#
+#    git config alias.apache '!'"ruby $PWD/doc/scripts/buildr-git.rb"
+#
+# After this, you have a 'git apache' command and you can try (be sure to read the help)
+#
+#    git apache help
+#    git apache setup svn --help
+#    git apache sync --help
+#
+# To configure your local repo for svn synchronization,
+#
+#    git apache update-authors
+#    git remote add upstream git@github.com:buildr/buildr.git
+#    git apache setup svn --username apacheLogin --apache-git upstream
+#    git apache sync
+#
+# This script can also be run without having a local buildr clone:
+#
+#   ruby -ropen-uri -e 'eval(open("http://svn.apache.org/viewvc/buildr/trunk/doc/scripts/buildr-git.rb?view=co").read)' help
+
+
+
+require 'yaml'
+require 'open-uri'
+
+if $0 == '-e' # invoked from open-uri
+  gitflow = "http://svn.apache.org/viewvc/buildr/trunk/doc/scripts/gitflow.rb?view=co"
+  eval(open(gitflow).read)
+else
+  require File.expand_path('gitflow', File.dirname(__FILE__))
+end
+
+GitFlow.program = 'buildr-git'
+
+module BuildrGit
+
+  class UpdateUsersCommand < GitFlow/'update-users'
+
+    @help = "Update list of Apache SVN committers from Jukka's list."
+    @@url = 'http://people.apache.org/~jukka/authors.txt'
+
+    def self.authors_file
+      File.expand_path('.git/authors.txt', Dir.pwd)
+    end
+
+    def self.user_email(apache_login, authors_file = nil)
+      authors_file ||= self.authors_file
+      authors = YAML.load(File.read(authors_file).gsub!(/\s+=\s+/, ': '))
+      contact = authors[apache_login]
+      fail "You are not listed as apache commiter on #{authors_file}" unless contact
+      fail "Not a valid contact line: #{contact}" unless contact =~ /\s+<(.*)>/
+      [$`, $1]
+    end
+
+    def options(opts)
+      opts.url = @@url
+      opts.file = self.class.authors_file
+      [['-u', '--url URL',
+        "From URL. defaults to: #{opts.url}", lambda { |url|
+          opts.url = url
+       }],
+       ['-f', '--file FILE',
+        "Write to FILE, defaults to #{opts.file}", lambda { |path|
+          opts.file = path
+        }]
+      ]
+    end
+
+    def execute(opts, argv)
+      FileUtils.mkdir_p(File.dirname(opts.file))
+      content = open(opts.url).read
+      File.open(opts.file, "w") { |f| f.print content }
+    end
+  end
+
+  class CloneCommand < GitFlow/:clone
+    @help = "Create a clone from github.com/buildr repository."
+
+    def options(opts)
+      opts.origin = 'git://github.com/buildr/buildr.git'
+      opts.svn_prefix = 'apache'
+      opts.project = 'buildr'
+      opts.local = expand_path(opts.project)
+      [['--prefix SVN_PREFIX', opts.svn_prefix, lambda { |p|
+          opts.svn_prefix = p }],
+       ['--origin GIT_ORIGIN', opts.origin, lambda { |o|
+          opts.origin = o }],
+       ['-d', '--dir DIR', opts.local, lambda { |d| opts.local = d }]
+      ]
+    end
+
+    def execute(opts, argv)
+      git 'clone', opts.origin, opts.local
+      Dir.chdir(opts.local) do
+        run 'update-users'
+        run 'setup'
+      end
+    end
+  end
+
+  class SetupCommand < GitFlow/:setup
+    @help = "Setup your buildr clone to be used with git mirror."
+    def options(opt)
+      []
+    end
+
+    def execute(opt, argv)
+      run 'setup', 'alias'
+      run 'setup', 'svn'
+    end
+  end
+
+  class SetupAliasCommand < SetupCommand/:alias
+    def execute(opt, argv)
+      me = expand_path('doc/scripts/buildr-git.rb')
+      git 'config', 'alias.apache', "!ruby #{me}"
+    end
+  end
+
+  class SetupSvnCommand < SetupCommand/:svn
+    @help = "Setup for getting changes from Apache SVN."
+
+    def options(opt)
+      opt.svn_prefix = 'apache'
+      opt.svn_path = 'buildr'
+      opt.townhall = 'origin'
+      [['--username SVN_USER', 'Use Apache svn username for this svn remote',
+        lambda { |e| opt.apache_login = e  }],
+       ['--svn-prefix PREFIX', 'The name of svn remote to use for project.',
+        "Defaults to #{opt.svn_prefix}",
+        lambda{|p| opt.svn_prefix = p }],
+       ['--svn-uri URI', lambda {|p| opt.svn_uri = p  }],
+       ['--svn-rev REVISION', lambda {|p| opt.svn_rev = p  }],
+       ['--svn-path PATH', 'The path to append to svn-uri.',
+        "Defaults to #{opt.svn_path}", lambda {|p| opt.svn_path = p  }],
+       ['--apache-git REMOTE', 'The name of remote you are using as town-hall git repo.',
+        "Defaults to #{opt.townhall}",
+        lambda {|p| opt.townhall = p }]
+      ]
+    end
+
+    def execute(opt, argv)
+      authors_file = UpdateUsersCommand.authors_file
+      git 'config', 'svn.authorsfile', authors_file
+      git 'config', 'apache.svn', opt.svn_prefix
+      git 'config', 'apache.git', opt.townhall
+
+      if opt.apache_login
+        user, email = UpdateUsersCommand.user_email(opt.apache_login, authors_file)
+        puts "You claim to be #{user} <#{email}> with apache login: #{opt.apache_login}"
+        git('config', 'user.name', user)
+        git('config', 'user.email', email)
+      end
+
+      if opt.svn_rev
+        revision = opt.svn_rev
+      else
+        location, revision = svn_loc_rev
+        revision = opt.svn_rev || revision
+      end
+
+      if opt.svn_uri
+        repo = opt.svn_uri
+      else
+        fail "No #{opt.svn_path} directory on #{location}" unless
+          location =~ /\/#{opt.svn_path}/
+        repo = $`
+      end
+
+      # Tell git where the svn repository is
+      git('config', "svn-remote.#{opt.svn_prefix}.url", repo)
+      git('config', "svn-remote.#{opt.svn_prefix}.fetch",
+          "#{opt.svn_path}/trunk:refs/remotes/#{opt.svn_prefix}/trunk")
+      git('config', "svn-remote.#{opt.svn_prefix}.branches",
+          "#{opt.svn_path}/branches/*:refs/remotes/#{opt.svn_prefix}/*")
+      git('config', "svn-remote.#{opt.svn_prefix}.tags",
+          "#{opt.svn_path}/tags/*:refs/remotes/#{opt.svn_prefix}/tags/*")
+
+      # Store the user for svn dcommit
+      if opt.apache_login
+        git('config', "svn-remote.#{opt.svn_prefix}.username", opt.apache_login)
+      end
+
+      # Create the svn branch, do this instead of pulling the full svn history
+      git('update-ref', "refs/remotes/#{opt.svn_prefix}/trunk",
+          'refs/remotes/origin/master')
+      # create tags from git
+      git('tag').split.each do |tag|
+        git('update-ref', "refs/remotes/#{opt.svn_prefix}/tags/#{tag}",
+            "refs/tags/#{tag}")
+      end
+      # update svn metadata
+      mkdir_p(expand_path('.git/svn'))
+      svn_meta = expand_path('.git/svn/.metadata')
+      git('config', '--file', svn_meta,
+          "svn-remote.#{opt.svn_prefix}.branches-maxRev", revision)
+      git('config', '--file', svn_meta,
+          "svn-remote.#{opt.svn_prefix}.tags-maxRev", revision)
+    end
+
+    def svn_loc_rev
+      meta = sh('git log -n 10 | grep git-svn-id | head -n 1').chomp
+      fail "No svn metadata on last 10 commits" if meta.empty?
+      meta.split[1].split('@')
+    end
+  end
+
+  class FetchCommand < GitFlow/:fetch
+    @help = "Get changes from svn, creating tags, branches on townhall"
+    @documentation = <<-DOC
+This command can be used to fetch changes from Apache\'s SVN repo.
+
+GIT CONFIG VALUES:
+
+apache.svn  - The svn remote using to get changes from Apache SVN.
+              Set by setup-svn --svn-prefix.
+    DOC
+
+    def options(opt)
+      opt.apache_svn = git('config', '--get', 'apache.svn').chomp rescue nil
+      [['--apache-svn SVN_REMOTE', 'The SVN remote used to get changes from Apache',
+        "Current value: #{opt.apache_svn}",
+        lambda { |r| opt.apache_svn = r }]
+       ]
+    end
+
+    def execute(opt, argv)
+      fail "Missing apache.svn config value" unless opt.apache_svn
+      git('svn', 'fetch', opt.apache_svn)
+    end
+  end
+
+  class SyncCommand < GitFlow/:sync
+    @help = "Synchronizes between Apache svn and git townhall."
+    @documentation = <<-DOC
+This command will perform the following actions:
+  * fetch changes from apache svn.
+  * rebase them on the current branch or on the one specified with --onto
+  * dcommit (this will push your changes to Apache trunk)
+
+GIT CONFIG VALUES:
+
+apache.svn
+  The svn remote using to get changes from Apache SVN.
+  Set by setup-svn --svn-prefix.
+
+apache.git
+  The git remote used as townhall repository.
+  Set by setup-svn --townhall.
+
+svn-remote.APACHE_GIT.username
+  If configured, sync will use this svn username while dcommiting.
+DOC
+
+    def options(opt)
+      git('branch').split.tap { |n| opt.current = n[n.index('*')+1] }
+      opt.branch = opt.current
+      opt.svn_branch = 'trunk'
+      opt.git_branch = 'master'
+      opt.apache_git = git('config', '--get', 'apache.git').chomp rescue nil
+      opt.apache_svn = git('config', '--get', 'apache.svn').chomp rescue nil
+      opt.svn_username = git('config', '--get',
+                             "svn-remote.#{opt.apache_svn}.username").chomp rescue nil
+      [['--apache-svn SVN_REMOTE', 'The SVN remote used to get changes from Apache',
+        "Current value: #{opt.apache_svn}",
+        lambda { |r| opt.apache_svn = r }],
+       ['--apache-git REMOTE', 'The git remote used as town-hall repository.',
+        "Current value: #{opt.apache_git}",
+        lambda { |r| opt.apache_git = r }],
+       ['--username SVN_USER',
+        'Specify the SVN username for dcommit',
+        "Defaults to: #{opt.svn_username}",
+        lambda { |b| opt.svn_username = b }],
+       ['--svn-branch SVN_BRANCH',
+        'Specify the SVN branch to rebase changes from, and where to dcommit',
+        "Defaults to: #{opt.svn_branch}",
+        lambda { |b| opt.svn_branch = b }],
+       ['--git-branch REMOTE_BRANCH',
+        'Specify the remote town-hall branch (on apache.git) to update',
+        "Defaults to: #{opt.git_branch}",
+        lambda { |b| opt.git_branch = b }],
+       ['--branch BRANCH', 'Specify the local branch to take changes from',
+        "Current branch: #{opt.branch}",
+        lambda { |b| opt.branch = b }]
+      ]
+    end
+
+    def execute(opt, argv)
+      # obtain the svn url
+      url = git('config', '--get', "svn-remote.#{opt.apache_svn}.url").chomp
+      # obtain the path for project
+      path = git('config', '--get', "svn-remote.#{opt.apache_svn}.branches").
+        chomp.split('/branches').first
+      commit_url = "#{url}/#{path}/#{opt.svn_branch}"
+
+      # obtain latest changes from svn
+      git('svn', 'fetch', '--svn-remote', opt.apache_svn)
+      # obtain latest changes from git
+      git('fetch', opt.apache_git,
+          "#{opt.git_branch}:refs/remotes/#{opt.apache_git}/#{opt.git_branch}")
+
+      # rebase svn changes in the desired branch
+      git('rebase', "#{opt.apache_svn}/#{opt.svn_branch}", opt.branch)
+      git('rebase', "#{opt.apache_git}/#{opt.git_branch}", opt.branch)
+
+      # dcommit to the specific svn branch
+      ['svn', 'dcommit',
+       '--svn-remote', opt.apache_svn, '--commit-url', commit_url].tap do |cmd|
+        if opt.svn_username
+          cmd << '--username' << opt.svn_username
+        end
+        git(*cmd)
+      end
+
+      # update townhall remote ref
+      git('update-ref',
+          "refs/remotes/#{opt.apache_git}/#{opt.git_branch}",
+          "refs/remotes/#{opt.apache_svn}/#{opt.svn_branch}")
+
+      # forward the remote townhall/master to apache/trunk
+      git('push', opt.apache_git,
+          "refs/remotes/#{opt.apache_git}/#{opt.git_branch}:#{opt.git_branch}")
+
+      # get back to the original branch
+      git('checkout', opt.current)
+    end
+  end
+
+
+  # This one is displayed when the user executes this script using
+  # open-uri -e
+  HEADER = <<HEADER
+
+Buildr official commit channel is Apache's svn repository, however some
+developers may prefer to use git while working on several features and
+merging other's changes.
+
+This script will configure a gitflow copy on so you can commit to svn.
+
+Enter <-h> to see options, <-H> to see notes about configured aliases
+and recommended workflow, or any other option.
+
+Ctrl+D or an invalid option to abort
+HEADER
+
+  # When fork is completed, we display the following notice on a
+  # pager, giving the user a brief overview of git aliases used
+  # to keep the mirror in sync.
+  NOTICE = <<NOTICE
+ALIASES:
+
+  Some git aliases have been created for developer convenience:
+
+    git apache fetch    # get changes from apache/trunk without merging them
+                        # you can inspect what's happening on trunk without
+                        # having to worry about merging conflicts.
+                        # Inspect the remote branch with `git log apache/trunk`
+                        # Or if you have a git-ui like `tig` you can use that.
+
+    git apache merge    # Merge already fetched changes on the current branch
+                        # Use this command to get up to date with trunk changes
+                        # you can always cherry-pick from the apache/trunk
+                        # branch.
+
+    git apache pull     # get apache-fetch && git apache-merge
+
+    git apache push     # Push to Apache's SVN. Only staged changes (those
+                        # recorded using `git commit`) will be sent to SVN.
+                        # You need not to be on the master branch.
+                        # Actually you can work on a tiny-feature branch and
+                        # commit directly from it.
+                        #
+                        # VERY IMPORTANT:
+                        #
+                        # Missing commits on Apache's SVN will be sent using
+                        # your apache svn account. This means that you can
+                        # make some commits on behalf of others (like patches
+                        # comming from JIRA issues or casual contributors)
+                        # Review the apache-push alias on .git/config if you
+                        # want to change login-name used for commit to SVN.
+                        #
+                        # See the recommended workflow to avoid commiting
+                        # other developers' changes and the following section.
+
+THE GITHUB MIRROR:
+
+   Buildr has an unofficial git mirror on github, maintained by Apache committers:
+
+     http://github.com/buildr/buildr
+
+   This mirror DOES NOT replace Apache's SVN repository. We really care about
+   using Apache infrastructure and following Apache project guidelines for
+   contributions. This git mirror is provided only for developers convenience,
+   allowing them to easily create experimental branches or review code from
+   other committers.
+
+   All code that wants to make it to the official Apache Buildr repository needs
+   to be committed to the Apache SVN repository by using the command:
+
+      git synchronize
+
+   This command will synchronize both ways svn<->git to keep trunk upto date.
+   You need to be an Apache committer and have permissions on the SVN repo.
+
+   It's VERY IMPORTANT for Buildr committers to remember that contributions from
+   external entities wanting to be accepted will require them to sign the Apache ICLA.
+   We provide the git mirror to make it easier for people to experiment and
+   contribute back to Buildr, before merging their code in, please remember they
+   have to create create a JIRA issue granting ASF permission to include their code,
+   just like any other contribution following Apache's guidelines.
+
+   So, it's very important - if you care about meritocracy - to follow or at
+   least that you get an idea of the recommended workflow.
+
+RECOMMENDED WORKFLOW:
+
+   So now that you have your local buildr copy you can create topic branches
+   to work on independent features, and still merge easily with head changes.
+
+   They may seem lots of things to consider, but it's all for Buildr's healt.
+   As all things git, you can always follow your own workflow and even create
+   aliases on you .git/config file to avoid typing much. So, here they are:
+
+   1) get your gitflow configured
+     (you have already do so, this was the most difficult part)
+
+   2) create a topic branch to work on, say.. you want to add cool-feature:
+
+        git checkout -b cool-feature master
+        # now on branch cool-feature
+
+   3) hack hack hack.. use the source luke.
+      every time you feel you have something important like added failing
+      spec, added part of feature, or resolved some conflict from merges,
+      you can commit your current progress. If you want to be selective, use:
+
+        git commit --interactive
+
+   3) review your changes, get ALL specs passing, repeat step 3 as needed
+
+   4) let's see what are they doing on trunk
+
+        git apache-fetch
+        # You can inspect the upstream changes without having to merge them
+        git log apache/trunk # what are they doing!!
+
+   5) integrate mainstream changes to your cool-feature branch, you can always
+      use `git cherry-pick` to select only some commits.
+
+        git merge apache/trunk cool-feature
+
+   6) Go to 3 unless ALL specs are passing.
+
+   7.a) (Skip to 7.b you have commit bit on Apache's SVN)
+      Create a patch using `git format-patch`
+      Promote your changes, create a JIRA issue and upload it granting Apache
+      license to include your code:
+
+        https://issues.apache.org/jira/browse/BUILDR
+        dev@buildr.apache.org
+
+   7.b) Now you have everyhing on staging area and merged important changes
+      from apache/trunk, it's time to commit them to Apache's SVN.
+
+        git apache-push
+
+   8) Optional. If you are a buildr committer you may want to synchronize
+     the github mirror for helping others to get changes without having to
+     wait on Victor's cronjob to run every hour (useful for urgent changes).
+
+        git synchronize
+
+   9) Pull changes from origin frequently.
+
+        git fetch origin
+        git rebase --onto origin/master master master
+
+   10) Unconditionally, Go to step 2 ;)
+       Share your gitflow workflow, git tips, etc.
+
+RESOURCES:
+
+   http://github.com/buildr/buildr/tree/master
+   http://git.or.cz/gitwiki/GitCheatSheet
+   http://groups.google.com/group/git-users/web/git-references
+
+NOTICE
+  #' for emacs
+
+end