ursm-ditz 0.4

data/Changelog

@@ -0,0 +1,35 @@
+== 0.4 / 2008-07-27
+* bugfix: HOME environment variable now correctly detected on windows
+* hooks loaded from both home directory and project directory
+* added bash shell completion
+* plugin architecture for tighter SCM integration, etc
+* 'ditz grep' should also grep against comments, log messages, etc
+* added man page
+* removed ditz-convert-from-monolith
+* lots of HTML output tweaking
+== 0.3 / 2008-06-04
+* readline support for all text entry
+* hook system. Use ditz -l to see possible hooks.
+* new commands: archive, shortlog, set-component
+* improved commands: log, assign, add-release
+* new issue type: 'tasks'
+* 'ditz' by itself shows the todo list
+* zsh tab completion for subcommands
+* local config can now specify bugs directory location
+* issue name interpolation now on all issue fields
+* bugfix: various HTML generation bugs
+* bugfix: ditz now works from project subdirectories
+* bugfix: removed UNIX-specific environment variable assumptions
+== 0.2 / 2008-04-11
+* bugfix: store each issue in a separate file to avoid false conflicts
+* added per-command help
+* added 'log' command for recent activity
+* added better exception handling---turn into pretty error messages
+* added text-area commands like /edit, /reset, etc
+* all times now stored in UTC
+== 0.1.2 / 2008-04-04
+* bugfix: add_reference very broken
+== 0.1.1 / 2008-04-04
+* bugfix: bugfix/feature question always returns feature
+== 0.1 / 2008-04-02
+* Initial release!

data/README.txt

@@ -0,0 +1,127 @@
+== ditz
+
+by William Morgan <wmorgan-ditz at the masanjin dot nets>
+
+http://ditz.rubyforge.org
+
+== DESCRIPTION
+
+Ditz is a simple, light-weight distributed issue tracker designed to work with
+distributed version control systems like git, darcs, Mercurial, and Bazaar. It
+can also be used with centralized systems like SVN.
+
+Ditz maintains an issue database directory on disk, with files written in a
+line-based and human-editable format. This directory can be kept under version
+control, alongside project code.
+
+There are several different ways to use ditz:
+
+1. Treat issue change the same as code change: include it as part of commits,
+   and merge it with changes from other developers, resolving conflicts in the
+   usual manner.
+2. Keep the issue database in the repository but in a separate branch. Issue
+   changes can be managed by your VCS, but is not tied directly to code
+   commits.
+3. Keep the issue database separate and not under VCS at all.
+
+Ditz provides a simple, console-based interface for creating and updating the
+issue database file, and some rudimentary static HTML generation capabilities
+for producing world-readable status pages (for a demo, see the ditz ditz page).
+It currently offers no central public method of bug submission. 
+
+== SYNOPSIS
+
+# set up project. creates the bugs.yaml file.
+1. ditz init
+2. ditz add-release
+
+# add an issue
+3. ditz add
+
+# where am i?
+4. ditz status
+5. ditz todo (or simply "ditz")
+
+# do work
+6. write code
+7. ditz close <issue-id>
+8. commit
+9. goto 3
+
+# finished!
+10. ditz release <release-name>
+
+== THE DITZ DATA MODEL
+
+Ditz includes the bare minimum set of features necessary for open-source
+development. Features like time spent, priority, assignment of tasks to
+developers, due dates, etc. are purposely excluded.
+
+A ditz project consists of issues, releases and components.
+
+Issues:
+  Issues are the fundamental currency of issue tracking. A ditz issue is either
+  a feature or a bug, but this distinction doesn't affect anything other than
+  how they're displayed.
+
+  Each issue belongs to exactly one component, and is part of zero or one
+  releases.
+
+  Each issues has an exportable id, in the form of 40 random hex characters.
+  This id is "guaranteed" to be unique across all possible issues and
+  developers, present and future. Issue ids are typically not exposed to the
+  user.
+
+  Issues also have a non-exportable name, which is short and human-readable.
+  All ditz commands use issue names instead of issue ids. Issue ids may change
+  in certain circumstances, specifically after a "ditz drop" command.
+
+Components:
+  There is always one "general" component, named after the project itself. In
+  the simplest case, this is the only component, and the user is never bothered
+  with the question of which component to assign an issue to.
+
+  Components simply provide a way of organizing issues, and have no real
+  functionality. Issues are assigned names derived form the component they're
+  assigned to.
+
+Releases:
+  A release is the primary grouping mechanism for issues. Status commands like
+  "ditz status" and "ditz todo" always group issues by release. When a release
+  is 100% complete, it can be marked as released, in which case the associated
+  issues will cease appearing in ditz status and todo messages.
+
+== FUTURE WORK
+
+In future releases, Ditz will have a plugin architecture to allow tighter
+integration with specific SCMs and developer communication channels. (See
+http://ditz.rubyforge.org/ditz/issue-0704dafe4aef96279364013aba177a0971d425cb.html)
+
+== LEARNING MORE
+
+* ditz help
+* find $DITZ_INSTALL_DIR -type f | xargs cat
+
+== REQUIREMENTS
+
+* trollop >= 1.8.2
+
+== INSTALLATION
+
+Download tarballs from http://rubyforge.org/projects/ditz/, or command your
+computer to "gem install ditz".
+
+== LICENSE
+
+Copyright (c) 2008 William Morgan.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'hoe'
+
+$:.unshift "lib"
+require 'ditz'
+
+class Hoe
+  def extra_deps; @extra_deps.reject { |x| Array(x).first == "hoe" } end
+end # thanks to "Mike H"
+
+Hoe.new('ditz', Ditz::VERSION) do |p|
+  p.rubyforge_name = 'ditz'
+  p.author = "William Morgan"
+  p.summary = "A simple issue tracker designed to integrate well with distributed version control systems like git and darcs. State is saved to a YAML file kept under version control, allowing issues to be closed/added/modified as part of a commit."
+
+  p.description = p.paragraphs_of('README.txt', 4..11).join("\n\n").gsub(/== SYNOPSIS/, "Synopsis:")
+  p.url = "http://ditz.rubyforge.org"
+  p.changes = p.paragraphs_of('Changelog', 0..0).join("\n\n")
+  p.email = "wmorgan-ditz@masanjin.net"
+end
+
+WWW_FILES = FileList["www/*"] + %w(README.txt)
+
+task :upload_webpage => WWW_FILES do |t|
+  sh "rsync -essh -cavz #{t.prerequisites * ' '} wmorgan@rubyforge.org:/var/www/gforge-projects/ditz/"
+end
+
+task :upload_report do |t|
+  sh "ruby -Ilib bin/ditz html ditz"
+  sh "rsync -essh -cavz ditz wmorgan@rubyforge.org:/var/www/gforge-projects/ditz/"
+end
+
+# vim: syntax=ruby

data/ReleaseNotes

@@ -0,0 +1,50 @@
+0.4
+---
+- Command-line completion scripts are now included for bash and zsh. To
+  activate, source the relevant file in $GEMDIR/ditz-0.4/contrib/completion/.
+
+- Hooks can now be set on a per-project basis. Make a .ditz/hooks directory in
+  your project root and place them there. These will be loaded after any
+  hooks in ~/.ditz/hooks, so they can override or simply supplement.
+
+- The plugin system is done. There's currently one plugin, for git integration.
+  To enable it, add the line "- git" in a .ditz-plugins file in your project
+  root. The git plugin currently has the following features:
+
+  - Issues can have a git branch assigned to them with "ditz set-branch".
+  - Git commit messages can have a Ditz-issue: header auto-filled if you
+    commit with "ditz commit <issue>" (i.e. instead of git commit).
+  - In both HTML and screen output, commits from the assigned branch, and
+    commits with the corresponding Ditz-issue: header in the log message,
+    will be listed for each issue.
+
+  Note that the plugin system is independent of the hook system. In order
+  to auto-add ditz files to the git index upon modification, you must set
+  up hooks. Example hooks for git are at:
+    http://hackety.org/2008/06/26/gitHooksForDitz.html
+
+  Also note that as soon as a feature branch is merged back into master, ditz
+  loses the ability to distinguish its commits. So the Ditz-issue: approach
+  is probably better if you want a long-term record.
+
+0.3
+---
+Ditz now works from project subdirectories, and you can have a .ditz-config in
+the project root for project-specific configuration. (This is not merged with
+the global config, so this file overrides everything in ~/.ditz-config.)
+
+You can specify an :issue_dir key in this file, which can be a relative path to
+the directory containing project.yaml. So if you want to rename that directory,
+or keep it somewhere else, now you can.
+
+There's also a new hook system for plugging in your own code. Run ditz -l to
+see a list of available hooks.
+
+0.2
+---
+
+In ditz 0.2, we store issues per file. This avoids many unnecessary conflicts
+that occur in the single-file case.
+
+To upgrade your bugs.yaml to a bugs/ directory, you must run
+ditz-convert-from-monolith.

data/bin/ditz

@@ -0,0 +1,213 @@
+#!/usr/bin/ruby1.8
+
+## requires are split in two for efficiency reasons: ditz should be really
+## fast when using it for completion.
+$KCODE = "u"
+
+require 'operator'
+op = Ditz::Operator.new
+
+## a secret option for shell completion
+if ARGV.include? '--commands'
+  puts op.class.operations.map { |name, _| name }
+  exit 0
+end
+
+require 'rubygems' rescue LoadError nil
+require 'fileutils'
+require 'pathname'
+require 'trollop'; include Trollop
+require "ditz"
+require "vendor/yaml_waml"
+
+PROJECT_FN = "project.yaml"
+CONFIG_FN = ".ditz-config"
+PLUGIN_FN = ".ditz-plugins"
+
+config_dir = Ditz::find_dir_containing CONFIG_FN
+plugin_dir = Ditz::find_dir_containing PLUGIN_FN
+
+$opts = options do
+  version "ditz #{Ditz::VERSION}"
+  opt :issue_dir, "Issue database dir", :default => "bugs"
+  opt :config_file, "Configuration file", :default => File.join(config_dir || ".", CONFIG_FN)
+  opt :plugins_file, "Plugins file", :default => File.join(plugin_dir || ".", PLUGIN_FN)
+  opt :verbose, "Verbose output", :default => false
+  opt :no_comment, "Skip asking for a comment", :default => false
+  opt :list_hooks, "List all hooks and descriptions, and quit.", :short => 'l', :default => false
+  stop_on_unknown
+end
+
+Ditz::HookManager.register :startup, <<EOS
+Executes at startup
+
+Variables: project, config
+No return value.
+EOS
+
+Ditz::HookManager.register :after_add, <<EOS
+Executes before terminating if new issue files has been created.
+Basically you want to instruct your SCM that these files has
+been added.
+
+Variables: project, config, issues
+No return value.
+EOS
+
+Ditz::HookManager.register :after_delete, <<EOS
+Executes before terminating if new issue files has been deleted.
+Basically you want to instruct your SCM that these files has
+been deleted.
+
+Variables: project, config, issues
+No return value.
+EOS
+
+Ditz::HookManager.register :after_update, <<EOS
+Executes before terminating if new issue files has been updated.
+You may want to instruct your SCM about these changes.
+Note that new issues are not considered updated.
+
+Variables: project, config, issues
+No return value.
+EOS
+
+if $opts[:list_hooks]
+  Ditz::HookManager.print_hooks
+  exit 0
+end
+
+plugins = begin
+  Ditz::debug "loading plugins from #{$opts[:plugins_file]}"
+  YAML::load_file$opts[:plugins_file]
+rescue SystemCallError => e
+  Ditz::debug "can't load plugins file: #{e.message}"
+  []
+end
+
+plugins.each do |p|
+  fn = Ditz::find_ditz_file "plugins/#{p}.rb"
+  Ditz::debug "loading plugin #{p.inspect} from #{fn}"
+  load fn
+end
+
+config = begin
+  Ditz::debug "loading config from #{$opts[:config_file]}"
+  Ditz::Config.from $opts[:config_file]
+rescue SystemCallError => e
+  if ARGV.member? "<options>"
+    ## special case here. if we're asking for tab completion, and the config
+    ## file doesn't exist, don't do the interactive building. just make a
+    ## fake empty one and carry on.
+    Ditz::Config.new
+  else
+    puts <<EOS
+I wasn't able to find a configuration file #{$opts[:config_file]}.
+We'll set it up right now.
+EOS
+    Ditz::Config.create_interactively.save! $opts[:config_file]
+  end
+end
+
+cmd = ARGV.shift || "todo"
+issue_dir = Pathname.new(config.issue_dir || $opts[:issue_dir])
+
+case cmd # some special commands not handled by Ditz::Operator
+when "init"
+  die "#{issue_dir} directory already exists" if issue_dir.exist?
+  issue_dir.mkdir
+  fn = issue_dir + PROJECT_FN
+  project = op.init
+  project.save! fn
+  puts "Ok, #{issue_dir} directory created successfully."
+  exit
+when "help"
+  op.do "help", nil, nil, ARGV
+  exit
+end
+
+project_root = Ditz::find_dir_containing(issue_dir + PROJECT_FN)
+die "No #{issue_dir} directory---use 'ditz init' to initialize" unless project_root
+project_root += issue_dir
+
+project = begin
+  fn = project_root + PROJECT_FN
+  Ditz::debug "loading project from #{fn}"
+  project = Ditz::Project.from fn
+
+  fn = project_root + "issue-*.yaml"
+  Ditz::debug "loading issues from #{fn}"
+  project.issues = Dir[fn].map { |fn| Ditz::Issue.from fn }
+  Ditz::debug "found #{project.issues.size} issues"
+  project
+rescue SystemCallError, Ditz::Project::Error => e
+  die "#{e.message} (use 'init' to initialize)"
+end
+
+project.validate!
+project.issues.each { |p| p.project = project}
+project.assign_issue_names!
+
+unless op.has_operation? cmd
+  die "no such command: #{cmd}"
+end
+
+Ditz::HookManager.run :startup, project, config
+
+Ditz::debug "executing command #{cmd}"
+begin
+  op.do cmd, project, config, ARGV
+rescue Ditz::Operator::Error, Ditz::Release::Error, Ditz::Project::Error, Ditz::Issue::Error => e
+  $stderr.puts "Error: #{e.message}"
+  exit(-1)
+rescue Errno::EPIPE, Interrupt
+  puts
+  exit 1
+end
+
+## save project.yaml
+dirty = project.each_modelobject { |o| break true if o.changed? } || false
+if dirty
+  fn = project_root + PROJECT_FN
+  Ditz::debug "project is dirty, saving #{fn}"
+  project.save! fn
+end
+
+## project issues are not model fields proper, so they must be
+## saved independently.
+changed_issues = project.issues.select { |i| i.changed? }
+changed_issues.each do |i|
+  i.pathname ||= (project_root + "issue-#{i.id}.yaml")
+  i.project ||= project # hack: not set on new issues
+  Ditz::debug "issue #{i.name} is dirty, saving #{i.pathname}"
+  i.save! i.pathname
+end
+
+project.deleted_issues.each do |i|
+  fn = i.pathname
+  Ditz::debug "issue #{i.name} has been deleted, deleting #{fn}"
+  FileUtils.rm fn
+end
+
+unless project.added_issues.empty?
+  unless Ditz::HookManager.run :after_add, project, config, project.added_issues
+    puts "You may have to inform your SCM that the following files have been added:"
+    project.added_issues.each { |i| puts "  " + i.pathname }
+  end
+end
+
+unless project.deleted_issues.empty?
+  unless Ditz::HookManager.run :after_delete, project, config, project.deleted_issues
+    puts "You may have to inform your SCM that the following files have been deleted:"
+    project.deleted_issues.each { |i| puts "  " + i.pathname }
+  end
+end
+
+changed_not_added_issues = changed_issues - project.added_issues
+unless changed_not_added_issues.empty?
+  Ditz::HookManager.run :after_update, project, config, changed_not_added_issues
+end
+
+config.save! $opts[:config_file] if config.changed?
+
+# vim: syntax=ruby

data/contrib/completion/_ditz.zsh

@@ -0,0 +1,29 @@
+#compdef ditz
+
+ME=ditz
+COMMANDS=--commands
+OPTIONS='<options>'
+
+if (($CURRENT == 2)); then
+  # We're completing the first word after the tool: the command.
+  _wanted command expl "$ME command" \
+    compadd -- $( "$ME" "$COMMANDS" )
+else
+  # Find the options/files/URL/etc. for the current command by using the tool itself.
+      case "${words[$CURRENT]}"; in
+        -*)
+          _wanted args expl "Arguments for $ME ${words[2]}" \
+             compadd -- $( "$ME" "${words[2]}" "$OPTIONS" ; _files )
+            ;;
+        ht*|ft*)
+            _arguments '*:URL:_urls'
+            ;;
+        /*|./*|\~*|../*)
+            _arguments '*:file:_files'
+            ;;
+        *)
+          _wanted args expl "Arguments for $ME ${words[2]}" \
+             compadd -- $( "$ME" "${words[2]}" "$OPTIONS" )
+          ;;
+      esac
+fi

data/contrib/completion/ditz.bash

@@ -0,0 +1,22 @@
+# ditz bash completion
+#
+# author: Christian Garbs
+#
+# based on bzr.simple by Martin Pool
+
+_ditz() 
+{
+    cur=${COMP_WORDS[COMP_CWORD]}
+    if [ $COMP_CWORD -eq 1 ]; then
+	COMPREPLY=( $( compgen -W "$(ditz --commands)" $cur ) )
+    elif [ $COMP_CWORD -eq 2 ]; then
+	cmd=${COMP_WORDS[1]}
+	COMPREPLY=( $( compgen -W "$(ditz "$cmd" '<options>' 2>/dev/null)" $cur ) )
+    elif [ $COMP_CWORD -eq 3 ]; then
+	cmd=${COMP_WORDS[1]}
+	parm1=${COMP_WORDS[2]}
+	COMPREPLY=( $( compgen -W "$(ditz "$cmd" "$parm1" '<options>' 2>/dev/null)" $cur ) )
+    fi 
+}
+
+complete -F _ditz -o default ditz

data/lib/component.rhtml

@@ -0,0 +1,22 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Component <%= component.name %></title>
+<meta http-equiv="Content-Type" content="text/html; charset=utf8" />
+<link rel="stylesheet" href="style.css" type="text/css" />
+</head>
+
+<body>
+
+<div><%= link_to "index", "&laquo; #{project.name} project page" %></div>
+
+<h1><%= project.name %> component: <%= component.name %></h1>
+
+<%= render "issue_table", :show_component => false, :show_release => true %>
+
+<p class="footer">Generated by <a
+href="http://ditz.rubyforge.org/">ditz</a>.</p>
+</body>
+</html>

data/lib/ditz.rb

@@ -0,0 +1,56 @@
+module Ditz
+
+VERSION = "0.4"
+
+def debug s
+  puts "# #{s}" if $opts[:verbose]
+end
+module_function :debug
+
+def self.has_readline?
+  @has_readline
+end
+
+def self.has_readline= val
+  @has_readline = val
+end
+
+begin
+  Ditz::has_readline = false
+  require 'readline'
+  Ditz::has_readline = true
+rescue LoadError
+  # do nothing
+end
+
+def home_dir
+  @home ||=
+    ENV["HOME"] || (ENV["HOMEDRIVE"] && ENV["HOMEPATH"] ? ENV["HOMEDRIVE"] + ENV["HOMEPATH"] : nil) || begin
+    $stderr.puts "warning: can't determine home directory, using '.'"
+    "."
+  end
+end
+
+## helper for recursive search
+def find_dir_containing target, start=Pathname.new(".")
+  return start if (start + target).exist?
+  unless start.parent.realpath == start.realpath
+    find_dir_containing target, start.parent
+  end
+end
+
+## my brilliant solution to the 'gem datadir' problem
+def find_ditz_file fn
+  dir = $:.find { |p| File.exist? File.expand_path(File.join(p, fn)) }
+  raise "can't find #{fn} in any load path" unless dir
+  File.expand_path File.join(dir, fn)
+end
+
+module_function :home_dir, :find_dir_containing, :find_ditz_file
+end
+
+require 'model-objects'
+require 'operator'
+require 'views'
+require 'hook'
+

data/lib/hook.rb

@@ -0,0 +1,67 @@
+module Ditz
+  class HookManager
+    def initialize
+      @descs = {}
+      @blocks = {}
+    end
+
+    @@instance = nil
+    def self.method_missing m, *a, &b
+      @@instance ||= self.new
+      @@instance.send m, *a, &b
+    end
+
+    def register name, desc
+      @descs[name] = desc
+      @blocks[name] = []
+    end
+
+    def on *names, &block
+      names.each do |name|
+        raise "unregistered hook #{name.inspect}" unless @descs[name]
+        @blocks[name] << block
+      end
+    end
+
+    def run name, *args
+      raise "unregistered hook #{name.inspect}" unless @descs[name]
+      blocks = hooks_for name
+      return false if blocks.empty?
+      blocks.each { |block| block[*args] }
+      true
+    end
+
+    def print_hooks f=$stdout
+puts <<EOS
+Ditz has #{@descs.size} registered hooks:
+
+EOS
+
+      @descs.map{ |k,v| [k.to_s,v] }.sort.each do |name, desc|
+        f.puts <<EOS
+#{name}
+#{"-" * name.length}
+#{desc}
+EOS
+      end
+    end
+
+    def enabled? name; !hooks_for(name).empty? end
+
+    def hooks_for name
+      if @blocks[name].nil? || @blocks[name].empty?
+        dirs = [Ditz::home_dir, Ditz::find_dir_containing(".ditz")].compact.map do |d|
+          File.join d, ".ditz", "hooks"
+        end
+        Ditz::debug "looking for hooks in #{dirs.join(" and ")}"
+        files = dirs.map { |d| Dir[File.join(d, "*.rb")] }.flatten
+        files.each do |fn|
+          Ditz::debug "loading hook file #{fn}"
+          load fn
+        end
+      end
+
+      @blocks[name] || []
+    end
+  end
+end