mingle-macro-development-toolkit 1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2008 ThoughtWorks, Inc.  All rights reserved.
+
+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/README.rdoc

@@ -0,0 +1,66 @@
+= Macro Development Toolkit - supporting development of custom macros for Mingle
+
+This toolkit provides support for developing, testing and deploying custom Mingle macros. 
+
+Use the built in generator to create a skeleton of a plugin which you can then deploy to an instance of Mingle running
+version 2.2 or later of the software.
+
+This allows you to take advantage of free charting utilities such as the Google Charts API, to create 
+new visualizations, specific to your project or organization.
+
+== FEATURES:
+
+* A command line tool to generate the skeleton of a custom Mingle macro
+* A unit test helper that uses locally available YAML fixture files to facilitate unit testing of the macros
+* An integration test helper that can 
+  * obtain data from a remote instance of Mingle
+  * test MQL execution against a remote instance of Mingle
+* Rake task to deploy the custom macro as a plugin to a locally deployed Mingle instance
+
+== INSTALL:
+
+The preferred method of installing the Macro Development Toolkit is through its GEM file. You'll need to have
+RubyGems[http://www.rubygems.org/] installed for that, though. If you have it,
+then use:
+
+  % [sudo] gem install macro_development_toolkit-1.0.gem
+
+== GETTING STARTED:
+
+To get started with this gem after you install it, use the new_mingle_macro script to generate a skeleton for your
+macro, along with test helpers. Say you wanted to create a new macro called "risk_meter" start out by creating 
+the macro skeleton as follows
+
+  % new_mingle_macro risk_meter
+
+The skeleton project will also contain a file, called "getting_started.txt" that will walk you through the steps 
+of fleshing out your macro.
+
+== SUPPORT:
+ 
+For any issues/clarifications/comments with installation or using this gem, contact us at the Mingle forums[http://studios.thoughtworks.com/discussion/forums/]. You can also get in touch with the ThoughtWorks Studios support
+team over email at support@thoughtworks.com
+
+== LICENSE:
+
+The MIT License
+
+Copyright (c) 2008 ThoughtWorks, Inc.  All rights reserved.
+
+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,36 @@
+#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+
+begin
+  require 'rubygems'
+
+  unless Gem::RubyGemsVersion >= '1.2.0'
+    $stderr.puts %(Rails requires RubyGems >= 1.2.0 (you have #{rubygems_version}). Please `gem update --system` and try again.)
+    exit 1
+  end
+
+rescue LoadError
+  $stderr.puts %(Rails requires RubyGems >= 1.2.0. Please install RubyGems and try again: http://rubygems.rubyforge.org)
+  exit 1
+end
+
+%w[rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/macro_development_toolkit'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('mingle-macro-development-toolkit', MacroDevelopmentToolkit::VERSION) do |p|
+  p.developer('ThoughtWorks Inc', 'support@thoughtworks.com')
+  p.post_install_message = 'getting_started.txt'
+  p.rubyforge_name       = 'mingle-macros'
+  p.extra_deps         = [
+    ['activesupport','>= 2.0.2'],
+  ]
+  p.rdoc_pattern = /README|(lib\/macro_development_toolkit\/mingle(?!_))/
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = ''
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }

data/bin/new_mingle_macro

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+#Copyright 2008 ThoughtWorks, Inc.  All rights reserved.
+
+require 'erb'
+begin
+  require 'activesupport'
+rescue LoadError
+  require 'rubygems'
+  require 'activesupport'
+end
+
+def print_usage
+  puts <<-EOS
+    Macro name cannot be blank.
+    
+    Usage: new_mingle_macro <macro_name> [macro_class_name]
+    
+    macro_name      : The name of your new macro. Should be aplphabetic, possibly including underscores(_)
+    macro_class_name: (optional) The name of the class that implements the macro. Should be a CamelCased alphabetic string. Defaults to CamelCased version of macro_name.
+    
+  EOS
+end
+
+if ARGV[0].blank?
+  print_usage
+  exit!
+end
+
+macro_name = ARGV[0].downcase.gsub(/\s/, '_')
+
+if macro_name !~ /^[_A-Za-z]+$/
+  print "Your macro name contains special characters that we will replace with underscore (_). Is this OK? [Yes/No]"
+  exit if STDIN.gets.downcase =~ /^n/
+  macro_name = macro_name.gsub(/[^_A-Za-z]/, '_').squeeze('_')
+end
+
+macro_class_name = ARGV[1] || macro_name.gsub(/\W/, '_').classify
+if macro_class_name.classify != macro_class_name
+  print "Your macro class name is not a valid class name. Continue with the default class name of #{macro_name.classify}? [Yes/No]"
+  exit if STDIN.gets.downcase =~ /^n/
+  macro_class_name = macro_name.classify
+end
+
+if File.exists?(macro_name)
+  print "Folder #{macro_name} already exists in your current directory. Either rename the macro or delete the folder and then execute this command to continue."
+  exit
+end
+
+puts "macro name is #{macro_name}"
+
+class Path
+  def initialize(location=:gem)
+    @base_location = if location.to_s == 'gem'
+      File.expand_path(File.join(File.dirname(__FILE__), '..'))
+    else
+      File.expand_path(location)
+    end    
+      
+  end
+  
+  def /(another_fragment)
+    self.class.new(File.join(@base_location, another_fragment))
+  end  
+  
+  def cp(options = {:to => nil, :r => true})
+    if options[:r]
+      FileUtils.cp(@base_location, options[:to].to_s, :verbose => true)
+    else
+      FileUtils.cp_r(@base_location, options[:to].to_s, :verbose => true)
+    end    
+  end
+  
+  def mkdir_p
+    FileUtils.mkdir_p(@base_location)
+  end  
+
+  def to_s
+    @base_location
+  end
+end  
+
+gem_dir = Path.new(:gem)
+macro_dir = Path.new(macro_name)
+
+[macro_dir/'lib', macro_dir/'test'/'unit', macro_dir/'test'/'fixtures', macro_dir/'test'/'integration', macro_dir/'tasks'].each(&:mkdir_p)
+
+(gem_dir/'test'/'fixtures'/'sample').cp :to => macro_dir/'test'/'fixtures'
+(gem_dir/'test'/'unit'/'fixture_loader.rb').cp :to => macro_dir/'test'/'unit'/'fixture_loader.rb'
+(gem_dir/'test'/'integration'/'rest_loader.rb').cp :to => macro_dir/'test'/'integration'/'rest_loader.rb'
+(gem_dir/'tasks'/'test.rake').cp :to => macro_dir/'tasks'/'test.rake'
+(gem_dir/'example'/'deploy.rake').cp :to => macro_dir/'tasks'/'deploy.rake'
+(gem_dir/'getting_started.txt').cp :to => macro_dir/'getting_started.txt'
+
+templates = {
+  gem_dir/'example'/'Rakefile' => macro_dir/'Rakefile',
+  gem_dir/'example'/'init.rb' => macro_dir/'init.rb',
+  gem_dir/'example'/'macro.rb' => macro_dir/'lib'/"#{macro_name}.rb",
+  gem_dir/'example'/'unit_test.rb' => macro_dir/'test'/'unit'/"#{macro_name}_test.rb",
+  gem_dir/'example'/'unit_test_helper.rb' => macro_dir/'test'/'unit'/'unit_test_helper.rb',
+  gem_dir/'example'/'integration_test.rb' => macro_dir/'test'/'integration'/"#{macro_name}_integration_test.rb",
+  gem_dir/'example'/'integration_test_helper.rb' => macro_dir/'test'/'integration'/'integration_test_helper.rb'
+}
+
+templates.each do |template, output|
+  template_file = File.open(template.to_s)
+  File.open(output.to_s, 'w').write(ERB.new(template_file.read, nil, '-').result(binding))
+end

data/example/Rakefile

@@ -0,0 +1,3 @@
+%w[rubygems rake rake/clean rake/testtask fileutils macro_development_toolkit].each { |f| require f }
+
+Dir['tasks/**/*.rake'].each { |t| load t }

data/example/deploy.rake

@@ -0,0 +1,10 @@
+namespace :macro do |ns|
+
+  task :deploy do
+    macro_folder = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+    mingle_plugins_folder = File.join(ENV['MINGLE_LOCATION'], 'vendor', 'plugins')
+    FileUtils.cp_r(macro_folder, mingle_plugins_folder)
+    puts "#{macro_folder} successfully copied over to #{mingle_plugins_folder}. Restart the Mingle server to start using the macro."
+  end
+
+end

data/example/init.rb

@@ -0,0 +1,10 @@
+begin
+  require 'macro_development_toolkit'
+rescue LoadError
+  require 'rubygems'
+  require 'macro_development_toolkit'
+end
+
+if defined?(RAILS_ENV) && RAILS_ENV == 'production' && defined?(MinglePlugins)
+  MinglePlugins::Macros.register(<%= macro_class_name %>, '<%= macro_name %>')
+end 

data/example/integration_test.rb

@@ -0,0 +1,13 @@
+require File.dirname(__FILE__) + '/integration_test_helper.rb'
+
+class <%= macro_class_name %>IntegrationTest < Test::Unit::TestCase
+  
+  PROJECT_RESOURCE = 'http://username:password@your.mingle.server:port/lightweight_projects/your_project_identifier.xml'
+
+  def test_macro_contents
+    <%= macro_name %> = <%= macro_class_name %>.new(nil, project(PROJECT_RESOURCE), nil)
+    result = <%= macro_name %>.execute
+    assert result
+  end
+
+end

data/example/integration_test_helper.rb

@@ -0,0 +1,19 @@
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '..', '..', 'init.rb')
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', '<%= macro_name %>')
+require File.join(File.dirname(__FILE__), 'rest_loader')
+
+class Test::Unit::TestCase
+
+  def project(name)
+    @project ||= RESTfulLoaders::ProjectLoader.new(name, nil, self).project
+  end  
+
+  def errors
+    @errors ||= []
+  end  
+  
+  def alert(message)
+    errors << message
+  end
+end  

data/example/macro.rb

@@ -0,0 +1,18 @@
+class <%= macro_class_name %>
+
+  def initialize(parameters, project, current_user)
+    @parameters = parameters
+    @project = project
+    @current_user = current_user
+  end
+    
+  def execute
+    "Customize me and return some HTML"
+  end
+  
+  def can_be_cached?
+    false  # if appropriate, switch to true once you move your macro to production
+  end
+    
+end
+

data/example/unit_test.rb

@@ -0,0 +1,13 @@
+require File.join(File.dirname(__FILE__), 'unit_test_helper')
+
+class <%= macro_class_name %>Test < Test::Unit::TestCase
+  
+  FIXTURE = 'sample'
+  
+  def test_macro_contents
+    <%= macro_name %> = <%= macro_class_name %>.new(nil, project(FIXTURE), nil)
+    result = <%= macro_name %>.execute
+    assert result
+  end
+
+end

data/example/unit_test_helper.rb

@@ -0,0 +1,12 @@
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '..', '..', 'init.rb')
+require File.join(File.dirname(__FILE__), '..', '..', 'lib', '<%= macro_name %>')
+require File.join(File.dirname(__FILE__), 'fixture_loader')
+
+class Test::Unit::TestCase
+  
+  def project(name)
+    @project ||= FixtureLoaders::ProjectLoader.new(name).project
+  end  
+   
+end

data/getting_started.txt

@@ -0,0 +1,253 @@
+A background on macros in Mingle
+---------------------------------
+
+Macros are a special kind of markup in the Mingle wiki. A macro is identified by the following markup generic syntax
+
+{{ 
+  macro_name
+    parameter1: value1
+    parameter2: value2
+    ...
+}}
+
+The markup has to be valid YAML syntax. Specifically, this means that the markup is sensitive to spacing and indentation. For more help around YAML and what constitutes valid YAML markup, you can refer to http://yaml.org/spec/current.html
+
+Specific examples of this include the pre-written macros, such as the value, average & table macros and the macros for all the charts.
+
+When Mingle encounters a macro while rendering the markup, it delegates handling of the macro to a custom class behind the scenes that is registered to handle it. e.g., if Mingle encountered the following markup,
+
+{{
+  average
+    query: SELECT 'Pre-release Estimate' WHERE Release = (current release)
+}}
+
+it would parse the content between the opening and closing double braces, and identify the following.
+
+Macro Name: average
+Macro Parameters: {query => "SELECT 'Pre-release Estimate' WHERE Release = (current release)"}
+
+It then scans a registry of known macros, for a class that is configured to handle a macro with name average. This is the AverageMacro class. You can find this class under the vendor/plugins/average_macro directory of your installation of Mingle.
+
+class AverageMacro
+  
+  def initialize(parameters, project, current_user)
+    @parameters = parameters
+    @project = project
+    raise "Parameter <b>query</b> is required" unless query
+  end
+  
+  def execute
+    first_values = @project.execute_mql(query).collect { |record| record.values.first }
+    data = first_values.reject(&:blank?).collect(&:to_f) 
+    data.empty? ? 'no values found' : @project.format_number_with_project_precision(data.sum.to_f/data.size.to_f)
+  end
+  
+  private
+  
+  def query
+    @parameters['query']
+  end
+end
+
+All data that is required to execute the macro is injected into the macro through the constructor. The parameters that are interpreted from the markup are passed in as a hash. The project that is passed in is a lightweight representation of the project in the Mingle model, and is documented at http://mingle-macros.rubyforge.org/rdoc
+
+The execute method uses the MQL execution facility that the project class provides, to execute the MQL string that is passed into through the parameters hash. It then formats the results to be a number, and provides that result of the execute command.
+
+For more help on what constitutes valid MQL, you can refer to our help documentation at http://studios.thoughtworks.com/mingle-agile-project-management/2.2/help/mql_reference.html
+
+Writing your own macro
+----------------------
+
+To write your own macro, you can start with the generated skeleton for the macro. To generate your own macro skeleton, use the new_mingle_macro script that installed with your gem.
+
+% new_mingle_macro your_new_macro
+
+This should generate a folder structure as follows
+
+your_new_macro
+      |
+      |----lib
+      |     |
+      |     your_new_macro.rb
+      |
+      |
+      |----test
+             |
+             |----fixtures
+             |      |
+             |    sample
+             |       |
+             |       projects.yml, card_types.yml...
+             |
+             |---- unit
+             |      |
+             |      your_new_macro_test.rb,...
+             |
+             |---- integration
+                    |
+                    your_new_macro_integration_test.rb, ...
+
+
+The lib directory contains the actual macro, and the test folders give you the option to run the tests either against local YAML based fixtures, or using REST to test against a deployed mingle instance.
+
+When this macro is deployed to Mingle, all wiki markup of the form
+
+{{
+  your_new_macro
+    parameter1: value1
+    parameter2: <some_mql_statement>
+    ...
+}}
+
+will be parsed as YAML and handling will be delegated to an instance of your macro class, YourNewMacro. The parameters will be parsed into a Ruby hash, of the following structure:
+
+{'parameter1' => 'value1', 'parameter2' => '<some_mql_snippet>'}
+
+and will be passed into the constructor of the class, along with an instance of a Mingle::Project, that represents the project that this macro is being rendered on.
+
+As an example of what you can do with this information is the following macro, which uses the Google Charting API to render a Google-o-meter style chart to represent work completed in a fuel gauge style meter.
+
+class WorkGauge
+  
+  def initialize(parameters, project, current_user)
+    @parameters = parameters
+    @project = project
+    @current_user = current_user
+  end
+    
+  def execute
+    completed_work = @project.execute_mql(@parameters['completed_work']).first.values.sum
+    total_work = @project.execute_mql(@parameters['total_work']).first.values.sum
+    completion_percentage = (completed_work.to_f / total_work.to_f) * 100
+
+    %Q{ <img src='http://chart.apis.google.com/chart?cht=gom&chs=350&chd=t:#{completion_percentage}&chds=0,100' /> }
+  end
+  
+end
+
+You can find both simpler and more complex examples in the vendor/plugins/sample_macros directory.
+
+Unit testing your macro
+------------------------
+
+The macro development toolkit comes with a built in unit testing framework, that borrows the familiar idea of YAML based fixtures. The one small difference we have made to it is that each project that you are providing fixtures for gets its own subfolder within the fixtures directory. We hope that this makes it easier to identify relationships between the objects set up in the YAML files.
+
+If you are using the skeleton project set up by the new_mingle_macro script, the fixtures directory provides you with a sample project fixture. The data in that should give you a sense of the relationships between the various objects.
+
+The skeleton project also has a sample unit test set up for you, which uses the sample fixture data. Note the helper method project(...) which takes the name of a sample project to load information from. This method loads a web of objects from the directory named the same as the argument, in the fixtures folder.
+
+class YourNewMacroTest < Test::Unit::TestCase
+  
+  FIXTURE = 'sample'
+  
+  def test_macro_contents
+    macro = YourNewMacro.new(nil, project(FIXTURE), nil)
+    result = macro.execute
+    assert result
+  end
+
+end
+
+Once loaded, you can test things like parameter checking and validations using this style of test. While you cannot execute MQL in this style of test, you can use your favorite mocking library to test how results get handled.
+
+You can see examples of unit tests in the average macro that is packaged with Mingle in the vendor/plugins/average_macro directory.
+
+To run your unit tests, run 
+
+% rake test:units 
+
+from the root of your custom macro
+
+Integration testing your macro
+-------------------------------
+
+########################################################NOTE###############################################################
+#                                                                                                                         #
+# IN ORDER TO RUN THE INTEGRATION TESTS, YOU WILL NEED TO TURN ON BASIC AUTHENTICATION FOR THE MINGLE 2.2 SERVER THAT YOU # 
+# ARE GOING TO BE TESTING AGAINST.                                                                                        #
+#                                                                                                                         #
+#########################################################NOTE##############################################################
+
+The integration tests look very similar to the unit tests, the primary difference being that they actually communicate with a deployed Mingle instance over REST. The helper methods populate a web of objects representing a project, that look and behave in a manner identical to how they will in production.
+
+The one significant difference about these style of tests is that you can actually execute MQL remotely on the Mingle instance instead of mocking out the MQL execution. This will give you a good idea of what results and errors you may expect to see in production, without having to deploy the macro every time.
+
+There are tradeoffs, of course. Some of these are as follows
+
+* Should you decide to add these tests to a Continuous Integration build, like Cruise, you will hit the production Mingle sever with every test run. Not hot.
+
+* Given that each test makes a call to a production server, there is no guarantee (unless you set it up in such a way) - that multiple calls to fetch the same resource will give the same result.
+
+* Also, while not slow, these tests are definitely much slower than the unit tests. So while it is certainly possible to write only integration tests, we would encourage as a judicious mix of both styles.
+
+class YourNewMacroIntegrationTest < Test::Unit::TestCase
+  
+  PROJECT_RESOURCE = 'http://yourname:password@your.mingle.server:port/lightweight_project/project_identifier.xml'
+
+  def test_macro_contents
+    macro = YourNewMacro.new(nil, project(PROJECT_RESOURCE), nil)
+    result = macro.execute
+    assert result
+  end
+
+end
+
+The skeleton project also has a sample integration test set up for you, which points to a bogus Mingle server, and uses bad credentials. Replace this resource URL with the URL for a deployed instance within your organization. The helper method project(...) which takes the resource URL, loads the data from the XML data obtained from the live instance of Mingle. 
+
+You can see examples of integration tests in the average macro that is packaged with Mingle in the vendor/plugins/average_macro directory. These tests run against a standard template that ships with Mingle2.2, and so you should be able to run them within your organization too, without a problem.
+
+To run your integration tests, run 
+
+% rake test:integration 
+
+from the root of your custom macro
+
+Deploying your macro
+---------------------
+
+####################################################### CAUTION ###########################################################
+#                                                                                                                         #
+# BEFORE YOU DEPLOY ANYTHING TO YOUR MINGLE INSTANCE, PLEASE MAKE SURE THAT IT IS COMPLETELY SAFE. THIS IS ESPECIALLY     # 
+# IMPORTANT IF THE MACRO WAS DEVELOPED BY A THIRD PARTY.                                                                  #
+# HERE IS A LIST OF THINGS THAT YOU SHOULD LOOK OUT FOR. THIS LIST SHOULD NOT BE CONSIDERED COMPLETE, IT IS JUST A        #
+# REPRESENTATIVE SAMPLE.                                                                                                  # 
+#     *    IF MINGLE RUNS AS A PRIVILEGED USER, THE MACRO COULD END UP DAMAGING THE HOST MACHINE                          #
+#     *    THROUGH DIRECT SQL CALLS, RATHER THAN USING SUPPLIED MQL EXECUTION MECHANISM, THE MACRO COULD GAIN ACCESS TO   #
+#          DATA THAT PEOPLE WOULD NORMALLY NOT BE AUTHORIZED TO SEE                                                       #
+#     *    LENGTHY CALLS TO EXTERNAL SYSTEMS COULD TIE UP MINGLE RESOURCES AND LEAVE THE APP UNRESPONSIVE                 #
+#     *    SYSTEM CALLS, IF USED, MUST BE INSPECTED AND WELL-UNDERSTOOD PRIOR TO DEPLOYMENT                               #
+#     *    OTHER DATABASE ACTIVITY, SUCH AS TRANSACTION COMMITS, SHOULD BE MONITORED AND AVOIDED                          #
+#                                                                                                                         #
+######################################################## CAUTION ##########################################################
+
+
+To deploy your macro to a locally deployed instance of Mingle, which is running at mingle_root
+
+% rake macro:deploy MINGLE_LOCATION=/path/to/mingle_root
+
+where /path/to/mingle_root is the location where Mingle2.2 is installed. 
+
+* On Windows, this is the location that the installer installed Mingle at
+* On OSX, this will be within the app bundle, at <mingle_application_bundle>/Contents/Resources/app
+* On *NIX, this is the expanded archive
+
+The entire macro folder and its contents will be copied over into the vendor/plugins directory of that Mingle installation. Once deployed, the server will need to be restarted in order for the macro to become available for use.
+
+Alternatively, you could also copy the folder by hand into the same location.
+
+########################################################NOTE################################################################
+#                                                                                                                          #
+#                                          LEGAL NOTICES AND INFORMATION                                                   #
+#                                                                                                                          #
+#########################################################NOTE###############################################################
+
+This Getting Started file and the mingle-macro-development-toolkit-1.0.gem are owned exclusively by ThoughtWorks, Inc., 
+and ThoughtWorks reserves all rights therein.
+
+We believe that it is a sound practice from legal, business and software development perspectives to always provide copyright 
+information and license information with any software that you make available to others.  We have provided this information 
+for the Mingle Macro Development Toolkit in the LICENSE.txt file distributed with the Toolkit.  We encourage you to use that 
+as an example to follow when marking your software with a copyright notice, as well as providing users with a license to your 
+software.  We have chosen to use the MIT License, an Open Source License, you may choose to use the same or a different 
+license. If you are going to use an Open Source License we strongly encourage you to use a license approved by the Open Source 
+Initiative, available here: http://www.opensource.org/licenses.