capnotify 0.1.6pre → 0.2.0

data/README.md

@@ -24,7 +24,7 @@ is made.
 
 Add this line to your application's Gemfile:
 
-    gem 'capnotify'
+    gem "capnotify", "~> 0.1.6pre"
 
 And then execute:
 
@@ -32,7 +32,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install capnotify
+    $ gem install capnotify --pre
 
 Then, in your `Capfile`, add the following line:
 
@@ -354,9 +354,14 @@ also
  * getting component by name
  * lazy components
 
+This should probably be in the wiki rather than the readme.
+
 ## Extensions
 
-Need to write this.
+It's possible to write extensions for Capnotify. Typically, these will be used to add new
+components to long messages.
+
+Need to write this. This will probably wind up in the wiki instead of here.
 
 ## Contributing
 

data/capnotify.gemspec

@@ -24,5 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"
   spec.add_development_dependency "awesome_print"
 
-  spec.add_dependency "capistrano", "~> 2.14.2"
+  spec.add_dependency "capistrano", "~> 2.14"
 end

data/lib/capnotify.rb

@@ -2,6 +2,7 @@ require 'capistrano'
 require "capnotify/version"
 require 'capnotify/component'
 require 'capnotify/plugin'
+require 'capnotify/plugin/message'
 require 'capnotify/plugin/overview'
 require 'capnotify/plugin/details'
 
@@ -10,20 +11,27 @@ module Capnotify
     config.load do
       Capistrano.plugin :capnotify, ::Capnotify::Plugin
 
+      # conditionally set a capistrano var if it hasn't been set, yet.
+      # this functin was ganked from the built-in capistrano deploy recipe
+      # since we can't count on this function being defined, we redefine here.
       def _cset(name, *args, &block)
         unless exists?(name)
           set(name, *args, &block)
         end
       end
 
-
       # some configuration
+      # The paths to the built-in templates
+      # Set these in your deployment recipes if you want a custom template
+      # These paths are used when building the deployment notification emails
       _cset :capnotify_deployment_notification_html_template_path, capnotify.built_in_template_for('default_notification.html.erb')
       _cset :capnotify_deployment_notification_text_template_path, capnotify.built_in_template_for('default_notification.txt.erb')
 
       # get the name of the user deploying
       # if using git, this will read that from your git config
       # otherwise will use the currently logged-in user's name
+      # TODO: Support SCM other than git.
+      # TODO: Support a method other than `whoami` for getting the user's name
       _cset(:deployer_username) do
         if exists?(:scm) && fetch(:scm).to_sym == :git
           `git config user.name`.chomp
@@ -33,13 +41,17 @@ module Capnotify
       end
 
       # built-in values:
+
+      # This is the list of components to use for the notification
       set :capnotify_component_list, []
 
+      # The name of the application. Used in pretty much every built-in message
+      # by default, the output should be: "STAGE APPNAME @ BRANCH"
       # override this to change the default behavior for capnotify.appname
       _cset(:capnotify_appname) do
-        name = [ fetch(:application, nil), fetch(:stage, nil) ].compact.join(" ")
+        name = [ fetch(:stage, nil), fetch(:application, nil) ].compact.map{|c| c.capitalize}.join(" ")
         if fetch(:branch, nil)
-          name = "#{ name } / #{ branch }"
+          name = "#{ name } @ #{ branch }"
         end
         name
       end
@@ -78,11 +90,13 @@ module Capnotify
       end
 
       # full email message to notify of deployment (html)
+      # when called, will compile the template and return the complete data as a string
       _cset(:capnotify_deployment_notification_html) do
         capnotify.build_template( fetch(:capnotify_deployment_notification_html_template_path) )
       end
 
       # full email message to notify of deployment (plain text)
+      # when called, will compile the template and return the complete data as a string
       _cset(:capnotify_deployment_notification_text) do
         data = capnotify.build_template( fetch(:capnotify_deployment_notification_text_template_path) )
 
@@ -91,15 +105,20 @@ module Capnotify
       end
 
       # before update_code, fetch the current revision
-      # this is needed to ensure that no matter when capnotify fetches the commit logs,
+      # this is needed to ensure that no matter when capnotify is run, it will have the correct previous (currently deployed) revision
       # it will have the correct starting point.
       before 'deploy:update_code' do
         set :capnotify_previous_revision, fetch(:current_revision, nil) # the revision that's currently deployed at this moment
       end
 
-      # configure the callbacks
 
       on(:load) do
+        # register the callbacks
+        # These callbacks can be disabled by setting the following variables to a truthy value:
+        #  * capnotify_disable_deploy_hooks
+        #  * capnotify_disable_migrate_hooks
+        #  * capnotify_disable_maintenance_hooks
+
         # deploy start/complete
         unless fetch(:capnotify_disable_deploy_hooks, false)
           before('deploy') { trigger :deploy_start }
@@ -118,12 +137,15 @@ module Capnotify
           after('deploy:web:enable')  { trigger :maintenance_page_down }
         end
 
+        # load the default plugins
+        # disable loading them by setting capnotify_disable_default_components to a truthy value
         unless fetch(:capnotify_disable_default_components, false)
-          capnotify.load_plugin :capnotify_overview, Capnotify::Plugin::Overview
-          capnotify.load_plugin :capnotify_details, Capnotify::Plugin::Details
+          capnotify.load_default_plugins
         end
 
-        capnotify.print_splash
+        # prints out a splash screen if capnotify_show_splash is set to true
+        # defaults to being silent.
+        capnotify.print_splash if fetch(:capnotify_show_splash, false)
       end
 
     end

data/lib/capnotify/component.rb

@@ -45,6 +45,10 @@ module Capnotify
       @content
     end
 
+    # FIXME: this should probably leverage Procs for rendering of different types, maybe?
+    #        that would give a lot of power to a developer who wants a custom format for a plugin (eg XML or JSON)
+    # Render the content in the given format using the right built-in template. Returns the content as a string.
+    # In the event that there is not a valid template, return an empty string.
     def render_content(format)
       begin
         ERB.new( File.open( template_path_for(format) ).read, nil, '%<>' ).result(self.get_binding)

data/lib/capnotify/plugin.rb

@@ -4,9 +4,10 @@ require 'pry'
 module Capnotify
   module Plugin
 
+    # output a pretty splash screen of the Capnotify logo
+    # this can be enabled by setting capnotify_show_splash to a truthy value:
+    #  set :capnotify_show_splash, true
     def print_splash
-      return if fetch(:capnotify_hide_splash, false)
-
       puts <<-SPLASH
            __________________
       - --|\\   Deployment   /|    _____                    __  _ ___
@@ -21,16 +22,52 @@ module Capnotify
     # convenience method for getting the friendly app name
     # If the stage is specified (the deployment is using multistage), include that.
     # given that the application is "MyApp" and the stage is "production", this will return "MyApp production"
+    # if capnotify_appname is not set, it'll return an empty string
     def appname
       fetch(:capnotify_appname, "")
     end
 
-    def load_plugin(name, mod)
-      Capistrano.plugin name, mod
+    # get the name of the deploying user
+    # currently this only supports git.
+    # if reading the git user.name, fall back on `whoami`
+    def deployed_by
+      username = nil
+
+      scm = fetch(:scm, nil)
+
+      if scm
+        if scm.to_sym == :git
+          username = `git config user.name`.chomp
+          username = nil if $? != 0 || username.strip == ''
+        end
+      end
+
+      username || `whoami`.chomp
+    end
+
+    # load the default built-in plugins
+    # this is called automatically when capistrano is done loading
+    # you can disable this (and not laod any plugins by default) by setting capnotify_disable_default_components
+    #  set :capnotify_disable_default_components, true
+    def load_default_plugins
+      capnotify.load_plugin Capnotify::Plugin::Message
+      capnotify.load_plugin Capnotify::Plugin::Overview
+      capnotify.load_plugin Capnotify::Plugin::Details
+    end
+
+    # given a module name, load it as a plugin
+    # capnotify plugins must conform to the spec. See docs for info.
+    # mod should be the module itself, eg:
+    #  capnotify.load_plugin Capnotify::Plugin::Message
+    def load_plugin(mod)
+      Capistrano.plugin mod::PLUGIN_NAME, mod
 
-      get_plugin(name).init
+      get_plugin(mod::PLUGIN_NAME).init
     end
 
+    # given a plugin name as a symbol, unload the capnotify plugin
+    # this will also unload any kind of capistrano plugin
+    # if the plugin supports the unload method, it will be called.
     def unload_plugin(name)
       p = get_plugin(name)
 
@@ -38,6 +75,7 @@ module Capnotify
       Capistrano.remove_plugin(name)
     end
 
+    # given a plugin name, return the plugin.
     def get_plugin(name)
       raise "Unknown plugin: #{ name }" unless Capistrano::EXTENSIONS.keys.include?(name)
       self.send(name)

data/lib/capnotify/plugin/details.rb

@@ -2,8 +2,10 @@ module Capnotify
   module Plugin
     module Details
 
+      PLUGIN_NAME = :capnotify_details
+
       def init
-        capnotify.components << Capnotify::Component.new(:capnotify_details) do |c|
+        capnotify.components << Capnotify::Component.new(PLUGIN_NAME) do |c|
           c.header = 'Deployment Details'
 
           c.content = {}
@@ -18,7 +20,7 @@ module Capnotify
       end
 
       def unload
-        capnotify.delete_component :capnotify_details
+        capnotify.delete_component PLUGIN_NAME
       end
 
     end

data/lib/capnotify/plugin/message.rb

@@ -0,0 +1,33 @@
+# Capnotify built-in plugin for Custom messages in email
+# This adds a "message" section that will include 'notification_msg' if it's set
+# For example:
+#  cap deploy -s notification_msg="Just getting a hotfix deployed"
+module Capnotify
+  module Plugin
+    module Message
+
+      # the plugin's name (how it's referenced once it's loaded)
+      PLUGIN_NAME = :capnotify_message
+
+      # initialize the plugin
+      def init
+        # add a component tagged with this plugin's name
+        capnotify.components << Capnotify::Component.new(PLUGIN_NAME) do |c|
+          # the header
+          c.header = 'Message'
+
+          # the content
+          # if notification_msg isn't set, content will be set to nil
+          # nil content will prevent the section from being rendered.
+          c.content = fetch(:notification_msg, nil)
+        end
+      end
+
+      # delete the component when this plugin is unloaded
+      def unload
+        capnotify.delete_component PLUGIN_NAME
+      end
+
+    end
+  end
+end

data/lib/capnotify/plugin/overview.rb

@@ -2,22 +2,25 @@ module Capnotify
   module Plugin
     module Overview
 
+      PLUGIN_NAME = :capnotify_overview
+
       def init
-        capnotify.components << Capnotify::Component.new(:capnotify_overview) do |c|
+        capnotify.components << Capnotify::Component.new(PLUGIN_NAME) do |c|
           c.header = 'Deployment Overview'
 
           c.content = {}
-          c.content['Deployed by'] = 'capnotify.deployed_by'
+          c.content['Deployed by'] = capnotify.deployed_by
           c.content['Deployed at'] = Time.now
-          c.content['Application'] = fetch(:application, '')
-          c.content['Repository'] = fetch(:repository, '')
+          c.content['Application'] = fetch(:application, 'n/a')
+          c.content['Repository'] = fetch(:repository, 'n/a')
         end
       end
 
       def unload
-        capnotify.delete_component :capnotify_overview
+        capnotify.delete_component PLUGIN_NAME
       end
 
+
     end
   end
 end

data/lib/capnotify/templates/default_notification.html.erb

@@ -64,6 +64,7 @@
   </h1>
 
   <% capnotify.components.each do |component| %>
+    <% next if component.content.nil? %>
     <div class="<%= component.css_class %>">
       <h2><%= component.header %></h2>
 

data/lib/capnotify/templates/default_notification.txt.erb

@@ -1,7 +1,8 @@
 <%= capnotify.appname %> deployment completed!
 
 <% capnotify.components.each do |component| %>
---- <%= @header %> ---
+  <% next if component.content.nil? %>
+--- <%= component.header %> ---
 <%= component.render_content(:txt) %>
 <% end %>
 

data/lib/capnotify/version.rb

@@ -1,3 +1,3 @@
 module Capnotify
-  VERSION = "0.1.6pre"
+  VERSION = "0.2.0"
 end

data/spec/capnotify/plugin_spec.rb

@@ -19,6 +19,9 @@ describe Capnotify::Plugin do
   # a plugin for testing with
   # wires up init and unload to the ProxyObject
   module MyPlugin
+
+    PLUGIN_NAME = :my_plugin
+
     def init
       ProxyObject.instance.call_init
     end
@@ -65,7 +68,7 @@ describe Capnotify::Plugin do
 
     it "should load the plugin into capistrano" do
       config.load do
-        capnotify.load_plugin :my_plugin, MyPlugin
+        capnotify.load_plugin MyPlugin
       end
 
       Capistrano::EXTENSIONS.keys.should include(:my_plugin)
@@ -75,7 +78,7 @@ describe Capnotify::Plugin do
       ProxyObject.instance.should_receive :call_init
 
       config.load do
-        capnotify.load_plugin :my_plugin, MyPlugin
+        capnotify.load_plugin MyPlugin
       end
 
     end
@@ -86,7 +89,7 @@ describe Capnotify::Plugin do
 
     before do
       config.load do
-        capnotify.load_plugin :my_plugin, MyPlugin
+        capnotify.load_plugin MyPlugin
       end
     end
 
@@ -115,7 +118,7 @@ describe Capnotify::Plugin do
     context "when plugin exists" do
       before do
         config.load do
-          capnotify.load_plugin :my_plugin, MyPlugin
+          capnotify.load_plugin MyPlugin
         end
       end
 
@@ -149,6 +152,44 @@ describe Capnotify::Plugin do
       lambda { capnotify.build_template( capnotify.built_in_template_for('default_notification.txt.erb') ) }.should_not raise_error
     end
 
+    context "when building templates with components" do
+
+      let(:html_rendered_template) { capnotify.build_template( capnotify.built_in_template_for('default_notification.html.erb') ) }
+      let(:text_rendered_template) { capnotify.build_template( capnotify.built_in_template_for('default_notification.txt.erb') ) }
+
+      before do
+        capnotify.load_default_plugins
+        capnotify.components.count.should > 0
+      end
+
+      context "html templates" do
+        it "should not render components with no content" do
+          html_rendered_template.should_not match(/Message/) # the header
+        end
+
+        it "should render components with content" do
+          config.set :notification_msg, 'ASDFASDF'
+
+          html_rendered_template.should match(/Message/) # the header
+          html_rendered_template.should match(/ASDFASDF/) # the content
+        end
+      end
+
+      context "text templates" do
+        it "should not render components with no content" do
+          text_rendered_template.should_not match(/Message/) # the header
+        end
+
+        it "should render components with content" do
+          config.set :notification_msg, 'ASDFASDF'
+
+          text_rendered_template.should match(/Message/) # the header
+          text_rendered_template.should match(/ASDFASDF/) # the content
+        end
+      end
+
+    end
+
   end
 
   context "#components" do

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: capnotify
 version: !ruby/object:Gem::Version
-  version: 0.1.6pre
-  prerelease: 5
+  version: 0.2.0
+  prerelease: 
 platform: ruby
 authors:
 - Spike Grobstein
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-03 00:00:00.000000000 Z
+date: 2013-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -98,7 +98,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.14.2
+        version: '2.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -106,7 +106,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.14.2
+        version: '2.14'
 description: Extensible Capistrano notification system with helpers and sensible default
   values for common notification tasks.
 email:
@@ -127,6 +127,7 @@ files:
 - lib/capnotify/component.rb
 - lib/capnotify/plugin.rb
 - lib/capnotify/plugin/details.rb
+- lib/capnotify/plugin/message.rb
 - lib/capnotify/plugin/overview.rb
 - lib/capnotify/templates/_component.html.erb
 - lib/capnotify/templates/_component.txt.erb
@@ -150,12 +151,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -27722869543230501
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: -27722869543230501
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -167,4 +174,3 @@ test_files:
 - spec/capnotify/plugin_spec.rb
 - spec/capnotify_spec.rb
 - spec/spec_helper.rb
-has_rdoc: