=====================
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.6.0, which includes bug
fixes and additional features compared to the previous 2.5.0 release.

Roundup is compatible with Python 3.10+.

.. 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.6.0 release are:

  .. comment: `XXXFIXME`: docs/upgrading.html#cve-2026-csrfl
     CVE hasn't been assigned as of date of release for either
     of the first two improvements.

* **Fix for missing CSRF protection for PATCH method**

  The REST interface does not apply CSRF checks when using the PATCH
  command. See request still in progress at time of release.

* **Filter history entries where permissions are handled by check function**

  The history of a property change was always shown if the property
  permissions included a check function. The permissions are now
  properly checked using the check function. CVE request still in
  progress at time of release.

* **Modern CSRF prevention method without CSRF tokens available**

  This release implements CSRF protection using `Cross-Site Request
  Forgery by Filippo Valsorda <https://words.filippo.io/csrf/>`_.  This
  is an effective method for CSRF protection and is much simpler as
  well. There are no configurable options unlike the 8 options for the
  older method.

* **Require reauthentication when making changes to sensitive fields**

  You can trigger a reauthentication when the user changes particular
  fields. For example you can require a password be entered before the
  user changes their password.

* **Classic UI interface modernization.**

  The classic tracker has basic responsive support for mobile.  The
  table based layout was removed and HTML 5 landmarks (main, nav ...)
  are used along with flex and grid layouts.  The left hand menu now
  collapses to a grid layout in a single column when on a smaller
  display. This can be retrofitted to existing classic trackers.

  When you moved from one page to the next on an index, the
  query/search name was lost. This release now preserves the search
  name.

  Queries triggered from the query edit page now include the query
  name in the index view.

  The web UI now allows users to log in without a password. Before the
  ``password`` field was required which prevented completing the login
  action.

  The user.item.html template now generates valid javascript.

  The jinja2 template got an updated copy of bootstrap.

More info on the 49 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