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

Roundup is compatible with Python 2.7.12+ or 3.6+.

.. admonition:: Python 2 Support

   Python 2 support ends with release 2.4.0 (July 2024).
   Several Continuous Integration (CI) services are
   discontinuing their resources for testing with Python 2.
   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.3.0 release are:

* three CVE's have been fixed. One requires changes to your
  tracker's home directory. The other two are fixed by
  installing 2.4.0.  See
  https://www.roundup-tracker.org/docs/security.html for
  details and instructions on how to fix these in 2.4.0 and
  earlier releases.

* new classhelper component thanks to a team of students
  from CS682 at U-Mass Boston. This fixes many issues with
  the old classhelper. It is implemented as a web-component
  and needs REST interface access. It will fall back to the
  classic classhelper if REST is not available or if the
  browser does not support web-components.

* fix Windows Python installation using pip. It used to go
  into an infinite loop during install or download. Also fix
  installation of shared files (templates) so roundup-admin
  can find them.

* using ``@current_user`` as a value in a search URL for a
  user property will use the current logged in user. Now you
  can share searches like: "My issues" as "my" will become
  the current logged in user.

* login failures to the REST/XML-RPC interfaces are now rate
  limited to limit password guessing attacks.

* utf8mb4 is the default charset for MySQL. This requires
  migrating your database using the mysql client. You can
  choose to keep the older character set in config.ini.

* PostgreSQL services defined in pg_service.conf can be
  used.  PostgreSQL schemas are supported to eliminate the
  need for the roundup user to have database
  creation/deletion privileges.

* fix out of memory issue when importing larger trackers
  into PostgreSQL.

* multiple roundup-admin improvements: display protected
  properties (like creation date), better formatting of
  output, command history. Also on windows, pyreadline3 is
  supported to provide an editable interactive command line.

* an experimental wsgi performance improvement in 2.3.0 is
  now now the default and is opt-out.

* new template functions: utils.readfile and
  utils.expandfile. Javascript that is included in the
  Python core will be moved to external files and be able to
  have values from Roundup substituted in the Javascript.

* allow content-type of a template to be set from inside the
  template.  This allows returning json or xml from a
  template without a .json or .xml extention.

* fix import/export on windows to use Unix style line
  endings fixing export/import on Windows and making exports
  portable across platforms.

More info on the 79 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.4.0`` version identifier to match your downloaded file).

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


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