Python implementation of Ditz (http://ditz.rubyforge.org).
Project description
What’s this all about?
This package is intended to be a drop-in replacement for the Ditz distributed issue tracker. It provides a pyditz command-line program, which acts (mostly) the same way as ditz, and it adds several other nice things too:
Whereas ditz, when typed on its own, runs the todo command, pyditz drops you into a command shell where you can run Ditz commands and get completion on command names, issue names and release names according to context.
With pyditz, you don’t have to run it from the same directory where the issue database is; it will look in parent directories for it.
It keeps an intelligent cache of issues, so parsing of all the YAML files isn’t necessary for each command. This greatly improves speed when you have lots of issues.
You can use the database engine of PyDitz in Python programs to migrate bug databases to and from Ditz format, or create summary reports in your own favourite format. Me, I prefer reStructuredText and rst2pdf.
How complete is it?
All the existing Ditz commands are implemented, with the following exceptions:
- edit
In Ditz, this invoked vi (or another editor defined by the EDITOR environment variable) to edit the raw YAML source of an issue. I have plans to do something similar, or knock up a Tkinter graphical edit window.
- validate
I’m guessing this is supposed to somehow check the integrity of the database. In Ditz it’s a no-op. No plans to do anything with this at the moment.
It’s also missing some decent program and database API documentation (coming soon).
What else do I need?
How do I use it?
Here’s an edited part of the README file from the original Ditz.
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.
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.
Ditz includes a robust plugin system for adding commands, model fields, and modifying output. Note: PyDitz doesn’t yet have this!
Ditz currently offers no central public method of bug submission.
Using Ditz
There are several different ways to use Ditz:
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.
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.
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.
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, 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:
ditz init ditz add-release
Add an issue:
ditz add
Where am i?
ditz status ditz todo
Do work:
write code ditz close <issue-id> commit
Finished!
ditz release <release-name>
The Ditz Data Model
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, components and releases.
- Issues
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.
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-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 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 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, and its issues will cease appearing in Ditz status and todo messages.
What other stuff should I know about?
PyDitz gives a few more customization options than Ditz, by the use of a per-user configuration file called .ditzrc in your home directory. At the moment this just controls the number of “activity” events reported on the HTML index and issue pages. Here’s the default settings:
# pyditz v0.5 configuration file. [html] index_events = 10 release_events = 10
No doubt the number of entries here will increase as development continues.
Why did you rewrite Ditz in Python?
Good question. Here are a few answers:
I didn’t intend to. I originally wanted a way to summarize the status of a particular Ditz project in a printable, non-HTML way. I tried to learn Ruby to the extent that I could hack together what I wanted, but in the end I decided it was easier to go with Python and PyYAML.
That was it for a while: a simple module that read issues in a Ditz database. Then I discovered the Cmd module in the standard library, and wondered what I could do with it. And here we are.
A modular Python implementation enables a whole load of Ditz interfacing possibilities with other Python modules I haven’t even considered. Most of which I hope other people develop.
Programming is fun!
Can I join in with this?
By all means. Grab the PyDitz code base on Bitbucket and go for it. Here’s a few guidelines:
If you decide to work on one of the not-yet-implemented commands (see above), let me know. No point in duplicating work!
Source formatting should follow PEP8. I use flake8 to make sure.
Any new features should have a corresponding unit test in the tests directory.
Having said all that, I will gladly accept any patches. I am Glenn Hutchings <zondo42@gmail.com>.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
