capistrano-deploytags 0.9.2 → 1.0.0

data/README.md

@@ -1,13 +1,20 @@
-Capistrano Deployment Tags
-==========================
-This plugin to Capistrano will add a timestamped Git tag
-at each deployment, automatically.  It is intended to be used with
-the multistage recipe and will tag each release by environment.
-You can, however, use it without multistage simply by setting :branch
-and :stage in your recipe.
-
-What It Does
-------------
+[![Gem Version](https://badge.fury.io/rb/capistrano-deploytags.svg)](http://badge.fury.io/rb/capistrano-deploytags)
+
+## Capistrano Deployment Tags
+
+This plugin for Capistrano 3 will add a timestamped Git tag
+at each deployment, automatically. It requires :branch and :stage to be set,
+but as Capistrano 3 is multistage by default (unlike Cap 2) :stage should
+already be set, but you can override the variable if you want to change the
+name of the tag.
+
+### Requires Capistrano 3
+
+As of version 1.0.0, this plugin requires Cap 3. If you need a Capistrano
+2 compatible version, then use `gem 'capistrano-deploytags', '~> 0.9.2'`
+
+### What It Does
+
 Simply: it makes it so you can track your deployments from Git.
 If I were to issue the command:
 
@@ -23,21 +30,29 @@ generating statistics about deployments per day/week/year, tracking
 code size over a period of time, detecting Rails migrations, and
 probably a thousand other things I haven't thought of.
 
-Usage
------
+### Usage
+
 capistrano-deploytags is available on
 [rubygems.org](https://rubygems.org/gems/capistrano-deploytags).
-You can install it from there with:
+In keeping with the pattern used by Capistrano itself and other plugins, add it
+to the `development` group of your Gemfile with `require: false`:
 
-`gem install capistrano-deploytags`
+```ruby
+# Gemfile
+group :deployment do
+  gem 'capistrano-deploytags', '~> 1.0.0', require: false
+end
+```
 
-If you use Bundler, be sure to add the gem to your Gemfile.
-In your Capistrano `config/deploy.rb` you should add:
+Then require `capistrano/deploytags` in your Capfile
 
-`require 'capistrano-deploytags'`
+```
+# Capfile
+require 'capistrano/deploytags'
+```
 
-This will create two tasks, one that runs before deployment and one
-that runs after.
+This will create two tasks, one that runs before the `deploy` task, and one
+that runs after the `cleanup` task.
 
 *NOTE:* You will be creating and pushing tags from the version of the code in the
 current checkout. This plugin needs to be run from a clean checkout of your
@@ -50,15 +65,14 @@ system that will actually be deployed before checking the tree for changes.
 Know this ahead of time as this may affect how you deal with your deployment
 branches.
 
-Setting the Remote
-------------------
-By default, Capistrano Deploytags will use the first remote in the list returned
-by `git remote`. If you prefer to use a different remote, then you may change the
-`:git_remote` setting from your `deploy.rb`, the stage, or on the command line with
-`-S git_remote=your-remote`.
+### Setting the Remote
+
+By default, Capistrano Deploytags will use the remote names `origin`. If you
+use a different remote name, then you may change the `:git_remote` setting
+from your `deploy.rb` or the stage.
+
+### Working on Your Deployment Scripts
 
-Working on Your Deployment Scripts
-----------------------------------
 Because you must have a clean tree to deploy, working on your deployment
 scripts themselves can be a bit frustrating unless you know how to make it
 work. The easiest way around this problem is to simply commit your changes
@@ -68,8 +82,8 @@ happily carry on deploying without complaint.
 Alternatively, you could disable the plugin temporarily with one of the
 methods described below.
 
-Disabling Tagging for a Stage
------------------------------
+### Disabling Tagging for a Stage
+
 Sometimes you do not want to enable deployment tagging for a particular
 stage. In that event, you can simply disable tagging by setting `no_deploytags`
 like so:
@@ -78,7 +92,8 @@ like so:
 set :no_deploytags, true
 ```
 
-You can also set this from the command line at any time with `-S no_deploytags=true`.
+You can also set this from the command line at any time with an environment
+variable `cap stage deploy NO_DEPLOYTAGS=true`.
 
 *NOTE:* this will disable the use of the plugin's functionality entirely for
 that stage. The tasks will run, but will do nothing. This means that tasks that
@@ -86,24 +101,24 @@ are hooked to the Capistrano Deploytags tasks will also still run, but they may
 find their expectations are not met with regards to the cleanliness of the git
 tree.
 
-Customizing the Tag Format
---------------------------
-You may override the time format in `config/deploy.rb`:
+### Customizing the Tag Format
+
+You may override the time format in `deploy.rb` or your stage:
 
 ```ruby
 set :deploytag_time_format, "%Y.%m.%d-%H%M%S-utc"
 ```
 
-Customizing the Tag Commit Message
-----------------------------------
+### Customizing the Tag Commit Message
+
 By default, Capistrano Deploytags will create a tag with a message that indicates
 the local user name on the box where the deployment is done, and the hash of the
 tagged commit. If you prefer to have a more detailed commit message you may override
-the `:deploytag_commit_message` setting from your `deploy.rb` or on the command line
-with `-S deploytag_commit_message='This is my commit message for the deployed tag'`.
+the `:deploytag_commit_message` setting from your `deploy.rb`, e.g. 
+`set :deploytag_commit_message, 'This is my commit message for the deployed tag'`
+
+### Viewing Deployment History
 
-Viewing Deployment History
---------------------------
 It's trivial to view the deployment history for a repo. From a checkout
 of the repo, type `git tag -l -n1`. The output looks something like:
 
@@ -112,7 +127,7 @@ dev-2013.07.22-105130 baz deployed a4d522d9d to dev
 dev-2013.07.22-113207 karl deployed 4c43f8464 to dev
 dev-2013.07.22-114437 gavin deployed 776e15414 to dev
 dev-2013.07.22-115103 karl deployed 619ff5724 to dev
-dev-2013.07.22-144121 joshmyers deployed cf1ed1a02 to dev
+dev-2013.07.22-144121 josh deployed cf1ed1a02 to dev
 ```
 A little use of `grep` and you can easily get the history for a
 particular (e.g. `git tag -l -n1 | grep dev`).
@@ -120,8 +135,8 @@ particular (e.g. `git tag -l -n1 | grep dev`).
 It should be noted that the names used when tags are created are the
 local user name on the box where the deployment is done.
 
-Helpful Git Config
-------------------
+### Helpful Git Config
+
 You might find it useful to add this to your ~/.gitconfig in order
 to get a nice history view of the commits and tags.
 
@@ -133,29 +148,43 @@ to get a nice history view of the commits and tags.
 You can then view the list by typing `git lol` from the checked out
 code path.
 
-Deploying a Previous Commit
----------------------------
+### Deploying a Previous Commit
+
 Because you have to actually be on the head of the branch you are
 deploying in order for tagging to work properly, deploying a previous
-commit doesn't work as you might expect. The simple solution is to
-create a new branch from the previous commit you wish to deploy and
-supplying `-S branch=<new branch>` as arguments to Capistrano.
+commit doesn't work as you might expect.
+
+One simple solution is to configure your `config.rb` to accept an ENV var
+override. Then if you need to deploy a previous commit you can check out that
+commit (SHA or branch), and supply the var on the command line. e.g. with this
+in your `config.rb`:
+
+```ruby
+set :branch,      ENV["REVISION"] || ENV["BRANCH_NAME"] || "master"
+```
+
+you can deploy a previous commit with
+
+```shell
+git checkout <previous-commit>
+cap <stage> deploy REVISION=<previous-commit>
+```
+
+### Running from Jenkins
 
-Running from Jenkins
---------------------
 Because Jenkins will check out the code with the current revision
 number you will be in a detached state. This causes the plugin to be
 unhappy about the git tree. The solution is to add `-S branch=$GIT_COMMIT`
 to the cap deploy line called from your Jenkins build. This will cause
 the diffs and comparisons done by the deploytags gem to be correct.
 
-Credits
--------
+### Credits
+
 This software was written by [Karl Matthias](https://github.com/relistan)
 with help from [Gavin Heavyside](https://github.com/gavinheavyside) and the
 support of [MyDrive Solutions Limited](http://mydrivesolutions.com).
 
-License
--------
+### License
+
 This plugin is released under the BSD two clause license which is
 available in both the Ruby Gem and the source repository.

data/lib/capistrano-deploytags.rb

@@ -1,3 +0,0 @@
-Dir[File.join(File.dirname(__FILE__), 'capistrano', '*')].each do |file|
-  require file
-end

data/lib/capistrano/deploytags.rb

@@ -0,0 +1,26 @@
+# Ensure deploy tasks are loaded before we run
+require 'capistrano/deploy'
+
+# Load extra tasks into the deploy namespace
+load File.expand_path("../tasks/deploytags.rake", __FILE__)
+
+module CapistranoDeploytags
+  class Helper
+    def self.git_tag_for(stage)
+      "#{stage}-#{formatted_time}"
+    end
+
+    def self.formatted_time
+      Time.new.utc.strftime(fetch(:deploytag_time_format, "%Y.%m.%d-%H%M%S-utc"))
+    end
+
+    def self.commit_message(current_sha, stage)
+      if fetch(:deploytag_commit_message, false)
+        deploytag_commit_message
+      else
+        tag_user = (ENV['USER'] || ENV['USERNAME'] || 'deployer').strip
+        "#{tag_user} deployed #{current_sha} to #{stage}"
+      end
+    end
+  end
+end

data/lib/capistrano/tasks/deploytags.rake

@@ -0,0 +1,49 @@
+namespace :deploy do
+  desc 'prepare git tree so we can tag on successful deployment'
+  before :deploy, :prepare_tree do
+    run_locally do
+      if ENV['NO_DEPLOYTAGS'] || fetch(:no_deploytags, false)
+        info "[deploytags] Skipping deploytags"
+      else
+        branch = fetch(:branch, false)
+        stage = fetch(:stage, false)
+
+        unless branch && stage
+          error 'capistrano-deploytags requires that :branch and :stage be defined'
+          raise 'define :branch and :stage'
+        end
+
+        strategy.git "fetch #{fetch(:git_remote, 'origin')}"
+
+        diff_output = capture :git, "diff #{branch} --shortstat"
+
+        unless diff_output.empty?
+          error "Whoa there, partner. Dirty trees can't deploy. Git yerself clean first"
+          raise 'Dirty git tree'
+        end
+
+        strategy.git "checkout #{branch}"
+        info "Pulling from #{branch}"
+        strategy.git "pull #{fetch(:git_remote, 'origin')} #{branch}"
+      end
+    end
+  end
+
+  desc 'add git tags for each successful deployment'
+  after :cleanup, :tagdeploy do
+    run_locally do
+      if ENV['NO_DEPLOYTAGS'] || fetch(:no_deploytags, false)
+        info "[deploytags] Skipping deploytags"
+      else
+        tag_name = CapistranoDeploytags::Helper.git_tag_for(fetch(:stage))
+        latest_revision = fetch(:current_revision)
+        commit_message = CapistranoDeploytags::Helper.commit_message(latest_revision, fetch(:stage))
+
+        strategy.git "tag -a #{tag_name} -m \"#{commit_message}\" #{latest_revision}"
+        strategy.git "push #{fetch(:git_remote, 'origin')} #{tag_name}"
+
+        info "[cap-deploy-tagger] Tagged #{latest_revision} with #{tag_name}"
+      end
+    end
+  end
+end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-deploytags
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
 - Karl Matthias
+- Gavin Heavyside
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-01 00:00:00.000000000 Z
+date: 2014-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano
@@ -18,7 +19,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,16 +27,16 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
-  name: capistrano-ext
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
@@ -43,21 +44,40 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! '  Capistrano Deploytags is a simple plugin to Capistrano that works
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+description: ! '  Capistrano Deploytags is a simple plugin to Capistrano 3 that works
   with your deployment framework to track your code releases. All you have to do is
-  require capistrano-deploytags and each deployment will add a new tag for that deployment,
-  pointing to the latest commit. This lets you easily see which code is deployed on
-  each environment, and allows you to figure out which code was running in an environment
-  at any time in the past.
+  require capistrano-deploytags/capistrano and each deployment will add a new tag
+  for that deployment, pointing to the latest commit. This lets you easily see which
+  code is deployed on each environment, and allows you to figure out which code was
+  running in an environment at any time in the past.
 
 '
-email: relistan@gmail.com
+email:
+- relistan@gmail.com
+- gavin.heavyside@mydrivesolutions.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/capistrano-deploytags.rb
-- lib/capistrano/deploy_tags.rb
+- lib/capistrano/deploytags.rb
+- lib/capistrano/tasks/deploytags.rake
 - README.md
 - LICENSE
 homepage: http://github.com/mydrive/capistrano-deploytags

data/lib/capistrano/deploy_tags.rb

@@ -1,104 +0,0 @@
-module Capistrano
-  module DeployTags
-    def pending_git_changes?
-      # Do we have any changes vs HEAD on deployment branch?
-      `git fetch #{remote}`.tap do |output|
-        return !(`git diff #{branch} --shortstat`.strip.empty?) if exec_success?
-        raise "'git fetch #{remote}' failed:\n #{output}"
-      end
-    end
-
-    def git_tag_for(stage)
-      "#{stage}-#{formatted_time}"
-    end
-
-    def formatted_time
-      Time.new.utc.strftime(fetch(:deploytag_time_format, "%Y.%m.%d-%H%M%S-utc"))
-    end
-
-    def safe_run(*args)
-      raise "#{args.join(" ")} failed!" unless system(*args)
-    end
-
-    def exec_success?
-      $?.success?
-    end
-
-    def validate_git_vars
-      unless exists?(:branch) && exists?(:stage)
-        logger.log Capistrano::Logger::IMPORTANT, 'Capistrano Deploytags requires that :branch and :stage be defined.'
-        raise 'define :branch and :stage'
-      end
-    end
-
-    def git_tag?(tag)
-      !`git tag -l #{tag}`.strip.empty?
-    end
-
-    def has_remote?
-      !`git remote`.strip.empty?
-    end
-
-    def remote
-      exists?(:git_remote) ? git_remote : `git remote`.strip.split(/\n/).first
-    end
-
-    def commit_message(current_sha)
-      if exists?(:deploytag_commit_message)
-        deploytag_commit_message
-      else
-        tag_user = (ENV['USER'] || ENV['USERNAME'] || 'deployer').strip
-        "#{tag_user} deployed #{current_sha} to #{stage}"
-      end
-    end
-
-    def self.load_into(configuration)
-      configuration.load do
-        before 'deploy', 'git:prepare_tree'
-        before 'deploy:migrations', 'git:prepare_tree'
-        after  'deploy', 'git:tagdeploy'
-        after  'deploy:migrations', 'git:tagdeploy'
-
-        desc 'prepare git tree so we can tag on successful deployment'
-        namespace :git do
-          task :prepare_tree, :except => { :no_release => true } do
-            next if fetch(:no_deploytags, false)
-
-            cdt.validate_git_vars
-
-            logger.log Capistrano::Logger::IMPORTANT, "Preparing to deploy HEAD from branch '#{branch}' to '#{stage}'"
-
-            if cdt.pending_git_changes?
-              logger.log Capistrano::Logger::IMPORTANT, "Whoa there, partner. Dirty trees can't deploy. Git yerself clean first."
-              raise 'Dirty git tree'
-            end
-
-            cdt.safe_run 'git', 'checkout', branch
-            logger.log Capistrano::Logger::IMPORTANT, "Pulling from #{branch}"
-            cdt.safe_run 'git', 'pull', cdt.remote, branch if cdt.has_remote?
-          end
-
-          desc 'add git tags for each successful deployment'
-          task :tagdeploy, :except => { :no_release => true } do
-            next if fetch(:no_deploytags, false)
-
-            cdt.validate_git_vars
-
-            current_sha = `git rev-parse #{branch} HEAD`.strip[0..8]
-            logger.log Capistrano::Logger::INFO, "Tagging #{current_sha} for deployment"
-
-            cdt.safe_run 'git', 'tag', '-a', cdt.git_tag_for(stage), '-m', cdt.commit_message(current_sha)
-            cdt.safe_run 'git', 'push', '--tags' if cdt.has_remote?
-          end
-        end
-
-      end
-    end
-  end
-end
-
-Capistrano.plugin :cdt, Capistrano::DeployTags
-
-if Capistrano::Configuration.instance
-  Capistrano::DeployTags.load_into(Capistrano::Configuration.instance(:must_exist))
-end