annotate doc/features.txt @ 7752:b2dbab2b34bc

fix(refactor): multiple fixups using ruff linter; more testing. Converting to using the ruff linter and its rulesets. Fixed a number of issues. admin.py: sort imports use immutable tuples as default value markers for parameters where a None value is valid. reduced some loops to list comprehensions for performance used ternary to simplify some if statements named some variables to make them less magic (e.g. _default_savepoint_setting = 1000) fixed some tests for argument counts < 2 becomes != 2 so 3 is an error. moved exception handlers outside of loops for performance where exception handler will abort loop anyway. renamed variables called 'id' or 'dir' as they shadow builtin commands. fix translations of form _("string %s" % value) -> _("string %s") % value so translation will be looked up with the key before substitution. end dicts, tuples with a trailing comma to reduce missing comma errors if modified simplified sorted(list(self.setting.keys())) to sorted(self.setting.keys()) as sorted consumes whole list. in if conditions put compared variable on left and threshold condition on right. (no yoda conditions) multiple noqa: suppression removed unneeded noqa as lint rulesets are a bit different do_get - refactor output printing logic: Use fast return if not special formatting is requested; use isinstance with a tuple rather than two isinstance calls; cleaned up flow and removed comments on algorithm as it can be easily read from the code. do_filter, do_find - refactor output printing logic. Reduce duplicate code. do_find - renamed variable 'value' that was set inside a loop. The loop index variable was also named 'value'. do_pragma - added hint to use list subcommand if setting was not found. Replaced condition 'type(x) is bool' with 'isinstance(x, bool)' for various types. test_admin.py added testing for do_list better test coverage for do_get includes: -S and -d for multilinks, error case for -d with non-link. better testing for do_find including all output modes better testing for do_filter including all output modes fixed expected output for do_pragma that now includes hint to use pragma list if setting not found.
author John Rouillard <rouilj@ieee.org>
date Fri, 01 Mar 2024 14:53:18 -0500
parents c22b4f0364eb
children 1632bdbfbef6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6262
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6762
diff changeset
2 :description:
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6262
diff changeset
3 Features of using the Roundup Issue Tracker. Describes
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6262
diff changeset
4 all access methods, configuration and workflow capabilities.
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6262
diff changeset
5 Links to detailed documentation.
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6262
diff changeset
6
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 ================
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 Roundup Features
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9 ================
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 Roundup is a simple-to-use and -install issue-tracking system with
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 web, e-mail and command-line interfaces. It is based on the winning design
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
13 from Ka-Ping Yee in the :index:`Software Carpentry` "Track" design competition.
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
15 *simple to install*
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
16 - installation (including web interface) takes about 30 minutes
7351
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
17 - instant-gratification ``python demo.py`` takes less than 5 minutes :)
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
18 - five templates included in the distribution for you to base your tracker on
2660
2ebeb53eb336 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2259
diff changeset
19 - play with the demo, customise it and then use *it* as the template for
2ebeb53eb336 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2259
diff changeset
20 your production tracker
7351
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
21 - requires *no* additional support software - python (2.7 or 3.6+) is
2223
9b447ac40be3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
22 enough to get you going
7470
c22b4f0364eb Remove some easy/simple language.
John Rouillard <rouilj@ieee.org>
parents: 7351
diff changeset
23 - supports higher-performance storage backends like sqlite_,
3935
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3839
diff changeset
24 mysql_ and postgresql_
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 *simple to use*
6762
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
27 - accessible through the web (html, REST or XMLRPC), email,
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
28 command-line or Python programs
740
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
29 - may be used to track bugs, features, user feedback, sales opportunities,
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
30 milestones, ...
2259
f47ab53269cd *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
31 - automatically keeps a full history of changes to issues with
f47ab53269cd *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
32 configurable verbosity and easy access to information about who created
f47ab53269cd *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
33 or last modified *any* item in the database
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
34 - issues have their own mini mailing list (nosy list)
2258
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
35 - users may sign themselves up, there may be automatic signup for
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
36 incoming email and users may handle their own password reset requests
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
38 *highly configurable*
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
39 - web interface HTML is fully editable
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
40 - database schema is also fully editable (only the "user" class is required)
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
41 with a full set of data types (including dates and many-to-many relations)
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
42 across all storages available
6934
37e2e3897ddf Add reference to ABAC to feature document
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
43 - authorization is fine grained and can be based on the properties of
37e2e3897ddf Add reference to ABAC to feature document
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
44 a user and resource (`ABAC, PBAC (Attribute or Policy/Purpose Based Access
37e2e3897ddf Add reference to ABAC to feature document
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
45 Control <https://en.wikipedia.org/wiki/Attribute-based_access_control>`_))
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
46 - customised automatic auditors and reactors may be written that perform
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 1649
diff changeset
47 actions before and after changes are made to entries in the database,
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3748
diff changeset
48 or may veto the creation or modification of items in the database
2258
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
49 - samples are provided for all manner of configuration changes and
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
50 customisations
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
51
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
52 *fast, scalable*
3935
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3839
diff changeset
53 - with the sqlite, mysql and postgresql backends, roundup is
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 1649
diff changeset
54 also fast and scalable, easily handling thousands of issues and users
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 1649
diff changeset
55 with decent response times
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 1649
diff changeset
56 - database indexes are automatically added for those backends that
3935
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3839
diff changeset
57 support them (sqlite, mysql and postgresql)
7351
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
58 - indexed full text search (FTS) gives fast responses to searches across all
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
59 messages and indexed string properties
7351
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
60 - support for the Xapian, Whoosh, sqlite or postgres full-text
6762
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
61 indexing engines for large trackers
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
62
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
63 *documented*
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
64 - documentation exists for installation, upgrading, maintenance, users and
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
65 customisation
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67 *web interface*
1228
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
68 - fully editable interfaces for listing and display of items
Richard Jones <richard@users.sourceforge.net>
parents: 742
diff changeset
69 - extendable to include wizards, parent/meta bug displays, ...
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 - differentiates between anonymous, known and admin users
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 - may be set up to require login, and may also only allow admin users
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 to register new users
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
73 - authentication of user registration and user-driven password resetting
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
74 using email and one time keys
3748
fdc9eb78d708 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3533
diff changeset
75 - may be run using WSGI or through CGI as a normal cgi script, as a
7351
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
76 stand-alone web server, under mod_wsgi (mod_python is deprecated)
1f8e41b0e97f updates: template #, min version, timing on demo mode
John Rouillard <rouilj@ieee.org>
parents: 7259
diff changeset
77 or through Zope
740
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
78 - searching may be performed using many constraints, including a full-text
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
79 search of messages attached to issues
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
80 - file attachments (added through the web or email) are served up with the
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
81 correct content-type and filename
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
82 - email change messages generated by roundup appear to be sent by the
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
83 person who made the change, but responses will go back through the nosy
741
b48a19a88b65 Cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 740
diff changeset
84 list by default
2258
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
85 - flexible access control built around Permissions and Roles with assigned
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
86 Permissions
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
87 - generates valid HTML4 or XHTML
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
88 - detects concurrent user changes
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
89 - saving and editing of user-defined queries which may optionally be
c8f426142289 doc changes
Richard Jones <richard@users.sourceforge.net>
parents: 2223
diff changeset
90 shared with other users
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91
741
b48a19a88b65 Cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 740
diff changeset
92 *e-mail interface*
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 - may be set up using sendmail-like delivery alias, POP polling or mailbox
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 polling
740
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
95 - may auto-register users who send in mail and aren't known to roundup
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 - nosy list configuration controls how people are added and when messages
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 are sent to the list
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 - auto-filing of "unformatted" messages into a particular class
740
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
99 - e-mail attachments are handled sanely, being attached to the issue they're
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
100 intended for, and forwarded on to the nosy list
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
101 - sane handling of content-type and content-encoding of messages (text/plain
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
102 preferred in all situations)
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
103 - email packages that display threading will show issue messages correctly
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
104 threaded
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
105 - users may send in messages from multiple addresses and be associated
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
106 with the same roundup username
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
107 - built-in security features like TLS and APOP
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 *command-line*
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 - may be used to interactively manage roundup databases
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 - may be scripted using standard shell scripting
740
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
112 - roundup's API may also be used by other Python programs - a sample is
2d50d6a17617 more marketing ;)
Richard Jones <richard@users.sourceforge.net>
parents: 739
diff changeset
113 provided that runs once a day and emails people their assigned issues
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
114 - a variety of sample shell scripts are provided (weekly reports, issue
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
115 generation, ...)
739
c612747b1126 Added a Features doc
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116
3839
Stefan Seefeld <stefan@seefeld.name>
parents: 3754
diff changeset
117 *xmlrpc interface*
Stefan Seefeld <stefan@seefeld.name>
parents: 3754
diff changeset
118 - simple remote tracker interface with basic HTTP authentication
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
119 available at the /xmlrpc endpoint.
3839
Stefan Seefeld <stefan@seefeld.name>
parents: 3754
diff changeset
120 - provides same access to tracker as roundup-admin, but based on
Stefan Seefeld <stefan@seefeld.name>
parents: 3754
diff changeset
121 XMLRPC calls
7470
c22b4f0364eb Remove some easy/simple language.
John Rouillard <rouilj@ieee.org>
parents: 7351
diff changeset
122 - see the `xmlrpc guide`_ for more details basic and advanced clients etc.
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
123
6762
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
124 *RESTful interface*
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
125 - accessible using basic HTTP authentication at /rest starting point
6762
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
126 - able to be extended with new endpoints
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
127 - authentication can be done using JSON Web Tokens (JWT)
f8ee14436371 Add fts search engines, add more rest doc.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
128 - CORS support for use by third party web pages.
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
129 - see the `rest guide`_ for details.
3839
Stefan Seefeld <stefan@seefeld.name>
parents: 3754
diff changeset
130
7259
0c596e39980f update sqlite url
John Rouillard <rouilj@ieee.org>
parents: 6934
diff changeset
131 .. _sqlite: https://www.sqlite.org/index.html
5511
bfe8e52af1e7 more mentions of updated MySQL client module
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5096
diff changeset
132 .. _mysql: https://pypi.org/project/MySQL-python/
6262
ba82fb74f806 Update psycopg link to: https://www.psycopg.org/
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
133 .. _postgresql: https://www.psycopg.org/
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
134 .. _`xmlrpc guide`: xmlrpc.html
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5526
diff changeset
135 .. _`rest guide`: rest.html

Roundup Issue Tracker: http://roundup-tracker.org/