capistrano-distribution 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 51e2dcb1ba15f838b76d6eaf72e6f451c793f32b
+  data.tar.gz: 1cb882b4e420dc6c2292e897657f681b831d5515
+SHA512:
+  metadata.gz: 8f0275b355b9ee5311373aff3b70640ddb381fecd3dd3b6b57b9eab3817e17217a2c25667b53047dc69aa8fc3065050203fe7d828026c2f4bcfa1dc63ac2788c
+  data.tar.gz: 20a82ec2110fe7bfebd8ae1dfcd149e249f75332b1cde1d1fbeb4ac86afa6df2dff926958b2473b26c19882627f13414a02bc954540bc4cda5d87a2b5b70b78d

data/.yardopts

@@ -0,0 +1 @@
+--protected --private abstract lib/**/*.rb - README.md NEWS.md LICENSE

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2014 Spiceworks, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/NEWS.md

@@ -0,0 +1,35 @@
+# News and Notifications by Version
+
+This file lists noteworthy changes which may affect users of this project.  More
+detailed information is available in the rest of the documentation.
+
+**NOTE:** Date stamps in the following entries are in YYYY/MM/DD format.
+
+
+## v0.2.0 (2016/02/29)
+
+* Provide a setting (`:distribution_runner_opts`) to configure runner options.
+  * Must be a hash of options acceptable by the `on` method of sshkit.
+* Git distributables can now change the repo URL without manual intervention.
+* Pruning of dead Git branches now happens during repository update.
+  * Avoids too many dead branches causing updates to run forever.
+
+## v0.1.0 (2016/02/09)
+
+* Incompatible changes
+  * The `distribution` setting is now a stack of distributor definitions to be
+    applied in order as a series of overlays in the release area.
+* Provides the `distribution:set_current_revision` task used by newer
+  Capistrano releases.
+  * A `release_id` setting is required to provide a reasonable value.
+
+## v0.0.2 (2014/03/17)
+
+* Ensure that the internal_path attribute of AbstractArchiver is a Pathname
+  * Fixes extraction of ZIP archives.
+* Silence curl and unzip in the CurlZip distributor
+* Silence unzip in the Zip distributor
+
+## v0.0.1 (2014/02/27)
+
+* Birthday

data/README.md

@@ -0,0 +1,165 @@
+# Capistrano Distribution: More Than Just Git Deployments
+
+Flexible distribution for Capistrano 3.x.
+
+## LINKS
+
+* Homepage :: http://github.com/spiceworks/capistrano-distribution
+* Documentation :: http://rdoc.info/gems/capistrano-distribution/frames
+* Source :: http://github.com/spiceworks/capistrano-distribution
+
+## DESCRIPTION
+
+This gem hooks into the SCM functionality of Capistrano 3.x in order to provide
+a more generic distribution strategy.  Not only is it possible to deploy from a
+simple Git repository, but deployment of contents from Tar and ZIP files is also
+possible.  It is even easy to create deployments based on multiple sources.
+
+With the exception of the Git push method, all distribution operations pull
+content from providers on each target host.  For Git-based distributions
+whether using the push or pull method, this is very efficient after the first
+deployment because a mirror git repository is saved on each host such that only
+differentials are needed for future deployments.  All other types perform a
+full download of the source artifact, so these could be expensive and/or slow.
+
+## Features
+
+* Distribute from Git repositories and Tar/Zip archives.
+* Use remote and local sources, anything supported by Git and Curl.
+* Create homogenous deployments from multiple sources.
+
+## Known Bugs/Limitations
+
+* None so far...
+
+## SYNOPSIS
+
+Simple Git-based distribution (master branch of the current repository):
+
+```ruby
+# config/deploy.rb
+...
+set :scm, :distribution
+set :release_id, ->{ `git rev-parse HEAD`.chomp }
+set :distribution, ->{
+  [[
+    'http://example.com/repositories/example.git',
+    fetch(:release_id)
+  ]]
+}
+...
+```
+
+Simple Tar-based distribution (everything in the `example.tar.gz` archive is
+within an `example` subdirectory):
+
+```ruby
+# config/deploy.rb
+...
+set :scm, :distribution
+set :release_id, ->{ "example-#{fetch(:release_timestamp)}" }
+set :distribution, 'http://example.com/tarballs/example.tar.gz'
+...
+```
+
+Heterogenous distribution (a Redmine deployment with plugins):
+
+```ruby
+# config/deploy.rb
+...
+set :scm, :distribution
+set :release_id, ->{ "2.3.4-#{fetch(:release_timestamp)}" }
+set :distribution,
+  [
+    'http://www.redmine.org/releases/redmine-2.3.4.tar.gz'
+  ],
+  [
+    'https://bitbucket.org/akiko_pusu/redmine_issue_templates/get/0.0.4.tar.gz',
+    {
+      subtree: 'akiko_pusu-redmine_issue_templates-b885dfe8263d',
+      target: 'plugins/redmine_issue_templates'
+    }
+  ],
+  [
+    'https://bitbucket.org/haru_iida/redmine_code_review/get/0.6.2.tar.gz',
+    {
+      subtree: 'haru_iida-redmine_code_review-e79f98b8a77f',
+      target: 'plugins/redmine_code_review'
+    }
+  ],
+  [
+    'https://github.com/Undev/notify_custom_users/archive/0.0.5.tar.gz',
+    {
+      subtree: 'notify_custom_users-0.0.5',
+      target: 'plugins/notify_custom_users'
+    }
+  ],
+  [
+    'https://github.com/thorin/redmine_ldap_sync/archive/2.0.3.tar.gz',
+    {
+      subtree: 'redmine_ldap_sync-2.0.3',
+      target: 'plugins/redmine_ldap_sync'
+    }
+  ]
+...
+```
+
+## REQUIREMENTS
+
+* Git binary (for Git repositories)
+* Curl binary (for remote archives)
+* Unzip binary (for ZIP archives)
+* Tar binary (for Tar archives)
+
+## DEVELOPERS
+
+After checking out the source, run:
+
+    $ bundle install
+    $ bundle exec rake test yard
+
+This will install all dependencies, run the tests/specs, and generate the
+documentation.
+
+## AUTHORS
+
+Thanks to all contributors.  Without your help this project would not exist.
+
+* Jeremy Bopp :: jeremyb@spiceworks.com
+
+## Contributing
+
+Contributions for bug fixes, documentation, extensions, tests, etc. are
+encouraged.
+
+1. Clone the repository.
+2. Fix a bug or add a feature.
+3. Add tests for the fix or feature.
+4. Make a pull request.
+
+## LICENSE
+
+```
+(The MIT License)
+
+Copyright (c) 2014 Spiceworks, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

data/Rakefile

@@ -0,0 +1,243 @@
+# encoding: UTF-8
+# -*- ruby -*-
+
+require 'rubygems'
+
+require 'erb'
+require 'rake/testtask'
+require 'rubygems/package_task'
+require 'rake/clean'
+require 'yard'
+
+# Load the gemspec file for this project.
+GEMSPEC = Dir['*.gemspec'].first
+SPEC = eval(File.read(GEMSPEC), nil, GEMSPEC)
+
+# The path to the version.rb file and a string to eval to find the version.
+VERSION_RB = "lib/#{SPEC.name.gsub('-', '/')}/version.rb"
+VERSION_REF =
+  "#{SPEC.name.split('-').map { |p| p.split('_').map(&:capitalize).join }.join('::')}::VERSION"
+
+# A dynamically generated list of files that should match the manifest (the
+# combined contents of SPEC.files and SPEC.test_files).  The idea is for this
+# list to contain all project files except for those that have been explicitly
+# excluded.  This list will be compared with the manifest from the SPEC in order
+# to help catch the addition or removal of files to or from the project that
+# have not been accounted for either by an exclusion here or an inclusion in the
+# SPEC manifest.
+#
+# NOTE:
+# It is critical that the manifest is *not* automatically generated via globbing
+# and the like; otherwise, this will yield a simple comparison between
+# redundantly generated lists of files that probably will not protect the
+# project from the unintentional inclusion or exclusion of files in the
+# distribution.
+PKG_FILES = FileList.new(Dir.glob('**/*', File::FNM_DOTMATCH)) do |files|
+  # Exclude anything that doesn't exist as well as directories.
+  files.exclude {|file| ! File.exist?(file) || File.directory?(file)}
+  # Exclude Git administrative files.
+  files.exclude(%r{(^|[/\\])\.git(ignore|modules|keep)?([/\\]|$)})
+  # Exclude editor swap/temporary files.
+  files.exclude('**/.*.sw?')
+  # Exclude the gemspec file.
+  files.exclude(GEMSPEC)
+  # Exclude the README template file.
+  files.exclude('README.md.erb')
+  # Exclude resources for bundler.
+  files.exclude('Gemfile', 'Gemfile.lock')
+  files.exclude(%r{^.bundle([/\\]|$)})
+  files.exclude(%r{^vendor/bundle([/\\]|$)})
+  # Exclude generated content, except for the README file.
+  files.exclude(%r{^(pkg|doc|.yardoc)([/\\]|$)})
+  # Exclude Rubinius compiled Ruby files.
+  files.exclude('**/*.rbc')
+end
+
+# Make sure that :clean and :clobber will not whack the repository files.
+CLEAN.exclude('.git/**')
+# Vim swap files are fair game for clean up.
+CLEAN.include('**/.*.sw?')
+
+# Returns the value of the VERSION environment variable as a Gem::Version object
+# assuming it is set and a valid Gem version string.  Otherwise, raises an
+# exception.
+def get_version_argument
+  version = ENV['VERSION']
+  if version.to_s.empty?
+    raise "No version specified: Add VERSION=X.Y.Z to the command line"
+  end
+  begin
+    Gem::Version.create(version.dup)
+  rescue ArgumentError
+    raise "Invalid version specified in `VERSION=#{version}'"
+  end
+end
+
+# Performs an in place, per line edit of the file indicated by _path_ by calling
+# the sub method on each line and passing _pattern_, _replacement_, and _b_ as
+# arguments.
+def file_sub(path, pattern, replacement = nil, &b)
+  tmp_path = "#{path}.tmp"
+  File.open(path) do |infile|
+    File.open(tmp_path, 'w') do |outfile|
+      infile.each do |line|
+        outfile.write(line.sub(pattern, replacement, &b))
+      end
+    end
+  end
+  File.rename(tmp_path, path)
+end
+
+# Updates the version string in the gemspec file and a version.rb file it to the
+# string in _version_.
+def set_version(version)
+  file_sub(GEMSPEC, /(\.version\s*=\s*).*/, "\\1'#{version}'")
+  file_sub(VERSION_RB, /^(\s*VERSION\s*=\s*).*/, "\\1'#{version}'")
+end
+
+# Returns a string that is line wrapped at word boundaries, where each line is
+# no longer than _line_width_ characters.
+#
+# This is mostly lifted directly from ActionView::Helpers::TextHelper.
+def word_wrap(text, line_width = 80)
+  text.split("\n").collect do |line|
+    line.length > line_width ?
+      line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip :
+      line
+  end * "\n"
+end
+
+desc 'Alias for build:gem'
+task :build => 'build:gem'
+
+# Build related tasks.
+namespace :build do
+  # Create the gem and package tasks.
+  Gem::PackageTask.new(SPEC).define
+
+  # Ensure that the that the manifest is consulted when building the gem.  Any
+  # generated/compiled files should be available at that time.
+  task :gem => :check_manifest
+
+  desc 'Verify the manifest'
+  task :check_manifest do
+    manifest_files = (SPEC.files + SPEC.test_files).sort.uniq
+    pkg_files = PKG_FILES.sort.uniq
+    if manifest_files != pkg_files then
+      common_files = manifest_files & pkg_files
+      manifest_files -= common_files
+      pkg_files -= common_files
+      message = ["The manifest does not match the automatic file list."]
+      unless manifest_files.empty? then
+        message << "  Extraneous files:\n    " + manifest_files.join("\n    ")
+      end
+      unless pkg_files.empty?
+        message << "  Missing files:\n    " + pkg_files.join("\n    ")
+      end
+      raise message.join("\n")
+    end
+  end
+
+  # Creates the README.md file from a template and the gemspec contents.
+  file 'README.md' => ['README.md.erb', GEMSPEC] do
+    spec = SPEC
+    File.open('README.md', 'w') do |readme|
+      readme.write(
+        ERB.new(File.read('README.md.erb'), nil, '-').result(binding)
+      )
+    end
+  end
+end
+
+# Ensure that the clobber task also clobbers package files.
+task :clobber => 'build:clobber_package'
+
+# Create the documentation task.
+YARD::Rake::YardocTask.new
+# Ensure that the README file is (re)generated first.
+task :yard => 'README.md'
+
+# Gem related tasks.
+namespace :gem do
+  desc 'Alias for build:gem'
+  task :build => 'build:gem'
+
+  desc 'Publish the gemfile'
+  task :publish => ['version:check', :test, 'repo:tag', :build] do
+    sh "gem push pkg/#{SPEC.name}-#{SPEC.version}*.gem"
+  end
+end
+
+Rake::TestTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+# Version string management tasks.
+namespace :version do
+  desc 'Set the version for the project to a specified version'
+  task :set do
+    set_version(get_version_argument)
+  end
+
+  desc 'Set the version for the project back to 0.0.0'
+  task :reset do
+    set_version('0.0.0')
+  end
+
+  desc 'Check that all version strings are correctly set'
+  task :check => ['version:check:spec', 'version:check:version_rb', 'version:check:news']
+
+  namespace :check do
+    desc 'Check that the version in the gemspec is correctly set'
+    task :spec do
+      version = get_version_argument
+      if version != SPEC.version
+        raise "The given version `#{version}' does not match the gemspec version `#{SPEC.version}'"
+      end
+    end
+
+    desc 'Check that the version in the version.rb file is correctly set'
+    task :version_rb do
+      version = get_version_argument
+      begin
+        load VERSION_RB
+        internal_version = Gem::Version.create(eval(VERSION_REF))
+        if version != internal_version
+          raise "The given version `#{version}' does not match the version.rb version `#{internal_version}'"
+        end
+      rescue ArgumentError
+        raise "Invalid version specified in `#{VERSION_RB}'"
+      end
+    end
+
+    desc 'Check that the NEWS.md file mentions the version'
+    task :news do
+      version = get_version_argument
+      begin
+        File.open('NEWS.md') do |news|
+          unless news.each_line.any? {|l| l =~ /^## v#{Regexp.escape(version.to_s)} /}
+            raise "The NEWS.md file does not mention version `#{version}'"
+          end
+        end
+      rescue Errno::ENOENT
+        raise 'No NEWS.md file found'
+      end
+    end
+  end
+end
+
+# Repository and workspace management tasks.
+namespace :repo do
+  desc 'Tag the current HEAD with the version string'
+  task :tag => :check_workspace do
+    version = get_version_argument
+    sh "git tag -s -m 'Release v#{version}' v#{version}"
+  end
+
+  desc 'Ensure the workspace is fully committed and clean'
+  task :check_workspace => ['README.md'] do
+    unless `git status --untracked-files=all --porcelain`.empty?
+      raise 'Workspace has been modified.  Commit pending changes and try again.'
+    end
+  end
+end

data/lib/capistrano/distribution/distributor/abstract.rb

@@ -0,0 +1,85 @@
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# @abstract Subclass and override {#check} and {#distribute} to create a
+#   distributor.
+#
+# An abstract distributor upon which all distributors should ultimately be
+# based.
+#
+# See the existing concrete distributor definitions for examples.
+class Abstract
+  ##
+  # @param context [(#test, #execute)] a Capistrano context used to run
+  #   commands.
+  # @param url [URI, String] a URL to be used for fetching the artifact to be
+  #   distributed
+  # @param opts [Hash] options to override default settings
+  # @option opts [String] :target ('') a path within the release area to be the
+  #   root of the distribution.
+  def initialize(context, url, opts = {})
+    @context = context
+    @url = URI === url ? url : URI.parse(url)
+    @target = opts.fetch(:target, '')
+
+    @repo_id = Digest::SHA1.hexdigest(url.to_s)
+  end
+
+  ##
+  # @abstract Override to provide a meaningful check for prerequisites during
+  #   deployment.
+  #
+  # @return [Boolean] +true+ when prerequisites are met and +false+
+  #   otherwise.
+  def check
+    false
+  end
+
+  ##
+  # @abstract Override to provide meaningful distribution logic during
+  #   deployment.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when distribution fails.
+  def distribute
+  end
+
+  private
+
+  ##
+  # The source URL for the artifact to be distributed.
+  attr_reader :url
+
+  ##
+  # The Capistrano context in which the distributor will operate.
+  attr_reader :context
+
+  ##
+  # A unique identifier for the distributor for use under {#repo_path}.
+  attr_reader :repo_id
+
+  ##
+  # A path relative to the release location in which to distribute the artifact.
+  attr_reader :target
+
+  ##
+  # @return [Pathname] a path to the release location in which to distribute the
+  #   artifact based on {#target}
+  def release_path
+    context.release_path.join(target)
+  end
+
+  ##
+  # @return [Pathname] a path under the repo location to a unique workspace for
+  #   the distributor
+  def repo_path
+    context.repo_path.join(repo_id)
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/abstract_archiver.rb

@@ -0,0 +1,60 @@
+require 'pathname'
+
+require 'capistrano/distribution/distributor/abstract'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# @abstract Subclass and override {#distribute} to create a distributor that
+#   extracts archives found on the local filesystem.
+#
+# A convenience class for distributors that extract an archive file.
+class AbstractArchiver < Abstract
+  ##
+  # A regexp that matches file extentions typically found on archives used to
+  # distribute program binaries and source releases.
+  EXT_MATCHER = %r{(\.[^\d.]+[^.]*)+$}
+
+  ##
+  # @param context [{#test, #execute}] a Capistrano context used to run
+  #   commands.
+  # @param url [URI, String] a URL to be used for fetching the artifact to be
+  #   distributed
+  # @param opts [Hash] options to override default settings
+  # @option opts [String] :subtree a path within the archive to extract as if
+  #   its contents were at the root of the archive
+  def initialize(context, url, opts = {})
+    super(context, url, opts)
+    @subtree = Pathname.new(
+      opts.fetch(:subtree, File.basename(url).sub(ext_matcher, ''))
+    )
+  end
+
+  ##
+  # Tests whether or not the archive indicated by {#url} is locally available.
+  #
+  # @return [Boolean] +true+ if the archive is available; otherwise, +false+.
+  #
+  # @see Abstract#check
+  def check
+    context.test '[', '-f', url.path, ']'
+  end
+
+  private
+
+  ##
+  # The path within the archive to extract.  May be an empty string.
+  attr_reader :subtree
+
+  ##
+  # @return [Regexp] a regexp that matches file extentions.
+  def ext_matcher
+    EXT_MATCHER
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/abstract_curl.rb

@@ -0,0 +1,28 @@
+require 'capistrano/distribution/distributor/abstract_archiver'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# @abstract Subclass and override {#distribute} to create a distributor that
+#   extracts archives reachable via +curl+ command.
+#
+# A convenience class for distributors that extract an archive downloaded using
+# the +curl+ command.
+class AbstractCurl < AbstractArchiver
+  ##
+  # Tests whether or not the archive indicated by {#url} is available via the
+  # +curl+ command.
+  #
+  # @return [Boolean] +true+ if the archive is available; otherwise, +false+.
+  #
+  # @see Abstract#check
+  def check
+    context.test 'curl', '--fail', '--location', '--silent', '--head', '--request', 'GET', url
+  end
+end
+
+end
+end
+end