ditz 0.4 → 0.5

data/Manifest.txt

@@ -0,0 +1,42 @@
+Changelog
+INSTALL
+LICENSE
+Manifest.txt
+PLUGINS.txt
+README.txt
+Rakefile
+ReleaseNotes
+bin/ditz
+contrib/completion/_ditz.zsh
+contrib/completion/ditz.bash
+lib/blue-check.png
+lib/component.rhtml
+lib/ditz.rb
+lib/file-storage.rb
+lib/green-bar.png
+lib/green-check.png
+lib/hook.rb
+lib/html.rb
+lib/index.rhtml
+lib/issue.rhtml
+lib/issue_table.rhtml
+lib/lowline.rb
+lib/model-objects.rb
+lib/model.rb
+lib/operator.rb
+lib/plugins/git-sync.rb
+lib/plugins/git.rb
+lib/plugins/issue-claiming.rb
+lib/red-check.png
+lib/release.rhtml
+lib/style.css
+lib/trollop.rb
+lib/unassigned.rhtml
+lib/util.rb
+lib/view.rb
+lib/views.rb
+lib/yellow-bar.png
+man/ditz.1
+setup.rb
+www/index.html
+www/main.css

data/PLUGINS.txt

@@ -0,0 +1,99 @@
+Ditz plugin documentation
+
+Shipped plugins:
+1. git
+2. git-sync
+3. issue-claiming
+
+git
+---
+
+This plugin allows issues to be associated with git commits and git
+branches.  Git commits can be easily tagged with a ditz issue with the 'ditz
+commit' command, and both 'ditz show' and the ditz HTML output will then
+contain a list of associated commits for each issue.
+
+Issues can also be assigned a single git feature branch. In this case, all
+commits on that branch will listed as commits for that issue. This
+particular feature is fairly rudimentary, however---it assumes the reference
+point is the 'master' branch, and once the feature branch is merged back
+into master, the list of commits disappears.
+
+Two configuration variables are added, which, when specified, are used to
+construct HTML links for the git commit id and branch names in the generated
+HTML output.
+
+Commands added:
+  ditz set-branch: set the git branch of an issue
+  ditz commit: run git-commit, and insert the issue id into the commit
+    message.
+
+Usage: 
+  1. add a line "- git" to the .ditz-plugins file in the project root
+  2. run ditz reconfigure, and enter the URL prefixes, if any, from
+     which to create commit and branch links.
+  3. use 'ditz commit' with abandon.
+
+git-sync
+--------
+
+This plugin is useful for when you want synchronized, non-distributed issue
+coordination with other developers, and you're using git. It allows you to
+synchronize issue updates with other developers by using the 'ditz sync'
+command, which does all the git work of sending and receiving issue change
+for you. However, you have to set things up in a very specific way for this
+to work:
+
+1. Your ditz state must be on a separate branch. I recommend calling it
+   'bugs'. Create this branch, do a ditz init, and push it to the remote
+   repo. (This means you won't be able to mingle issue change and code
+   change in the same commits. If you care.)
+2. Make a checkout of the bugs branch in a separate directory, but NOT in
+   your code checkout. If you're developing in a directory called "project",
+   I recommend making a ../project-bugs/ directory, cloning the repo there
+   as well, and keeping that directory checked out to the 'bugs' branch.
+   (There are various complicated things you can do to make that directory
+   share git objects with your code directory, but I wouldn't bother unless
+   you really care about disk space. Just make it an independent clone.)
+3. Set that directory as your issue-dir in your .ditz-config file in your
+   code checkout directory. (This file should be in .gitignore, btw.)
+4. Run 'ditz reconfigure' and fill in the local branch name, remote
+   branch name, and remote repo for the issue tracking branch.
+
+Once that's set up, 'ditz sync' will change to the bugs checkout dir, bundle
+up any changes you've made to issue status, push them to the remote repo,
+and pull any new changes in too. All ditz commands will read from your bugs
+directory, so you should be able to use ditz without caring about where
+things are anymore.
+
+This complicated setup is necessary to avoid accidentally mingling code
+change and issue change. With this setup, issue change is synchronized,
+but how you synchronize code is still up to you.
+
+Usage:
+  0. read all the above text very carefully
+  1. add a line "- git-sync" to the .ditz-plugins file in the project
+     root
+  2. run 'ditz reconfigure' and answer its questions
+  3. run 'ditz sync' with abandon
+
+issue-claiming
+--------------
+
+This plugin allows people to claim issues. This is useful for avoiding
+duplication of work---you can check to see if someone's claimed an
+issue before starting to work on it, and you can let people know what
+you're working on.
+
+Commands added:
+  ditz claim: claim an issue for yourself
+  ditz unclaim: unclaim a claimed issue
+  ditz mine: show all issues claimed by you
+  ditz claimed: show all claimed issues, by developer
+  ditz unclaimed: show all unclaimed issues
+
+Usage:
+  1. add a line "- issue-claiming" to the .ditz-plugins file in the project
+     root
+  2. use the above commands to abandon
+

data/README.txt

@@ -1,6 +1,6 @@
 == ditz
 
-by William Morgan <wmorgan-ditz@masanjin.net>
+by William Morgan <wmorgan-ditz at the masanjin dot nets>
 
 http://ditz.rubyforge.org
 
@@ -14,23 +14,39 @@ 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 different ways to use ditz:
+Ditz provides a simple, console-based interface for creating and updating the
+issue database files, and some basic static HTML generation capabilities for
+producing world-readable status pages (for a demo, see the ditz ditz page).
 
- 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 commits.
- 3. Keep the issue database separate and not under VCS at all.
+Ditz includes a robust plugin system for adding commands, model fields, and
+modifying output. See PLUGINS.txt for documentation on the pre-shipped plugins.
 
-Your particular usage will depend on what you want to get out of ditz.
+Ditz currently offers no central public method of bug submission. 
 
-Ditz provides a simple, console-based interface for creating and updating the
-issue database file, and some rudimentary HTML generation capabilities for
-producing world-readable status pages. It currently offers no central public
-method of bug submission.
+== USING DITZ
+
+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.
+
+All of these options are supported; the choice of which to use depends on your
+workflow.
 
-== SYNOPSIS
+Option #1 is probably most appropriate for the unsynchronized, distributed
+development, since it allows individual developers to modify issue state with a
+minimum of hassle. Option #2 is most suitable for synchronized development, as
+issue state change can be transmitted independently of code change (see also
+the git-sync plugin) and can act as a sychronization mechanism. Option #3 is
+only useful with some other distribution mechanism, like a central web
+interface.
+
+== COMMANDLINE SYNOPSIS
 
 # set up project. creates the bugs.yaml file.
 1. ditz init
@@ -54,16 +70,17 @@ method of bug submission.
 
 == 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.
+By default, 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 relegated to the plugin
+system.
 
-A ditz project consists of issues, releases and components.
+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.
+  Issues are the fundamental currency of issue tracking. A Ditz issue is either
+  a feature or a bug, but this distinction currently 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.
@@ -73,9 +90,13 @@ Issues:
   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.
+  Issues also have a non-global, non-exportable name, which is short and
+  human-readable. All Ditz commands use issue names in addition to issue ids.
+  Issue names (but not issue ids) may change in certain circumstances, e.g.
+  after a "ditz drop" command.
+
+  Issue names can be specified in comments, titles and descriptions, and Ditz
+  will automatically rewrite them as necessary when they change.
 
 Components:
   There is always one "general" component, named after the project itself. In
@@ -83,20 +104,14 @@ Components:
   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.
+  functionality. Issues names are derived from 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)
+  is 100% complete, it can be marked as released, and its issues will cease
+  appearing in Ditz status and todo messages.
 
 == LEARNING MORE
 
@@ -105,7 +120,7 @@ http://ditz.rubyforge.org/ditz/issue-0704dafe4aef96279364013aba177a0971d425cb.ht
 
 == REQUIREMENTS
 
-* trollop >= 1.8.2
+* trollop >= 1.8.2, if running via RubyGems.
 
 == INSTALLATION
 

data/Rakefile

@@ -17,10 +17,10 @@ Hoe.new('ditz', Ditz::VERSION) do |p|
   p.url = "http://ditz.rubyforge.org"
   p.changes = p.paragraphs_of('Changelog', 0..0).join("\n\n")
   p.email = "wmorgan-ditz@masanjin.net"
-  p.extra_deps = [['trollop', '>= 1.8.2']]
+  p.extra_deps = [['trollop', '>= 1.9']]
 end
 
-WWW_FILES = FileList["www/*"] + %w(README.txt)
+WWW_FILES = FileList["www/*"] + %w(README.txt PLUGINS.txt)
 
 task :upload_webpage => WWW_FILES do |t|
   sh "rsync -essh -cavz #{t.prerequisites * ' '} wmorgan@rubyforge.org:/var/www/gforge-projects/ditz/"
@@ -31,4 +31,36 @@ task :upload_report do |t|
   sh "rsync -essh -cavz ditz wmorgan@rubyforge.org:/var/www/gforge-projects/ditz/"
 end
 
+task :plugins  do |t|
+  sh "ruby -w ./make-plugins.txt.rb > PLUGINS.txt"
+end
+
+task :really_check_manifest do |t|
+  f1 = Tempfile.new "manifest"; f1.close
+  f2 = Tempfile.new "manifest"; f2.close
+  sh "git ls-files | egrep -v \"^bugs/\" | sort > #{f1.path}"
+  sh "sort Manifest.txt > #{f2.path}"
+
+  f3 = Tempfile.new "manifest"; f3.close
+  sh "diff -u #{f1.path} #{f2.path} > #{f3.path}; /bin/true"
+
+  left, right = [], []
+  IO.foreach(f3.path) do |l|
+    case l
+    when /^\-\-\-/
+    when /^\+\+\+/
+    when /^\-(.*)\n$/; left << $1
+    when /^\+(.*)\n$/; right << $2
+    end
+  end
+
+  puts
+  puts "Tracked by git but not in Manifest.txt:"
+  puts left.empty? ? "  <nothing>" : left.map { |l| "  " + l }
+
+  puts
+  puts "In Manifest.txt, but not tracked by git:"
+  puts right.empty? ? "  <nothing>" : right.map { |l| "  " + l }
+end
+
 # vim: syntax=ruby

data/ReleaseNotes

@@ -1,3 +1,9 @@
+0.5
+---
+
+Two new plugins: git-sync, for synchronized git usage, and issue-claiming,
+which allows you to claim issues for yourself. See PLUGINS.txt for details.
+
 0.4
 ---
 - Command-line completion scripts are now included for bash and zsh. To

data/bin/ditz

@@ -1,4 +1,4 @@
-#!/usr/bin/env ruby
+#!/usr/bin/ruby1.8
 
 ## requires are split in two for efficiency reasons: ditz should be really
 ## fast when using it for completion.
@@ -11,13 +11,16 @@ if ARGV.include? '--commands'
   exit 0
 end
 
-require 'rubygems'
+begin
+  require 'rubygems'
+rescue LoadError
+end
+
 require 'fileutils'
 require 'pathname'
 require 'trollop'; include Trollop
 require "ditz"
 
-PROJECT_FN = "project.yaml"
 CONFIG_FN = ".ditz-config"
 PLUGIN_FN = ".ditz-plugins"
 
@@ -30,9 +33,10 @@ $opts = options do
   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
+$verbose = true if $opts[:verbose]
 
 Ditz::HookManager.register :startup, <<EOS
 Executes at startup
@@ -73,18 +77,10 @@ if $opts[:list_hooks]
   exit 0
 end
 
-plugins = begin
-  Ditz::debug "loading plugins from #{$opts[:plugins_file]}"
-  YAML::load_file$opts[:plugins_file]
+begin
+  Ditz::load_plugins $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
@@ -105,14 +101,17 @@ EOS
   end
 end
 
-cmd = ARGV.shift || "todo"
 issue_dir = Pathname.new(config.issue_dir || $opts[:issue_dir])
+cmd = ARGV.shift || "todo"
+unless op.has_operation? cmd
+  die "no such command: #{cmd}"
+end
 
 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
+  fn = issue_dir + Ditz::FileStorage::PROJECT_FN
   project = op.init
   project.save! fn
   puts "Ok, #{issue_dir} directory created successfully."
@@ -122,89 +121,67 @@ when "help"
   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_root = Ditz::find_dir_containing(issue_dir + Ditz::FileStorage::PROJECT_FN)
+die "No #{issue_dir} directory---use 'ditz init' to initialize" unless $project_root
+$project_root += issue_dir
 
+storage = Ditz::FileStorage.new $project_root
 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
+  storage.load
 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
 
-## talk about the law of unintended consequences. 'gets' requires this.
-args = []
-args << ARGV.shift until ARGV.empty?
-
 Ditz::debug "executing command #{cmd}"
 begin
-  op.do cmd, project, config, args
-rescue Ditz::Operator::Error => e
-  die e.message
+  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
+changed_not_added_issues = changed_issues - project.added_issues
 
-project.deleted_issues.each do |i|
-  fn = i.pathname
-  Ditz::debug "issue #{i.name} has been deleted, deleting #{fn}"
-  FileUtils.rm fn
-end
+storage.save project
+
+## at this point, for compatibility with older hook stuff, we set the pathname
+## directly on the issues.
 
+project.issues.each { |i| i.pathname = storage.filename_for_issue(i) }
 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 }
+    project.added_issues.each { |i| puts "  " + storage.filename_for_issue(i) }
   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 }
+    project.deleted_issues.each { |i| puts "  " + storage.filename_for_issue(i) }
   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
+  unless Ditz::HookManager.run :after_update, project, config, changed_not_added_issues
+    puts "You may have to inform your SCM that the following files have been modified:"
+    changed_not_added_issues.each { |i| puts "  " + storage.filename_for_issue(i) }
+  end
+end
+
+## hack upon a hack
+if project.changed?
+  project.pathname = storage.filename_for_project
+  unless Ditz::HookManager.run :after_update, project, config, [project]
+    puts "You may have to inform your SCM that the following files have been modified:"
+    puts "  " + storage.filename_for_project
+  end
 end
 
 config.save! $opts[:config_file] if config.changed?