Metadata-Version: 2.4
Name: bugzillatools
Version: 0.5.5
Summary: Bugzilla CLI client, XML-RPC binding and VCS plugins
Home-page: https://github.com/frasertweedale/bugzillatools
Author: Fraser Tweedale
Author-email: frase@frase.id.au
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Software Development :: Version Control
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: summary

bugzillatools consists of the ``bugzilla`` CLI program and a Python
library for interacting with the Bugzilla_ bug tracking system, and
plugins for version control systems that enable interaction with
Bugzilla installations.

The only dependency is Python_ 2.7 and bugzillatools works with
Bugzilla_ 4.0 or later where the XML-RPC feature is enabled.

.. _Bugzilla: http://www.bugzilla.org/
.. _Python: http://python.org/


Installation
============

::

  # via pip
  pip install bugzillatools         # as superuser
    -or-
  pip install bugzillatools --user  # user site-packages installation

  # from source
  python setup.py install           # as superuser
    -or-
  python setup.py install --user    # user site-packages installation

The ``bin/`` directory in your user base directory will need to appear
on the ``PATH`` if installing to user site-packages.  This directory is
system dependent; see :pep:`370`.

If installing to user site-packages, some manual moving or symlinking
of files will be required for the Bazaar plugin to be detected by
Bazaar.  :pep:`402` speaks to this shortcoming.


Components
==========

``bugzilla`` program
--------------------

Command-line application for interacting with Bugzilla servers.
The following subcommands are available:

:assign:              Assign bugs to the given user.
:block:               Show or update block list of given bugs.
:cc:                  Show or update CC List.
:comment:             List comments or file a comment on the given bugs.
:config:              Show or update configuration.
:depend:              Show or update dependencies of given bugs.
:desc:                Show the description of the given bug(s).
:dump:                Print internal representation of bug data.
:edit:                Edit the given bugs.
:fields:              List valid values for bug fields.
:help:                Show help.
:history:             Show the history of the given bugs.
:info:                Show detailed information about the given bugs.
:list:                Show a one-line summary of the given bugs.
:new:                 File a new bug.
:priority:            Set the priority on the given bugs.
:products:            List the products of a Bugzilla instance.
:search:              Search for bugs matching given criteria.
:status:              Set the status of the given bugs.
:time:                Show or adjust times and estimates for the given bugs.


``bzlib``
---------

Library providing access to Bugzilla instances through the XML-RPC
interface.  Supports bug creation, bug information and comment
retrieval, updating bug fields and appending comments to bugs.


Bazaar_ plugin
--------------

This plugin, when enabled for Bugzilla bugtrackers, marks bugs fixed on
those trackers when ``bzr commit`` is invoked with the ``--fixes`` argument.
It also adds a comment to the bug that includes the branch location, the
commit message, the list of changed files and other details about the commit.

The Bazaar_ plugin requires Bazaar 2.0 or later.

.. _Bazaar: http://bazaar.canonical.com/


Configuration
=============

``.bugzillarc``
---------------

The ``bugzilla`` program looks for its configuration in
``~/.bugzillarc``, which uses ini-style configuration.

``core``
^^^^^^^^

``server``
  Name of the default server

``alias``
^^^^^^^^^

Option names are aliases; their values are the replacement.

``server.<name>``
^^^^^^^^^^^^^^^^^

Define a server.  bugzillatools supports multiple servers; the
``--server=<name>`` argument can be used to select a server.

``url``
  Base URL of the Bugzilla server (mandatory)
``user``
  Bugzilla username (optional)
``password``
  Bugzilla password (optional)
``assign_status``
  When the ``assign`` command is used, if the current status of a bug
  is in the first list, the status will be updated to the second item.
  The format is: ``<oldstatus>[,<oldstatus>]* <newstatus>``.  An
  appropriate value for the default Bugzilla workflow might be:
  ``"UNCONFIRMED,CONFIRMED IN_PROGRESS"``.
``default_product``
  If provided and if the provided string corresponds to the name of a
  product on this server, use that product as the default.  The user
  will still be prompted to confirm.


Example ``.bugzillarc``
^^^^^^^^^^^^^^^^^^^^^^^

::

  [core]
  server = example

  [server.example]
  url = http://bugzilla.example.com
  user = user@example.com
  password = sekrit

  [alias]
  fix = status --status RESOLVED --resolution FIXED
  wfm = status --status RESOLVED --resolution WORKSFORME
  confirm = status --status CONFIRMED


Bazaar plugin
-------------

To enable the Bazaar bugzillatools plugin, include following
configuration directives in either ``~/.bazaar/bazaar.conf`` (global
configuration) or ``.bzr/branch/branch.conf`` (within a branch)::

  bugzilla_<server>_bugzillatools_enable = True
  bugzilla_<server>_url = <bugzilla url>
  bugzilla_<server>_status = RESOLVED
  bugzilla_<server>_resolution = FIXED

Such a configuration assumes that a section ``[server.<server>]``
has been defined in your ``.bugzillarc``.

You can now set the status of bugs (using the status and resolution
defined in the Bazaar config) directly::

  bzr commit -m 'fix bug 123' --fixes <server>:123


License
=======

bugzillatools is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.


Contributing
============

The bugzillatools source code is available from
https://github.com/frasertweedale/bugzillatools.

Bug reports, patches, feature requests, code review and
documentation are welcomed.

To submit a patch, please use ``git send-email`` or generate a pull
request.  Write a `well formed commit message`_.  If your patch is
nontrivial, update the copyright notice at the top of each changed
file.

.. _well formed commit message: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html


Changelog
=========

v0.5.5 :: Sat Apr 25 2015
-------------------------

New features:

- ``comment`` command learned the ``--private`` option
  (contributed by Johannes Segitz)

Bug fixes:

- fix comment enumeration order
- fix string encoding error when invoking editor which could lead to invalid
  XML being sent to server


v0.5.4 :: Sun Nov 23 2014
-------------------------

Bug fixes:

- better error messages on missing server/account configuration (#3)
- remove fields without name data from bug records (#5)
- make user and password configuration optional (#12)


v0.5.3.1 :: Sun Nov 24 2013
---------------------------

Bug fixes:

- fix installation error


v0.5.3 :: Sat Nov 23 2013
-------------------------

Bug fixes:

- editor: fix incorrect path to vi(1) when EDITOR is not defined
  (issues/1; reported by @taa1)
- ``create`` command: treat "defaulted" fields as mandatory in case
  no default is set (issues/2; reported by @taa1)
- ui: fix some unicode encoding errors
- ``fields`` command: handle minor changes in result format in 4.4
- correct the name of the platform field (platform -> rep_platform)

Other changes:

- expand bzr plugin documentation


v0.5.2 :: Tue Feb 7 2012
------------------------

New features:

- ``priority`` command: set the priority of the given bugs.
- ``comment`` command learned the ``--which`` argument, for limiting
  output to only the given comment(s).
- ``search`` learned the ``--version`` argument.
- ``edit`` command: edit the product version of a bug.

Bug fixes:

- ``search`` command: fix crash when zero bugs returned

Other changes:

- ``-V`` replaces ``--version`` for displaying program version
  information.


v0.5.1 :: Tue Jan 10 2012
-------------------------

Bug fixes:

- ``new`` command: fix assigned_to user matching.


v0.5 :: Tue Jan 3 2012
----------------------

New features:

- ``search`` command: search for bugs matching given criteria.
- ``history`` command: display bug history.
- ``new`` command: new config ``server.<name>.default_product``, if set
  and if corresponding to a product on the server, specifies the default
  product.
- ``new`` command: perform user matching when specifying the assignee or
  cc list during bug creation.

Bug fixes:

- ``time`` command: calculate the hours worked on a bug.


v0.4 :: Wed Nov 30 2011
-----------------------

New features:

- ``time`` command: show or adjust times and estimates for given bug.
  At time of writing, limitations in Bugzilla's RPC API prevent the
  display of cumulative time for a bug.
- ``desc`` command: show the description of the given bugs.
- ``dump`` command: print internal representation of bug(s).
- ``comment`` learned the ``--omit-empty`` and ``--include-empty``
  arguments; exclude or include empty comments (e.g. additional time
  worked, but no specific comment) from the output.  The default is to
  omit empty comments.
- The ``assign`` command can now be configured (on a per-server basis)
  to change the status of a bug, using the ``assign_status`` option.
  See README for details.

Bug fixes:

- Bugzilla URLs are now more rigourously sanity checked.

Other changes:

- Configuration file syntax changed to ini-like (i.e., parsable by
  ``ConfigParser``).  JSON configuration is no longer supported.


v0.3 :: Sun Aug 7 2011
----------------------

New features:

- Added the Bazaar plugin.
- ``new`` command: file a new bug, prompting user for bug data.
- ``status`` learned the ``--dupe-of`` argument; this is all that's needed
  to mark a bug as a duplicate of another (Bugzilla with automatically set
  the status and resolution fields to appropriate values).

Bug fixes:

- ``status`` only prompts for resolution if new status is closed and
  current status is open (``--resolution`` may still be specified,
  however.)
- The unused ``--choose-status`` and ``--choose-resolution`` arguments
  were removed from ``status``.
- Fix the index-field width when displaying choose-from lists (was too
  wide when the number of items displayed was a power of 10)
- Convert ``EOFError`` (``^D``) into ``bzlib.ui.RejectWarning`` when
  prompting user for input.
- Don't bother prompting the user to choose an item from a list that
  contains only one item.


v0.2.1 :: Tue Jul 12 2011
-------------------------

Bug fixes:

- Support Unicode data in all commands.
- Do not show 'aliases' heading in ``--help`` output if none defined.
- Add global arguments to subcommand ``--help`` output.


v0.2 :: Sat Jul 2 2011
----------------------

New features:

- ``comment`` now lists bug comments when no comment is given.
  ``--forward``, ``--reverse`` and ``--limit=N`` can be used to control
  output.
- ``depend`` and ``block`` commands: show or update bug dependency
  relationships.
- ``cc`` command: Show or update CC List.
- ``fields`` command: List valid values for bug fields.
- ``help`` command: Show help for a command, or the top-level help if
  no argument is given.
- ``--version`` prints bugzillatools version.
- Invoke EDITOR for comment input when comment required but not
  explicitly provided
- User matching:  For commands that require usernames, instead of
  providing full username, if a provided fragment matches a single user
  that user will be used.
- Command aliases: users can define their own aliases for commands and
  command arguments.
- Replace ``close``, ``fix``, ``reopen`` and ``resolve`` commands with the
  single ``status`` command; commands to suit a particular workflow can be
  defined as aliases of ``status``, with appropriate arguments.

Bug fixes:

- Improved server misconfiguration or missing configuration handling.
- List commands in alphabetical order.

Other changes:

- The default user configuration file changed to ``~/.bugzillarc``
  (formerly ~/.bugrc).


v0.1.2 :: Fri Jun 17 2011
-------------------------

Bug fixes:

- Fix Bugzilla construction args


v0.1.1 :: Tue Jun 14 2011
-------------------------

New features:

- ``products`` command: list products of a Bugzilla.
- Describe subcommands in ``--help`` output.

Bug fixes:

- Handle server lookup failure when no servers are defined.


v0.1 :: Sun Jun 12 2011
-----------------------

New features:

- First release of bugzillatools
