=====================
Roundup Issue Tracker
=====================

.. meta::
   :title: Roundup Issue Tracker
   :description: A simple-to-use and -install issue-tracking system
       with command-line, web, REST, XML-RPC and e-mail interfaces.
       Adaptable to many uses cases. Allows you to customise the look
       and feel and implement different workflows.
   :og\:type: website
   :og\:url: https://www.roundup-tracker.org/
   :og\:title: Roundup Issue Tracker
   :og\:description: A simple-to-use and -install issue-tracking system
       with command-line, web, REST, XML-RPC and e-mail interfaces.
       Adaptable to many uses cases. Allows you to customise the look
       and feel and implement different workflows.
   :og\:image: https://www.roundup-tracker.org/_images/index_logged_out.png

.. raw:: html

   <div class="release_info note">
     <!-- package version/pypi download -->
     <a
          href="https://pypi.org/project/roundup/#files">
       <span style="padding-inline-end: 1.75ch">Download:</span>
       <img style="vertical-align: text-top"
           src="https://img.shields.io/pypi/v/roundup?color=blue&label=Current%20Version&cacheSeconds=86400"
           alt="Display current version of Roundup on PyPI."
           height="18" width="127">
     </a>

     <!-- supported python versions: <img src="https://shields.io/pypi/pyversions/roundup"> -->
     <!-- license: <img src="https://img.shields.io/pypi/l/roundup"> -->
     <!-- changes since 2.2.0 <img src="https://img.shields.io/github/commits-since/roundup-tracker/roundup/2.2.0/master?sort=semver"> -->
     <!-- status beta, stable, mature.... <img src="https://img.shields.io/pypi/status/roundup"> -->
     <!-- mozilla observatory <img src="https://img.shields.io/mozilla-observatory/grade/www.roundup-tracker.org?publish"> -->
     <!-- commits from last named release: <img alt="GitHub commits difference between two branches/tags/commits" src="https://img.shields.io/github/commits-difference/roundup-tracker/roundup?base=2.2.0&head=master">a -->
     <!-- newest tag by date - use for alpha/beta release notifications?
     <img alt="GitHub tag (latest by date)" src="https://img.shields.io/github/v/tag/roundup-tracker/roundup"> -->

     <!-- downloads/month -->
     <a style="display:block; margin-block-start: 0.5em;"
          href="https://pypistats.org/packages/roundup">
       <span style="padding-inline-start: 10.75ch"></span>
       <img
         src="https://img.shields.io/badge/dynamic/json?color=blue&label=Downloads%2FMonth&cacheSeconds=86400&query=data.last_month&url=https%3A%2F%2Fpypistats.org%2Fapi%2Fpackages%2Froundup%2Frecent"
         alt="Badge displaying number of downloads per month."
         height="18" width="127">
     </a>
     <a style="display:block; margin-block-start: 0.5em;"
        href="https://hub.docker.com/r/rounduptracker/roundup">
     <span style="padding-inline-start: 10.75ch"></span>
     <img
        src="https://img.shields.io/docker/image-size/rounduptracker/roundup?label=Docker%20Size"
        alt="Graphic displaying size of newest docker image on hub.docker.com."
        height="18" width="127">
     </a>

     <!-- build status -->
     <a 
         style="display:block; margin-block-start: 1em;"
         href="https://github.com/roundup-tracker/roundup/actions?query=workflow%3Aroundup-ci++">
       <span>Build Status:</span>
       <img
         src="https://github.com/roundup-tracker/roundup/actions/workflows/ci-test.yml/badge.svg"
         alt="Status of primary regression test job on github."
         height="18" width="127"><br>
     </a>
   </div>

Roundup is a simple-to-use and -install issue-tracking system with
command-line, web, REST, XML-RPC and e-mail interfaces.  It is based
on the winning design from Ka-Ping Yee in the Software Carpentry
"Track" design competition.

The current stable version of Roundup is 2.3.0b1. It is a bug fix
and feature release for the 2.2.0 release 

Release Highlights
==================

Some improvements from the 2.2.0 release are:

* Dockerfile demo mode implemented.

* SQLite backends can use WAL mode to reduce blocking between readers
  and writers.

* Redis can be used for session database with SQLite and dbm
  backends. Provides a major performance improvement.

* roundup-mailgw can use OAUTH authentication to SMTP
  server. (roundup-mailgw command line options changed as a result.)

* Postgres full text index can now be enabled.

* Modifications to in-reply-to threading when there are multiple
  matches.

* Many updates to documentation to make it scannable, useful and
  work on mobile.

* Admin documentation includes a section on setting up Content
  Security Policy (CSP)

* REST now allows rate limiting headers to be accessed by client
  javascript.

* Default number of rounds for PBKDF2 updated to 2M to account for
  improvements in password crackers and CPU power.

* Support PBKDF2 with SHA512 for password storage

* Deprecate SSHA password hash function.

* roundup-admin reindex can be done in batches to managle load
  incurred by reindexing.

* roundup-admin can list avaailable templates and their installed
  locations.

* Crash fixes in detector handling, configuration handling, 

More info on the 51 changes can be found in the `change note`_.

Roundup Use Cases
=================

For more information on Roundup see the :doc:`features list
<docs/features>`, :doc:`design overview <docs/design>`, and all the
other :doc:`documentation <docs>`. Roundup has been deployed for:

* bug tracking and TODO list management (the classic
  installation)
* customer help desk support (with a wizard for the phone
  answerers, linking to networking, system and development
  issue trackers)
* issue management for IETF working groups
* sales lead tracking
* conference paper submission and double-blind referee
  management
* weblogging (well, almost :) 

...and so on. It's been designed with :doc:`flexibility
<docs/customizing>` in mind - it's not just another bug
tracker.


Try It Out
==========

Roundup ships with a **demo tracker** to play with - you don't need to
install Roundup. After you've unpacked the source, just run "``python
demo.py``" and load up the URL it prints out!

You can install using a virtual environment with pip by:

1. create a virtual environment with::

     python3 -m venv roundup

2. activate the environment with (assuming your shell is
   sh/bash/zsh/ksh like)::

     . roundup/bin/activate

3. install the latest release of Roundup with::

     python3 -m pip install roundup

4. create a demo tracker with::

     roundup-demo

   using ``./demo`` as the directory and the ``classic`` tracker.

5. load the URL printed by the demo tracker

6. when you are done, use `deactivate` to return your shell to using
   the system python.

Or choose the source directory gratification mode to run the demo
with these steps (change the ``-2.2.0`` version identifier to match
your downloaded file).

1. ``python3 -m pip download roundup``
2. ``tar -xzvf roundup-2.2.0.tar.gz``

   * if you don't have a tar command, ``python -c 'import tarfile, sys; tarfile.open(sys.argv[1]).extractall();' roundup-2.2.0.tar.gz`` can be used.

3. ``cd roundup-2.2.0``
4. ``python3 demo.py``

Both of these methods produce the same result.

(The source download can also be used to create a Docker image.)

Origin Story
============
Roundup was originally released as version 0.1.1 in late August, 2001.
The first `change note`_ written said:

    Needed a bug tracking system. Looked around. Tried to install many Perl-based systems, to no avail.
    Got tired of waiting for Roundup to be released. Had just finished major product project, so needed
    something different for a while. Roundup here I come... 

.. _`download`: https://pypi.org/project/roundup/
.. _`change note`: https://sourceforge.net/p/roundup/code/ci/tip/tree/CHANGES.txt
.. _`its own set of docs`: https://www.roundup-tracker.org/dev-docs/docs.html