Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
141 lines (112 sloc) 5.52 KB
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