=====================
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
          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.5.0 <img src="https://img.shields.io/github/commits-since/roundup-tracker/roundup/2.5.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.5.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.5.0, which includes bug
fixes and additional features compared to the previous 2.4.0 release.

Roundup is compatible with Python 3.7+.

.. admonition:: Python 2 Support

   Python 2 support ended with release 2.4.0 (July 2024).
   Use Python 3 for the deployment of new trackers.
   Existing trackers should be `upgraded to use Python 3.
   <docs/upgrading.html#python-3-support-info>`_

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

Some improvements from the 2.4.0 release are:

* **XSS vulnerability with devel and responsive templates fixed**

  Just before release an XSS security issue with trackers based on
  the devel or responsive templates was discovered. The `updating
  directions`_ include instructions on fixing this issue with the
  html templates from earlier releases. (CVE-2025-53865)

  .. _`updating directions`: docs/upgrading.html#cve-2025-53865

* **The property/field advanced search expression feature has been
  enhanced and documented.**

  Search expressions are usually built using the
  expression editor on the search page. They can be built manually
  by modifying the search URL but the RPN search expression format
  was undocumented. Errors in expressions could return results that
  didn't match the user's intent. This release documents the RPN
  expression syntax, adds basic expression error detection, and
  improves error reporting.

* **The default hash method for password storage is more secure.**

  We use PBKDF2 with SHA512 (was SHA1). With this change you can
  lower the value of password_pbkdf2_default_rounds in your
  tracker's config.ini. Check the upgrading documentation for more
  info. (Note this may cause longer authentication times, the
  upgrade doc describes how to downgrade the hash method if required.)

* **Roundup's session token is now prefixed with the magic
  ``__Secure__`` tag when using HTTPS.**

  This adds another layer of protection in addition to the
  existing ``Secure`` property that comes with the session cookie.

* **Data authorization can be done at the database level speeding up
  display of index pages.**

  Roundup verifies the user's authorization for the data fetched
  from the database after retrieving data from the database. A new
  optional ``filter`` argument has been added to Permission
  objects. When the administrator supplies a filter function, it
  can boost performance with SQL server databases by pushing
  selection criteria to the database. By offloading some
  permission checks to the database, less data is retrieved from
  the database. This leads to quicker display of index pages with
  reduced CPU and network traffic.

* **The REST endpoint can supply binary data (images, pdf, ...) to
  its clients.**

  Requesting binary data from a REST endpoint has been a
  hassle. Since JSON can't handle binary data, images (and other
  binary data) need to be encoded. This makes them significantly
  larger. The workaround was to use a non-REST endpoint for fetching
  non-text attachments. This update lets the REST endpoint return
  raw message or file content data. You can utilize the
  ``binary_content`` endpoint along with an appropriate ``Accept``
  header (e.g. ``image/jpeg``) in your request.

* **Extract translatable strings from your tracker easily.**

  The ``roundup-gettext`` tool has been enhanced to extract
  translatable strings from detectors and extensions. This will
  simplify the process of translating your trackers.

More info on the 42 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.6.0`` version identifier to match the version of Roundup you want
to use).

1. ``python3 -m pip download roundup``
2. ``tar -xzvf roundup-2.6.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.6.0.tar.gz


3. ``cd roundup-2.6.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