Metadata-Version: 1.1
Name: pyditz
Version: 0.5.1
Summary: Python implementation of Ditz (http://ditz.rubyforge.org).
Home-page: http://pypi.python.org/pypi/pyditz
Author: Glenn Hutchings
Author-email: zondo42@gmail.com
License: GPL v2 or later
Description: .. README for PyDitz, in -*- rst -*- mode.
        
        ========
         PyDitz
        ========
        
        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?
        ====================
        
        To install and run it:
            PyYAML_ and Jinja_
        
        To run the test suite:
            Nose_, Mock_ and Coverage_
        
        To build source distributions:
            setuptools_hg_
        
        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:
        
        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.
        
        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>.
        
        .. _Ditz: http://ditz.rubyforge.org
        .. _PyYAML: https://pypi.python.org/pypi/PyYAML
        .. _Jinja: http://jinja.pocoo.org
        .. _Nose: https://pypi.python.org/pypi/nose
        .. _Mock: https://pypi.python.org/pypi/mock
        .. _Coverage: https://pypi.python.org/pypi/coverage
        .. _reStructuredText: http://docutils.sourceforge.net/rst
        .. _rst2pdf: https://pypi.python.org/pypi/rst2pdf
        .. _PyDitz: https://bitbucket.org/zondo/pyditz
        .. _Cmd: http://docs.python.org/2.7/library/cmd
        .. _PEP8: http://www.python.org/dev/peps/pep-0008
        .. _flake8: https://pypi.python.org/pypi/flake8
        .. _setuptools_hg: https://bitbucket.org/jezdez/setuptools_hg
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Bug Tracking
