torque 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: abb92afe8ffbc8574c523dc0edc68438b75ccdeb
+  data.tar.gz: 5e0715da5458863001a6c9ff66cfa591704ff830
+SHA512:
+  metadata.gz: 63143235c62b8ddd4b95d6a8b6a654f78b17e4b2e4e9592009a51679eaa7f971cc0542246029938df55b473124bd9d91e49f370ca64cd26cb3a2ce73668c9435
+  data.tar.gz: f0ebb0b09dda8ae970bcd116eeb78ece99d183a21e625074de6638557efa65b0fd9adab1520ef9afeeeddfe22f8515377e4a38256dbe49cc2e47f9c493f912fd

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Scrimmage
+
+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.md

@@ -0,0 +1,116 @@
+Torque
+======
+
+Introduction
+------------
+
+Torque is a command line utility packaged as a Ruby gem. It compiles online data from a Pivotal Tracker project into a set of release notes for that project.
+
+At start, Torque requests a Pivotal Tracker API token, which gives Torque access to information from your Pivotal Tracker projects. Torque then asks the user to choose one of their projects to begin to generate notes from.
+
+Once configured, Torque requests data on the accepted stories from the current Pivotal project. It then compiles these stories into a first-draft release notes document. Depending on how consistently your team uses Pivotal Tracker, this document will contain:
+
+* A record of each feature that was added to the project since the last time Torque was run
+* A description of the feature
+* The date that this feature was accepted
+* A link to the Pivotal Tracker story that tracks this feature
+
+Torque's default behavior is to document all the stories that were accepted since the last time Torque was run. For instance, if Torque was run on June 1st and then on June 10th, it would generate release notes from the stories that were accepted between June 1st and June 10th (inclusive). This is designed to make it easy to generate release notes each time new features are pushed to production: If Torque is run at the time of each new release, then it will generate notes for all the features that were added since the previous release. If needed, Torque can also generate notes for a custom date range.
+
+Torque was designed and tested in a Ruby 2.0 environment.
+
+Current Features
+----------------
+
+* Automatically compiles all Pivotal Tracker stories accepted between the current date and the last time Torque was run
+* Compile stories accepted within a custom date range
+* Stores a record of each document as it's generated
+* Configuration script that automatically sets up a directory to use Torque
+* Project script that automatically displays/switches between your Pivotal Tracker projects
+* Ability to email the finished release notes from a personal email account to a pre-specified mailing list. (Currently can only send from accounts hosted by Gmail)
+
+Note on Confidentiality
+-----------------------
+
+During usage, Torque will request some confidential information -- namely, your Pivotal Tracker API token and your email username/password. This information is stored in a local config file on your computer and is only used to access (respectively) Pivotal Tracker and your email server. It is never collected, sent to a 3rd party, or used for any other purpose.
+
+Torque stores this data in a file called '.torqueinfo.yaml': Do not commit this file to your version control system!
+
+Installation
+------------
+
+    # gem install torque
+
+Configuration
+-------------
+
+To configure Torque, run in your project's root directory
+
+    # torque config
+
+The configuration script will request a Pivotal Tracker API token, which can be found at https://www.pivotaltracker.com/profile#api. The token can be reset at any time by running:
+
+    # 'torque config -t/--token'
+
+To change the output directory Torque writes its release notes to:
+
+    # 'torque config -o/--output [directory]'
+
+To overwrite the Torque settings and/or output directory:
+
+    # 'torque config -f/--force'
+
+Usage
+-----
+
+In a directory that has been configured, run
+
+    # torque
+
+Alternately, run Torque from a different directory by using the --root option:
+
+    # torque --root [configured/torque/directory]
+
+This will compile release notes for all stories accepted since the last time you ran Torque in this directory.
+
+To compile release notes for stories within a custom date range:
+
+    # torque -f [from] -t [to]
+
+If [from] is set, [to] will default to today. If [to] is set, [from] will default to 1/1/1900.
+
+To email the release notes from a personal email to Torque's mailing list:
+
+    # torque --email
+
+Running with the 'verbose' option will print a running list of stories as they are added. Running with the 'silent' option will silence all output.
+
+To display all available Pivotal Tracker projects or change your current project:
+
+    # torque project
+
+To set up automatic emailing when the notes and add/remove from the mailing list:
+
+    # torque email
+
+License
+-------
+
+Copyright (c) 2013 Scrimmage
+
+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/VERSION

@@ -0,0 +1,3 @@
+major:0
+minor:0
+patch:1

data/bin/config

@@ -0,0 +1,257 @@
+#!/usr/bin/env ruby
+
+# Configuration script for Torque. Sets up an output directory and settings file
+
+lib_dir = File.expand_path("../lib", File.dirname(__FILE__))
+template_dir = File.expand_path("../template", File.dirname(__FILE__))
+working_dir = "."
+
+require 'fileutils'
+require 'highline/import'
+require 'net/http'
+require 'optparse'
+require 'pathname'
+require "#{lib_dir}/torque/pivotal"
+require "#{lib_dir}/torque/torque_info_parser"
+require "#{lib_dir}/torque/project/project"
+require "#{lib_dir}/torque/project/project_manager"
+
+# Parses the options
+options = {}
+option_parser = OptionParser.new do |opts|
+
+  help_message = "Configures a directory to use Torque."
+  help_message += "\n"
+  help_message += "\nThis script will create a template for .torqueinfo.yaml and set up an output directory. It " \
+                  "will also set up access to the Pivotal Tracker API"
+
+  opts.banner  = "\nUsage:"
+  opts.banner += "\n    torque config [options]"
+  opts.banner += "\n"
+  opts.banner += "\n#{help_message}"
+  opts.banner += "\n"
+  opts.banner += "\n"
+  
+  opts.on("-f", "--force", "Force a configuration, overwriting any existing .torqueinfo file or output directory") do
+    |arg|
+    options[:force] = arg
+  end
+
+  opts.on("-h", "--help", "Display this help screen") do
+    |arg|
+    options[:help] = arg
+  end
+
+  opts.on("-o", "--output OUTPUT", "Set the output directory to the directory specified (default: release_notes)") do
+    |arg|
+    options[:output_dir] = arg
+  end
+
+  opts.on("-t", "--token", "Set the API token and Pivotal project only (do not change the filesystem)") do
+    |arg|
+    options[:token] = arg
+  end
+
+end
+
+# Parses options and handles exceptions
+
+begin
+  option_parser.parse!
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts option_parser
+  exit
+end
+
+# Handles special cases and exceptions
+
+if ARGV.member? "help" || options[:help]
+  puts "(Ran with 'help' option; other options ignored)"
+  puts option_parser
+  exit
+elsif !ARGV.empty?
+  puts "Unknown arguments: #{ARGV.join(", ")}"
+  puts option_parser.help
+  exit
+end
+
+# Checks for a connection to Pivotal Tracker
+
+if !Torque::Pivotal.connection?
+  puts "ABORTING"
+  puts "Cannot connect to www.pivotaltracker.com. A connection is required to configure Torque"
+  exit 1
+end
+
+# Configures the directory
+
+if !options[:token]
+
+  puts "Configuring directory for Torque..."
+
+  # Checks that configuration is possible
+
+  default_output_dir = "release_notes"
+  output_dir = options[:output_dir] || default_output_dir
+  output_path = Pathname.new(output_dir)
+
+  if !options[:force] && !options[:output_dir] && output_path.exist?
+    puts "ABORTING"
+    puts "The default output directory, #{default_output_dir}, already exists."
+    puts "(Use -o to choose an existing output directory or create a new one)"
+    puts "(Use -f to overwrite an existing directory)"
+    exit
+  end
+  
+
+  torque_info_path = Pathname.new(".torqueinfo.yaml")
+
+  if !options[:force] && !options[:output_dir] && torque_info_path.exist?
+    puts "ABORTING"
+    puts "A .torqueinfo.yaml file already exists in this directory."
+    puts "(Use -o to ignore this file and change only the output directory)"
+    puts "(Use -f to overwrite this file)"
+    exit
+  end
+  
+
+  # Configures the directory
+
+  retained_torque_info_file = false # True if the torque info file is the same after configuration
+
+  if options[:force] && output_path.exist?
+    puts "- Overwriting directory #{output_dir}"
+    FileUtils.rm_r(output_dir)
+
+  elsif options[:output_dir] && output_path.exist?
+    puts "- Setting output directory to #{output_dir}"
+
+  else
+    puts "- Creating directory #{output_dir}"
+  end
+
+  FileUtils.mkdir_p("#{output_dir}/previous")
+
+  if options[:force] && torque_info_path.exist?
+    puts "- Overwriting file .torqueinfo.yaml"
+    FileUtils.rm(".torqueinfo.yaml")
+
+  elsif options[:output_dir] && torque_info_path.exist?
+    retained_torque_info_file = true
+
+  else
+    puts "- Creating file .torqueinfo.yaml"
+  end
+
+  FileUtils.touch("./.torqueinfo.yaml")
+
+  File.open(".torqueinfo.yaml", "a+") do |file|
+    file.write("\n\n")
+  end
+  Torque::TorqueInfoParser.new.set("output_dir", output_dir)
+
+end
+
+
+# Determines whether to set up a new API token and project ID
+
+should_setup_info = true
+if retained_torque_info_file
+  valid = /^\s*(y|Y|n|N)\s*$/
+  setup_info_prompt = ask("Existing Torque info file found. Would you like to set up a new API token? [y/n]") {
+    |q|
+    q.validate = valid
+  }
+  setup_info_prompt.strip!
+  should_setup_info = (setup_info_prompt =~ /y|Y/)
+end
+
+
+if should_setup_info
+
+  # Adds the API token to the torque info file
+
+  project_manager = Torque::ProjectManager.new
+
+  puts
+  puts "In order to generate release notes, Torque needs your account's Pivotal Tracker API token"
+
+  # Input loop
+  while true
+    token_input = ask("Please paste your Pivotal Tracker API token below: https://www.pivotaltracker.com/profile#api") {
+      |q| q.echo = "*"
+    }
+    token = token_input.to_s
+
+    Torque::Pivotal.new(token).check_token ? break : (puts "Token was invalid. Try again")
+  end
+
+  File.open(".torqueinfo.yaml", "a+") do |file|
+    Torque::TorqueInfoParser.new.set("token", token)
+  end
+
+  # Adds the project ID to the torque info file
+
+  project_manager.load_project_list(token)
+  project_list = project_manager.project_list
+
+  if project_list.empty?
+    puts "No projects found for your Pivotal Tracker account. Add a project to your account, then use 'torque " \
+      "project' to set your Torque project"
+
+  else
+
+    # If only one project exists, defaults to it
+    if project_list.length == 1
+      project_index = 0
+      puts
+
+    # Allows user to choose between multiple projects
+    else
+      choice_str = "Please select one of the following projects. Torque will use the stories from this project to " \
+        "generate release notes"
+      choice_str += "\n(Enter a number)"
+      project_list.each_with_index do
+        |project, index|
+        choice_str += "\n#{index} : #{project.id} #{project.name}"
+      end
+
+      # Short util method for parsing numbers from strings
+      # Returns nil if no number can be parsed from string or if the number parsed is >= max
+      def parse_index(string, max)
+        index = nil
+        begin; index = Integer(string)
+        rescue ArgumentError; return nil
+        end
+        (index >= max || index < 0) ? nil : index
+      end
+
+      # Input loop
+      puts
+      while true
+        puts choice_str
+        num_str = ask("")
+        project_index = parse_index(num_str, project_list.length)
+        project_index ? break : (puts "Choice was invalid. Try again")
+      end
+
+    end
+
+    project = project_list[project_index]
+    Torque::TorqueInfoParser.new.set("project", Integer(project.id))
+    puts "Set project to #{project.id} - '#{project.name}'"
+    puts "Use 'torque project' to change this project"
+
+  end
+end
+
+# Finishes
+
+unless options[:token]
+  puts 
+  puts "Configuration complete!"
+  puts "WARNING: Do not check .torqueinfo.yaml into your version control system! (Contains sensitive information)"
+  puts
+end

data/bin/email

@@ -0,0 +1,172 @@
+#!/usr/bin/env ruby
+
+# Manages email settings for Torque.
+# Prompts for and stores a user's email and password, adds to/removes from the email_to list
+
+lib_dir = File.expand_path("../lib", File.dirname(__FILE__))
+template_dir = File.expand_path("../template", File.dirname(__FILE__))
+working_dir = "."
+
+require 'highline/import'
+require 'mail'
+require 'optparse'
+require "#{lib_dir}/torque/torque_info_parser"
+require "#{lib_dir}/torque/pivotal"
+
+# Parses the options
+options = {}
+option_parser = OptionParser.new do |opts|
+
+  help_message = "Handles email settings for Torque. Allows users to set up their own email address, add or remove " \
+                  "emails from the email_to list, and display the current email settings"
+
+  opts.banner  = "\nUsage:"
+  opts.banner += "\n    torque email [options]"
+  opts.banner += "\n"
+  opts.banner += "\n#{help_message}"
+  opts.banner += "\n"
+  opts.banner += "\n"
+
+  options[:add] = []
+  options[:rm] = []
+  
+  opts.on("-a", "--add ADDRESS", "Add an email address to the list") do
+    |arg|
+    options[:add] << arg
+  end
+
+  opts.on("-r", "--rm ADDRESS", "Remove an email address from the list") do
+    |arg|
+    options[:rm] << arg
+  end
+
+  opts.on("-s", "--setup", "Sets up a personal email address (Gmail only)") do
+    |arg|
+    options[:setup] = arg
+  end
+
+end
+
+# Parses options and handles exceptions
+
+begin
+  option_parser.parse!
+
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+  puts $!.to_s
+  puts option_parser
+  exit
+end
+
+# Handles special cases and exceptions
+
+if ARGV.member? "help" || options[:help]
+  puts "(Ran with 'help' option; other options ignored)"
+  puts option_parser
+  exit
+elsif !ARGV.empty?
+  puts "Unknown arguments: #{ARGV.join(", ")}"
+  puts option_parser.help
+  exit
+end
+
+# Checks for a connection to Pivotal Tracker
+
+if !Torque::Pivotal.connection?
+  puts "ABORTING"
+  puts "Cannot connect to www.pivotaltracker.com. A connection is required to use Torque"
+  exit 1
+end
+
+# Parses the torque info file
+
+torque_info = Torque::TorqueInfoParser.new
+begin
+  torque_info.parse
+rescue Torque::MissingTorqueInfoFileError => e
+  puts "ABORTING"
+  puts e.message
+  puts "Run 'torque config' in this directory, or change your working directory"
+  exit 2
+end
+
+# Util method to display the current email settings
+# Passes in the current TorqueInfoParser
+def disp_email(torque_info)
+
+  if !torque_info.email_address
+    puts "No user email found. (Set up your email address with 'torque email -s/--setup')"
+  elsif !torque_info.email_password
+    puts "No password found for current user email, '#{torque_info.email_address}'. (Set this with 'torque email " \
+      "--setup')"
+  else
+    puts "Email: #{torque_info.email_address}"
+  end
+
+  if torque_info.email_to.nil? || torque_info.email_to.empty?
+    puts "Mailing list: <empty>"
+  else
+    puts "Mailing list:"
+    torque_info.email_to.each do |email|
+      puts "  #{email}"
+    end
+  end
+
+end
+
+# Sets up the user's email and password
+
+if options[:setup]
+
+  puts "Enter the email address and password for the account you wish to send emails from. (Only Gmail accounts are " \
+    "currently supported)"
+  email_address = ( ask("Address:") ).to_s
+  email_password = ( ask("Password:") {|p| p.echo = "*"} ).to_s
+
+  torque_info.set("email_address", email_address)
+  torque_info.set("email_password", email_password)
+
+  puts "Ready to email!"
+
+  puts "---" unless (options[:add].empty? && options[:rm].empty?)
+  
+end
+
+# Validates all emails to be added
+
+options[:add].each do |email|
+
+end
+
+# Adds and removes emails from the email list
+
+unless (options[:add].empty? && options[:rm].empty?)
+
+  emails_added = torque_info.add_no_duplicates("email_to", options[:add])
+  options[:add].each do |email|
+    if emails_added.member? email
+      puts "'#{email}' added"
+      emails_added.delete(email)
+    else
+      puts "(add: '#{email}' is already on the list)"
+    end
+  end
+
+  emails_removed = torque_info.rm("email_to", options[:rm])
+  options[:rm].each do |email|
+    if emails_removed.member? email
+      puts "'#{email}' removed"
+      emails_removed.delete("#{email}")
+    else
+      puts "(rm: '#{email}' is not on the list)"
+    end
+  end
+
+end
+
+# Finishes
+
+torque_info.parse
+puts
+disp_email(torque_info)
+puts