ursm-ditz 0.4 → 0.5

data/Manifest.txt

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

data/PLUGINS.txt

@@ -0,0 +1,140 @@
+Ditz plugin documentation
+-------------------------
+
+Ditz features a code plugin system for adding and extending commands, fields,
+and output. Ditz's plugin system is used to add optional functionality to Ditz.
+
+If you're interested in writing a plugin, look at the simple plugins in
+lib/ditz/plugin/, and see
+  http://all-thing.net/2008/07/ditz-04-and-magic-of-ruby-dsls.html
+If you're interested using plugins, read on.
+
+Ditz loads specific plugins by looking for a .ditz-plugins file in the project
+root. The format of this file is a YAML array of strings, where each string is
+a plugin name. You can write this by hand like this:
+
+  - my-plugin
+  - another-plugin
+
+I.e. one plugin name per line, prefixed by "- " as the first two characters of each line.
+
+For each listed plugin name, Ditz looks for a file named
+"lib/ditz/plugin/<name>.rb" within Ruby's default search path. Assuming Ditz is
+installed in a standard manner, you should have available to you the following
+shipped plugins:
+
+1. git
+2. git-sync
+3. issue-claiming
+4. issue-labeling
+
+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
+
+issue-labeling
+--------------
+
+This plugin allows label issues. This can replace the issue component
+and/or issue types (bug,feature,task), by providing a more flexible
+to organize your issues.
+
+Commands added:
+  ditz new_label [label]: create a new label for the project
+  ditz label <issue> <labels>: label an issue with some labels
+  ditz unlabel <issue> [labels]: remove some label(s) of an issue
+  ditz labeled <labels> [release]: show all issues with these labels
+
+Usage:
+  1. add a line "- issue-labeling" to the .ditz-plugins file in the project
+     root
+  2. use the above commands to abandon
+

data/README.txt

@@ -14,7 +14,18 @@ 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:
+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).
+
+Ditz includes a robust plugin system for adding commands, model fields, and
+modifying output. See PLUGINS.txt for documentation on the pre-shipped plugins.
+
+Ditz 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
@@ -24,12 +35,18 @@ There are several different ways to use ditz:
    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. 
+All of these options are supported; the choice of which to use depends on your
+workflow.
+
+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.
 
-== SYNOPSIS
+== COMMANDLINE SYNOPSIS
 
 # set up project. creates the bugs.yaml file.
 1. ditz init
@@ -53,16 +70,17 @@ It currently offers no central public 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.
@@ -72,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
@@ -82,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
 
@@ -104,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

@@ -5,8 +5,8 @@ $:.unshift "lib"
 require 'ditz'
 
 class Hoe
-  def extra_deps; @extra_deps.reject { |x| Array(x).first == "hoe" } end
-end # thanks to "Mike H"
+  def extra_dev_deps; @extra_dev_deps.reject { |x| x[0] == "hoe" } end
+end
 
 Hoe.new('ditz', Ditz::VERSION) do |p|
   p.rubyforge_name = 'ditz'
@@ -17,9 +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.9'], ['kakutani-yaml_waml', '>= 0.3']]
 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/"
@@ -30,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,10 +1,12 @@
 #!/usr/bin/ruby1.8
 
+$LOAD_PATH.unshift(File.expand_path("#{File.dirname($0)}/../lib"))
+
 ## requires are split in two for efficiency reasons: ditz should be really
 ## fast when using it for completion.
 $KCODE = "u"
 
-require 'operator'
+require 'ditz/operator'
 op = Ditz::Operator.new
 
 ## a secret option for shell completion
@@ -13,14 +15,19 @@ if ARGV.include? '--commands'
   exit 0
 end
 
-require 'rubygems' rescue LoadError nil
+begin
+  require 'rubygems'
+  # list version dependant gems here.
+  gem 'kakutani-yaml_waml', '>= 0.3'
+  gem 'trollop', '>= 1.9'
+rescue LoadError
+end
+
 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"
 
@@ -33,10 +40,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
@@ -77,18 +84,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
@@ -109,49 +108,40 @@ 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."
   exit
+when "reconfigure" # might not be able to load the project
+  op.do cmd, nil, config, ARGV
+  exit
 when "help"
-  op.do "help", nil, nil, ARGV
+  op.do cmd, 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_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
 
 Ditz::debug "executing command #{cmd}"
@@ -165,47 +155,43 @@ rescue Errno::EPIPE, Interrupt
   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?