capistrano 3.4.0 → 3.17.1

data/UPGRADING-3.7.md

@@ -0,0 +1,86 @@
+# Capistrano 3.7.0 upgrade guide
+
+## The :scm variable is deprecated
+
+Up until now, Capistrano's SCM was configured using the `:scm` variable:
+
+```ruby
+# This is now deprecated
+set :scm, :svn
+```
+
+To avoid deprecation warnings:
+
+1. Remove `set :scm, ...` from your Capistrano configuration.
+2. Add *one* of the following SCM declarations to your `Capfile` after `require "capistrano/deploy"`:
+
+```ruby
+# To use Git
+require "capistrano/scm/git"
+install_plugin Capistrano::SCM::Git
+
+# To use Mercurial
+require "capistrano/scm/hg"
+install_plugin Capistrano::SCM::Hg
+
+# To use Subversion
+require "capistrano/scm/svn"
+install_plugin Capistrano::SCM::Svn
+```
+
+## This is the last release where Git is the automatic default
+
+If you do not specify an SCM, Capistrano assumes Git. However this behavior is
+now deprecated. Add this to your Capfile to avoid deprecation warnings:
+
+```ruby
+require "capistrano/scm/git"
+install_plugin Capistrano::SCM::Git
+```
+
+## :git_strategy, :hg_strategy, and :svn_strategy are removed
+
+Capistrano 3.7.0 has a rewritten SCM system that relies on "plugins". This
+system is more flexible than the old "strategy" system that only allowed certain
+parts of SCM tasks to be customized.
+
+If your deployment relies on a custom SCM strategy, you will need to rewrite
+that strategy to be a full-fledged SCM plugin instead. There is a fairly
+straightforward migration path: write your plugin to be a subclass of the
+built-in SCM that you want to customize. For example:
+
+```ruby
+require "capistrano/scm/git"
+
+class MyCustomGit < Capistrano::SCM::Git
+  # Override the methods you wish to customize, e.g.:
+  def clone_repo
+    # ...
+  end
+end
+```
+
+Then use your plugin in by loading it in the Capfile:
+
+```ruby
+require_relative "path/to/my_custom_git.rb"
+install_plugin MyCustomGit
+```
+
+## Existing third-party SCMs are deprecated
+
+If you are using a third-party SCM, you can continue using it without
+changes, but you will see deprecation warnings. Contact the maintainer of the
+third-party SCM gem and ask them about modifying the gem to work with the new
+Capistrano 3.7.0 SCM plugin system.
+
+## remote_file is removed
+
+The `remote_file` method is no longer in Capistrano 3.7.0. You can read the
+discussion that led to its removal here:
+[issue 762](https://github.com/capistrano/capistrano/issues/762).
+
+There is no direct replacement. To migrate to 3.7.0, you will need to rewrite
+any parts of your deployment that use `remote_file` to use a different
+mechanism for uploading files. Consider using the `upload!` method directly in
+a procedural fashion instead.

data/bin/cap

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
-require 'capistrano/all'
+require "capistrano/all"
 Capistrano::Application.new.run

data/capistrano.gemspec

@@ -1,37 +1,34 @@
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'capistrano/version'
+require "capistrano/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "capistrano"
   gem.version       = Capistrano::VERSION
   gem.authors       = ["Tom Clements", "Lee Hambley"]
   gem.email         = ["seenmyfate@gmail.com", "lee.hambley@gmail.com"]
-  gem.description   = %q{Capistrano is a utility and framework for executing commands in parallel on multiple remote machines, via SSH.}
-  gem.summary       = %q{Capistrano - Welcome to easy deployment with Ruby over SSH}
-  gem.homepage      = "http://capistranorb.com/"
-
-  gem.files         = `git ls-files`.split($/)
-  gem.executables   = ['cap', 'capify']
+  gem.description   = "Capistrano is a utility and framework for executing commands in parallel on multiple remote machines, via SSH."
+  gem.summary       = "Capistrano - Welcome to easy deployment with Ruby over SSH"
+  gem.homepage      = "https://capistranorb.com/"
+  gem.metadata      = {
+    "bug_tracker_uri" => "https://github.com/capistrano/capistrano/issues",
+    "changelog_uri" => "https://github.com/capistrano/capistrano/releases",
+    "source_code_uri" => "https://github.com/capistrano/capistrano",
+    "homepage_uri" => "https://capistranorb.com/",
+    "documentation_uri" => "https://capistranorb.com/"
+  }
+  gem.files         = `git ls-files -z`.split("\x0").reject { |f| f =~ /^docs/ }
+  gem.executables   = %w(cap capify)
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.licenses      = ['MIT']
-
-  gem.post_install_message = <<eos
-Capistrano 3.1 has some breaking changes. Please check the CHANGELOG: http://goo.gl/SxB0lr
-
-If you're upgrading Capistrano from 2.x, we recommend to read the upgrade guide: http://goo.gl/4536kB
-
-The `deploy:restart` hook for passenger applications is now in a separate gem called capistrano-passenger.  Just add it to your Gemfile and require it in your Capfile.
-eos
-
-  gem.required_ruby_version = '>= 1.9.3'
-  gem.add_dependency 'sshkit', '~> 1.3'
-  gem.add_dependency 'rake', '>= 10.0.0'
-  gem.add_dependency 'i18n'
+  gem.licenses      = ["MIT"]
 
-  gem.add_development_dependency 'rspec'
-  gem.add_development_dependency 'mocha'
+  gem.required_ruby_version = ">= 2.0"
+  gem.add_dependency "airbrussh", ">= 1.0.0"
+  gem.add_dependency "i18n"
+  gem.add_dependency "rake", ">= 10.0.0"
+  gem.add_dependency "sshkit", ">= 1.9.0"
 end

data/features/deploy.feature

@@ -7,7 +7,7 @@ Feature: Deploy
   Scenario: Creating the repo
     When I run cap "git:check"
     Then the task is successful
-    And references in the remote repo are listed
+    And git wrapper permissions are 0700
 
   Scenario: Creating the directory structure
     When I run cap "deploy:check:directories"
@@ -52,3 +52,37 @@ Feature: Deploy
     When I run cap "deploy:symlink:release"
     Then the current directory will be a symlink to the release
 
+  Scenario: Cleanup
+    Given config stage file has line "set :keep_releases, 3"
+    And 5 valid existing releases
+    And an invalid release named "new"
+    When I run cap "deploy:cleanup"
+    Then 3 valid releases are kept
+    And the invalid "new" release is ignored
+
+  Scenario: Cleanup after many failed releases doesn't remove last good release
+    Given config stage file has line "set :keep_releases, 2"
+    And I make 2 deployments
+    And an invalid release named "77777777777777"
+    And an invalid release named "88888888888888"
+    And an invalid release named "99999999999999"
+    When I run cap "deploy:cleanup"
+    Then 3 valid releases are kept
+    And the current directory will be a symlink to the release
+
+  Scenario: Cleanup when there are more releases than arguments can handle
+    Given config stage file has line "set :keep_releases, 3"
+    And 5000 valid existing releases
+    When I run cap "deploy:cleanup"
+    Then 3 valid releases are kept
+
+  Scenario: Rolling Back
+    Given I make 2 deployments
+    When I run cap "deploy:rollback"
+    Then the current symlink points to the previous release
+
+  Scenario: Rolling Back to a specific release
+    Given I make 3 deployments
+    When I rollback to a specific release
+    Then the current symlink points to that specific release
+

data/features/doctor.feature

@@ -0,0 +1,11 @@
+Feature: Doctor
+
+  Background:
+    Given a test app with the default configuration
+
+  Scenario: Running the doctor task
+    When I run cap "doctor"
+    Then the task is successful
+    And contains "Environment" in the output
+    And contains "Gems" in the output
+    And contains "Variables" in the output

data/features/installation.feature

@@ -1,16 +1,21 @@
 Feature: Installation
 
   Background:
-    Given a test app with the default configuration
+    Given a test app without any configuration
+
+  Scenario: The "install" task documentation can be viewed
+    When I run "cap -T"
+    Then the task is successful
+    And contains "cap install" in the output
 
   Scenario: With default stages
-    When I run cap "install"
+    When I run "cap install"
     Then the deploy.rb file is created
     And the default stage files are created
     And the tasks folder is created
 
   Scenario: With specified stages
-    When I run cap "install STAGES=qa,production"
+    When I run "cap install STAGES=qa,production"
     Then the deploy.rb file is created
     And the specified stage files are created
     And the tasks folder is created

data/features/stage_failure.feature

@@ -0,0 +1,9 @@
+Feature: Stage failure
+
+  Background:
+    Given a test app with the default configuration
+    And a stage file named deploy.rb
+
+  Scenario: Running a task
+    When I run cap "doctor"
+    Then the task fails

data/features/step_definitions/assertions.rb

@@ -1,5 +1,14 @@
+require "shellwords"
+
 Then(/^references in the remote repo are listed$/) do
-  expect(@output).to include('refs/heads/master')
+  expect(@output).to include("refs/heads/master")
+end
+
+Then(/^git wrapper permissions are 0700$/) do
+  permissions_test = %Q([ $(stat -c "%a" #{TestApp.git_wrapper_path_glob}) == "700" ])
+  _stdout, _stderr, status = vagrant_cli_command("ssh -c #{permissions_test.shellescape}")
+
+  expect(status).to be_success
 end
 
 Then(/^the shared path is created$/) do
@@ -10,6 +19,18 @@ Then(/^the releases path is created$/) do
   run_vagrant_command(test_dir_exists(TestApp.releases_path))
 end
 
+Then(/^(\d+) valid releases are kept/) do |num|
+  test = %Q([ $(ls -g #{TestApp.releases_path} | grep -E '[0-9]{14}' | wc -l) == "#{num}" ])
+  _, _, status = vagrant_cli_command("ssh -c #{test.shellescape}")
+  expect(status).to be_success
+end
+
+Then(/^the invalid (.+) release is ignored$/) do |filename|
+  test = "ls -g #{TestApp.releases_path} | grep #{filename}"
+  _, _, status = vagrant_cli_command("ssh -c #{test.shellescape}")
+  expect(status).to be_success
+end
+
 Then(/^directories in :linked_dirs are created in shared$/) do
   TestApp.linked_dirs.each do |dir|
     run_vagrant_command(test_dir_exists(TestApp.shared_path.join(dir)))
@@ -18,7 +39,7 @@ end
 
 Then(/^directories referenced in :linked_files are created in shared$/) do
   dirs = TestApp.linked_files.map { |path| TestApp.shared_path.join(path).dirname }
-  dirs.each do | dir|
+  dirs.each do |dir|
     run_vagrant_command(test_dir_exists(dir))
   end
 end
@@ -45,31 +66,31 @@ Then(/^directory symlinks are created in the new release$/) do
 end
 
 Then(/^the current directory will be a symlink to the release$/) do
-  run_vagrant_command(test_symlink_exists(TestApp.current_path))
+  run_vagrant_command(exists?("e", TestApp.current_path))
 end
 
 Then(/^the deploy\.rb file is created$/) do
-  file = TestApp.test_app_path.join('config/deploy.rb')
-  expect(File.exists?(file)).to be true
+  file = TestApp.test_app_path.join("config/deploy.rb")
+  expect(File.exist?(file)).to be true
 end
 
 Then(/^the default stage files are created$/) do
-  staging = TestApp.test_app_path.join('config/deploy/staging.rb')
-  production = TestApp.test_app_path.join('config/deploy/production.rb')
-  expect(File.exists?(staging)).to be true
-  expect(File.exists?(production)).to be true
+  staging = TestApp.test_app_path.join("config/deploy/staging.rb")
+  production = TestApp.test_app_path.join("config/deploy/production.rb")
+  expect(File.exist?(staging)).to be true
+  expect(File.exist?(production)).to be true
 end
 
 Then(/^the tasks folder is created$/) do
-  path = TestApp.test_app_path.join('lib/capistrano/tasks')
-  expect(Dir.exists?(path)).to be true
+  path = TestApp.test_app_path.join("lib/capistrano/tasks")
+  expect(Dir.exist?(path)).to be true
 end
 
 Then(/^the specified stage files are created$/) do
-  qa = TestApp.test_app_path.join('config/deploy/qa.rb')
-  production = TestApp.test_app_path.join('config/deploy/production.rb')
-  expect(File.exists?(qa)).to be true
-  expect(File.exists?(production)).to be true
+  qa = TestApp.test_app_path.join("config/deploy/qa.rb")
+  production = TestApp.test_app_path.join("config/deploy/production.rb")
+  expect(File.exist?(qa)).to be true
+  expect(File.exist?(production)).to be true
 end
 
 Then(/^it creates the file with the remote_task prerequisite$/) do
@@ -91,18 +112,18 @@ Then(/^the task fails$/) do
 end
 
 Then(/^the failure task will run$/) do
-  failed = TestApp.shared_path.join('failed')
+  failed = TestApp.shared_path.join("failed")
   run_vagrant_command(test_file_exists(failed))
 end
 
 Then(/^the failure task will not run$/) do
-  failed = TestApp.shared_path.join('failed')
+  failed = TestApp.shared_path.join("failed")
   expect { run_vagrant_command(test_file_exists(failed)) }
     .to raise_error(VagrantHelpers::VagrantSSHCommandError)
 end
 
 When(/^an error is raised$/) do
-  error = TestApp.shared_path.join('fail')
+  error = TestApp.shared_path.join("fail")
   run_vagrant_command(test_file_exists(error))
 end
 
@@ -117,3 +138,15 @@ end
 Then(/doesn't contain "([^"]*)" in the output/) do |expected|
   expect(@output).not_to include(expected)
 end
+
+Then(/the current symlink points to the previous release/) do
+  previous_release_path = @release_paths[-2]
+
+  run_vagrant_command(symlinked?(TestApp.current_path, previous_release_path))
+end
+
+Then(/^the current symlink points to that specific release$/) do
+  specific_release_path = TestApp.releases_path.join(@rollback_release)
+
+  run_vagrant_command(symlinked?(TestApp.current_path, specific_release_path))
+end

data/features/step_definitions/cap_commands.rb

@@ -2,6 +2,10 @@ When(/^I run cap "(.*?)"$/) do |task|
   @success, @output = TestApp.cap(task)
 end
 
+When(/^I run cap "(.*?)" within the "(.*?)" directory$/) do |task, directory|
+  @success, @output = TestApp.cap(task, directory)
+end
+
 When(/^I run cap "(.*?)" as part of a release$/) do |task|
   TestApp.cap("deploy:new_release_path #{task}")
 end
@@ -10,3 +14,8 @@ When(/^I run "(.*?)"$/) do |command|
   @success, @output = TestApp.run(command)
 end
 
+When(/^I rollback to a specific release$/) do
+  @rollback_release = @release_paths.first.split("/").last
+
+  step %Q{I run cap "deploy:rollback ROLLBACK_RELEASE=#{@rollback_release}"}
+end

data/features/step_definitions/setup.rb

@@ -2,8 +2,16 @@ Given(/^a test app with the default configuration$/) do
   TestApp.install
 end
 
+Given(/^a test app without any configuration$/) do
+  TestApp.create_test_app
+end
+
 Given(/^servers with the roles app and web$/) do
-  vagrant_cli_command('up') rescue nil
+  begin
+    vagrant_cli_command("up")
+  rescue
+    nil
+  end
 end
 
 Given(/^a linked file "(.*?)"$/) do |file|
@@ -13,10 +21,16 @@ end
 
 Given(/^file "(.*?)" exists in shared path$/) do |file|
   file_shared_path = TestApp.shared_path.join(file)
-  run_vagrant_command("mkdir -p #{TestApp.shared_path}")
+  run_vagrant_command("mkdir -p #{file_shared_path.dirname}")
   run_vagrant_command("touch #{file_shared_path}")
 end
 
+Given(/^all linked files exists in shared path$/) do
+  TestApp.linked_files.each do |linked_file|
+    step %Q{file "#{linked_file}" exists in shared path}
+  end
+end
+
 Given(/^file "(.*?)" does not exist in shared path$/) do |file|
   file_shared_path = TestApp.shared_path.join(file)
   run_vagrant_command("mkdir -p #{TestApp.shared_path}")
@@ -24,11 +38,11 @@ Given(/^file "(.*?)" does not exist in shared path$/) do |file|
 end
 
 Given(/^a custom task to generate a file$/) do
-  TestApp.copy_task_to_test_app('spec/support/tasks/database.rake')
+  TestApp.copy_task_to_test_app("spec/support/tasks/database.rake")
 end
 
 Given(/^a task which executes as root$/) do
-  TestApp.copy_task_to_test_app('spec/support/tasks/root.rake')
+  TestApp.copy_task_to_test_app("spec/support/tasks/root.rake")
 end
 
 Given(/config stage file has line "(.*?)"/) do |line|
@@ -36,15 +50,45 @@ Given(/config stage file has line "(.*?)"/) do |line|
 end
 
 Given(/^the configuration is in a custom location$/) do
-  TestApp.move_configuration_to_custom_location('app')
+  TestApp.move_configuration_to_custom_location("app")
 end
 
 Given(/^a custom task that will simulate a failure$/) do
-  safely_remove_file(TestApp.shared_path.join('failed'))
-  TestApp.copy_task_to_test_app('spec/support/tasks/fail.rake')
+  safely_remove_file(TestApp.shared_path.join("failed"))
+  TestApp.copy_task_to_test_app("spec/support/tasks/fail.rake")
 end
 
 Given(/^a custom task to run in the event of a failure$/) do
-  safely_remove_file(TestApp.shared_path.join('failed'))
-  TestApp.copy_task_to_test_app('spec/support/tasks/failed.rake')
+  safely_remove_file(TestApp.shared_path.join("failed"))
+  TestApp.copy_task_to_test_app("spec/support/tasks/failed.rake")
+end
+
+Given(/^a stage file named (.+)$/) do |filename|
+  TestApp.write_local_stage_file(filename)
+end
+
+Given(/^I make (\d+) deployments$/) do |count|
+  step "all linked files exists in shared path"
+
+  @release_paths = (1..count.to_i).map do
+    TestApp.cap("deploy")
+    stdout, _stderr = run_vagrant_command("readlink #{TestApp.current_path}")
+
+    stdout.strip
+  end
+end
+
+Given(/^(\d+) valid existing releases$/) do |num|
+  a_day = 86_400 # in seconds
+  (1...num).each_slice(100) do |num_batch|
+    dirs = num_batch.map do |i|
+      offset = -(a_day * i)
+      TestApp.release_path(TestApp.timestamp(offset))
+    end
+    run_vagrant_command("mkdir -p #{dirs.join(' ')}")
+  end
+end
+
+Given(/^an invalid release named "(.+)"$/) do |filename|
+  run_vagrant_command("mkdir -p #{TestApp.release_path(filename)}")
 end

data/features/subdirectory.feature

@@ -0,0 +1,9 @@
+Feature: cap can be run from a subdirectory, and will still find the Capfile
+
+  Background:
+    Given a test app with the default configuration
+    And servers with the roles app and web
+
+  Scenario: Running cap from a subdirectory
+    When I run cap "git:check" within the "config" directory
+    Then the task is successful

data/features/support/env.rb

@@ -1,11 +1,11 @@
-PROJECT_ROOT = File.expand_path('../../../', __FILE__)
-VAGRANT_ROOT = File.join(PROJECT_ROOT, 'spec/support')
-VAGRANT_BIN = ENV['VAGRANT_BIN'] || "vagrant"
+PROJECT_ROOT = File.expand_path("../../../", __FILE__)
+VAGRANT_ROOT = File.join(PROJECT_ROOT, "spec/support")
+VAGRANT_BIN = ENV["VAGRANT_BIN"] || "vagrant"
 
 at_exit do
-  if ENV['KEEP_RUNNING']
+  if ENV["KEEP_RUNNING"]
     VagrantHelpers.run_vagrant_command("rm -rf /home/vagrant/var")
   end
 end
 
-require_relative '../../spec/support/test_app'
+require_relative "../../spec/support/test_app"

data/features/support/remote_command_helpers.rb

@@ -1,22 +1,28 @@
 module RemoteCommandHelpers
   def test_dir_exists(path)
-    exists?('d', path)
+    exists?("d", path)
   end
 
   def test_symlink_exists(path)
-    exists?('L', path)
+    exists?("L", path)
   end
 
   def test_file_exists(path)
-    exists?('f', path)
+    exists?("f", path)
   end
 
   def exists?(type, path)
-    %{[ -#{type} "#{path}" ]}
+    %Q{[ -#{type} "#{path}" ]}
   end
 
-  def safely_remove_file(path)
-    run_vagrant_command("rm #{test_file}") rescue VagrantHelpers::VagrantSSHCommandError
+  def symlinked?(symlink_path, target_path)
+    "[ #{symlink_path} -ef #{target_path} ]"
+  end
+
+  def safely_remove_file(_path)
+    run_vagrant_command("rm #{test_file}")
+  rescue
+    VagrantHelpers::VagrantSSHCommandError
   end
 end
 

data/features/support/vagrant_helpers.rb

@@ -1,10 +1,12 @@
+require "open3"
+
 module VagrantHelpers
   extend self
 
   class VagrantSSHCommandError < RuntimeError; end
 
   at_exit do
-    if ENV['KEEP_RUNNING']
+    if ENV["KEEP_RUNNING"]
       puts "Vagrant vm will be left up because KEEP_RUNNING is set."
       puts "Rerun without KEEP_RUNNING set to cleanup the vm."
     else
@@ -14,22 +16,26 @@ module VagrantHelpers
 
   def vagrant_cli_command(command)
     puts "[vagrant] #{command}"
-    Dir.chdir(VAGRANT_ROOT) do
-      `#{VAGRANT_BIN} #{command} 2>&1`.split("\n").each do |line|
-        puts "[vagrant] #{line}"
-      end
+    stdout, stderr, status = Dir.chdir(VAGRANT_ROOT) do
+      Open3.capture3("#{VAGRANT_BIN} #{command}")
     end
-    $?
+
+    (stdout + stderr).each_line { |line| puts "[vagrant] #{line}" }
+
+    [stdout, stderr, status]
   end
 
   def run_vagrant_command(command)
-    if (status = vagrant_cli_command("ssh -c #{command.inspect}")).success?
-      true
-    else
-      fail VagrantSSHCommandError, status
-    end
+    stdout, stderr, status = vagrant_cli_command("ssh -c #{command.inspect}")
+    return [stdout, stderr] if status.success?
+    raise VagrantSSHCommandError, status
   end
 
+  def puts(message)
+    # Attach log messages to the current cucumber feature (`log`),
+    # or simply puts to the console (`super`) if we are outside of cucumber.
+    respond_to?(:log) ? log(message) : super(message)
+  end
 end
 
 World(VagrantHelpers)

data/lib/Capfile

@@ -1,3 +1,3 @@
 #!/usr/bin/env cap
 include Capistrano::DSL
-require 'capistrano/install'
+require "capistrano/install"

data/lib/capistrano/all.rb

@@ -1,17 +1,17 @@
-require 'rake'
-require 'sshkit'
+require "rake"
+require "sshkit"
 
-require 'io/console'
+require "io/console"
 
 Rake.application.options.trace = true
 
-require 'capistrano/version'
-require 'capistrano/version_validator'
-require 'capistrano/i18n'
-require 'capistrano/dsl'
-require 'capistrano/application'
-require 'capistrano/configuration'
+require "capistrano/version"
+require "capistrano/version_validator"
+require "capistrano/i18n"
+require "capistrano/dsl"
+require "capistrano/application"
+require "capistrano/configuration"
+require "capistrano/configuration/scm_resolver"
 
 module Capistrano
-
 end