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