=====================
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 use cases. Allows you to customize 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 use cases. Allows you to customize 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 news">
     <!-- package version/pypi download -->
     <a            target="_top" href="/newspapers?url=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 an issue-tracking system that boasts a user-friendly
interface and easy installation process. It offers a range of
interfaces, including command-line, web, REST, XML-RPC, and e-mail,
making it a versatile solution for issue tracking. The system is based
on the award-winning design by Ka-Ping Yee, which emerged victorious
in the Software Carpentry “Track” design competition.

Roundup is highly customizable, allowing users to tailor the system to
their specific needs and preferences.

The latest stable version of Roundup is 2.3.0, which includes bug
fixes and additional features compared to the previous 2.2.0 release.

Roundup is compatible with Python 2.7.12+ or 3.6+.

.. admonition:: Python 2 Support

   Despite the initial intention to provide support for Python 2 until
   2025, several Continuous Integration (CI) services are
   discontinuing their resources for testing with Python 2. It is
   recommended to utilize Python 3 for the deployment of new trackers,
   while existing trackers should be `upgraded to use Python 3.
   <docs/upgrading.html#python-3-support-info>`_

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

Some improvements from the 2.2.0 release are:

* Dockerfile demo mode implemented. This allows quick evaluation as
  well as the ability to spin up a configured tracker to customise.

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

* 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 resulting in more predictable handling of messages.

* 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) to better secure your Roundup trackers.

* 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 to improve
  resistance to password crackers.

* Deprecate SSHA password hash function.

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

* roundup-admin can list available templates and their installed
  locations. This is useful when installing via pip or in a docker
  container as supporting files are not stored in the usual locations
  like /usr/share/roundup.

* Crash fixes in detector handling, configuration handling, fix for
  sorting of multilinks.

More info on the 53 changes can be found in the `change notes`_.

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 :)
* thing management using the `GTD methodology <https://gettingthingsdone.com/>`_.

...and so on. It's been designed with :doc:`flexibility
<docs/customizing>` in mind - it's not merely 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!

Follow the source gratification mode with these steps (change the
``-2.3.0`` version identifier to match your downloaded file).

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

   * if you don't have a tar command (e.g windows), use:
     ``python -c "import tarfile, sys; tarfile.open(sys.argv[1]).extractall();" roundup-2.3.0.tar.gz``


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

(The source download can also be used to `create a custom Docker
image <docs/installation.html#docker-support>`_.)

Alternatively, 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.

Both of these methods produce the same result.

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 notes`: https://sourceforge.net/p/roundup/code/ci/tip/tree/CHANGES.txt
.. _`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