Mercurial Repository: p/roundup/code: doc/customizing.txt comparison

comparison doc/customizing.txt @ 7268:91125d474c1e

doc updates, normalize roundup => Roundup, add links, typo fixes In Tracker in a Nutshell section Document interfaces.py in table Add links for auditors/reactors to detectors section in table Add links for actions in table Also mark optional components Change roundup to canonical Roundup. Fix unordered lists that were indented causing a list inside a blockquote. UL lists are not unindented. Move internal hyperlink references above the section heading they refer to. Links were jumping after the heading which disorients the user. Change reference to never deleting 'users' class to be 'user' class. fix typos Remove uneeded trailing whitespace.

author	John Rouillard <rouilj@ieee.org>
date	Mon, 24 Apr 2023 00:21:25 -0400
parents	519fb6dca72b
children	90c70726e882

comparison

equal deleted inserted replaced

-:519fb6dca72b
+:91125d474c1e
 single: tracker; structure lib directory
 =================== ========================================================
 Tracker File        Description
 =================== ========================================================
 config.ini          Holds the basic `tracker configuration`_
 schema.py           Holds the `tracker schema`_
 initial_data.py     Holds any data to be entered into the database when the
-tracker is initialised.
+tracker is initialised (optional)
-db/                 Holds the tracker's database
+interfaces.py       Allows `modifying the core of Roundup`_ (optional)
-db/files/           Holds the tracker's upload files and messages
+db/                 Holds the tracker's database
+db/files/           Holds the tracker's upload files and messages
 db/backend_name     Names the database back-end for the tracker (obsolete).
-Current way uses the ``backend`` setting in the rdbms
+Use the ``backend`` setting in the ``[rdbms]``
-		    section of config.ini.
+		    section of ``config.ini`` instead.
-detectors/          Auditors and reactors for this tracker
+detectors/          `Auditors and reactors`_ for this tracker
-extensions/         Additional actions and `templating utilities`_
+extensions/         Additional `actions`_ and `templating utilities`_
 html/               Web interface templates, images and style sheets
 lib/                optional common imports for detectors and extensions
 =================== ========================================================
 .. index:: config.ini
 Tracker Configuration
 =====================
 The ``config.ini`` located in your tracker home contains the basic
-configuration for the web and e-mail components of roundup's interfaces.
+configuration for the web and e-mail components of Roundup's interfaces.
 Changes to the data captured by your tracker is controlled by the `tracker
 schema`_.  Some configuration is also performed using permissions - see the
 `security / access controls`_ section. For example, to allow users to
 automatically register through the email interface, you must grant the
 umask -- ``02``
 Defines the file creation mode mask.
 csv_field_size -- ``131072``
-Maximum size of a csv-field during import. Roundups export
+Maximum size of a csv-field during import. Roundup's export
 format is a csv (comma separated values) variant. The csv
 reader has a limit on the size of individual fields
 starting with python 2.5. Set this to a higher value if you
 get the error 'Error: field larger than field limit' during
 import.
 .. index:: config.ini; sections tracker
 Section **tracker**
 name -- ``Roundup issue tracker``
-A descriptive name for your roundup instance.
+A descriptive name for your Roundup instance.
 web -- ``http://host.example/demo/``
 The web address that the tracker is viewable at.
 This will be included in information sent to users of the tracker.
 The URL MUST include the cgi-bin part or anything else
 that is required to get to the home page of the tracker.
 You MUST include a trailing '/' in the URL.
 email -- ``issue_tracker``
-Email address that mail to roundup should go to.
+Email address that mail to Roundup should go to.
 language -- default *blank*
 Default locale name for this tracker. If this option is not set, the
 language is determined by the environment variable LANGUAGE, LC_ALL,
 LC_MESSAGES, or LANG, in that order of preference.
 domain -- ``localhost``
 Domain name used for email addresses.
 host -- default *blank*
-SMTP mail host that roundup will use to send mail
+SMTP mail host that Roundup will use to send mail
 username -- default *blank*
 SMTP login name. Set this if your mail host requires authenticated access.
 If username is not empty, password (below) MUST be set!
 precedence. The path may be either absolute or relative to the directory
 containig this config file.
 add_authorinfo -- ``yes``
 Add a line with author information at top of all messages send by
-roundup.
+Roundup.
 add_authoremail -- ``yes``
 Add the mail address of the author to the author information at the
 top of all messages.  If this is false but add_authorinfo is true,
 only the name of the actor is added which protects the mail address
 blankline_re -- ``[\r\n]+\s*[\r\n]+``
 Regular expression matching a blank line.  Value is Python Regular
 Expression (UTF8-encoded).
 ignore_alternatives -- ``no``
-When parsing incoming mails, roundup uses the first
+When parsing incoming mails, Roundup uses the first
 text/plain part it finds. If this part is inside a
 multipart/alternative, and this option is set, all other
 parts of the multipart/alternative are ignored. The default
 is to keep all parts and attach them to the issue.
 What you can't do to the schema
 -------------------------------
 You must never:
-**Remove the users class**
+**Remove the user class**
 This class is the only *required* class in Roundup.
 **Remove the "username", "address", "password" or "realname" user properties**
 Various parts of Roundup require these properties. Don't remove them.
 keyword
 Initially empty, will hold keywords useful for searching issues.
 user
 Initially holding the "admin" user, will eventually have an entry
-for all users using roundup.
+for all users using Roundup.
 msg
 Initially empty, will hold all e-mail messages sent to or
-generated by roundup.
+generated by Roundup.
 file
 Initially empty, will hold all files attached to issues.
 issue
 events.
 .. index:: triple: schema; property attributes; try_id_parsing
 - ``try_id_parsing`` is turned on by default. If entering a number
-into a Link or Multilink field, roundup interprets this number as an
+into a Link or Multilink field, Roundup interprets this number as an
 ID of the item to link to. Sometimes items can have numeric names
-(like, e.g., product codes). For these roundup needs to match the
+(like, e.g., product codes). For these Roundup needs to match the
 numeric name and should never match an ID. In this case you can set
 ``try_id_parsing='no'``.
 .. index:: triple: schema; property attributes; rev_multilink
 .. index:: triple: schema; property attributes; msg_header_property
 - The ``msg_header_property`` is used by the mail gateway when sending
 out messages. When a link or multilink property of an issue changes,
-roundup creates email headers of the form::
+Roundup creates email headers of the form::
 X-Roundup-issue-prop: value
 where ``value`` is the ``name`` property for the linked item(s).
 For example, if you have a multilink for attached_files in your
 type of the file.
 Roundup by default considers the contents of the file immutable. This
 is to assist in maintaining an accurate record of correspondence.  The
 distributed tracker templates do not enforce this. So if you have
-access to the roundup tracker directory, you can edit the files (make
+access to the Roundup tracker directory, you can edit the files (make
 sure to preserve mode, owner and group) to remove information (e.g. if
 somebody includes a password or you need to redact proprietary
 information). Obviously the journal for the message/file will not
 report that the file has changed.
 If you need to delete an entire file, replace the file contents with::
 [file contents deleted due to spam 202-10-21 --myname]
-rather than deleting the file. If you actually delete the file roundup
+rather than deleting the file. If you actually delete the file Roundup
 will report an error to the user and email the administrator. If you
 empty the file, a user downloading the file using the direct URL
 (e.g. ``tracker/msg22``) may be confused and think something is broken
 when they receive an empty file. Retiring a file/msg does not prevent
 access to the file using the direct URL. Retiring an item only removes
 where ``hello`` is a file on local disk.
 You can enforce immutability in your tracker by adding an auditor (see
 detectors_) for the file/msg class that rejects changes to the content
 property. The auditor could also add a journal entry so that a change
-via the roundup mechanism is reported.  Using a mixin (see:
+via the Roundup mechanism is reported.  Using a mixin (see:
 https://wiki.roundup-tracker.org/MixinClassFileClass) to augment the
 file class allows for other possibilities including signing the file, or
 recording a checksum in the database and validating the file contents
 at the time it gets read. This allows detection of changes done on the
-filesystem outside of the roundup mechanism.
+filesystem outside of the Roundup mechanism.
 .. index:: triple: schema; class property; messages
 triple: schema; class property; files
 triple: schema; class property; nosy
 triple: schema; class property; superseder
 .. index:: roundup-admin; setting assignedto on an issue
 Select a String property of the class to be the key property. The key
 property must be unique, and allows references to the items in the class
 by the content of the key property. That is, we can refer to users by
-their username: for example, let's say that there's an issue in roundup,
+their username: for example, let's say that there's an issue in Roundup,
 issue 23. There's also a user, richard, who happens to be user 2. To
 assign an issue to him, we could do either of::
 roundup-admin set issue23 assignedto=2
 Select a property of the class to be the label property. The label
 property is used whereever an item should be uniquely identified, e.g.,
 when displaying a link to an item. If setlabelprop is not specified for
 a class, the following values are tried for the label:
 * the key of the class (see the `setkey(property)`_ section above)
 * the "name" property
 * the "title" property
 * the first property from the sorted property name list
 So in most cases you can get away without specifying setlabelprop
 explicitly.
 You should make sure that users have View access to this property or
 e.g., when grouping or sorting class A by a link to class B in the user
 interface, the order property of class B is used for sorting.  If
 setorderprop is not specified for a class, the following values are tried
 for the order property:
 * the property named "order"
 * the label property (see `setlabelprop(property)`_ above)
 So in most cases you can get away without specifying setorderprop
 explicitly.
 .. index: triple: schema; class method; create
 .. _Roundup wiki:
 https://wiki.roundup-tracker.org/
 .. index:: !detectors
+.. _detectors:
+.. _Auditors and reactors:
 Detectors - adding behaviour to your tracker
 ============================================
-.. _detectors:
 Detectors are initialised every time you open your tracker database, so
 you're free to add and remove them any time, even after the database is
 initialised via the ``roundup-admin initialise`` command.
 comes from "the system" and not a user).
 .. index:: extensions
 .. index:: extensions; add python functions to tracker
+.. _extensions:
+.. _actions:
 Extensions - adding capabilities to your tracker
 ================================================
-.. _extensions:
 While detectors_ add new behavior by reacting to changes in tracked
 objects, `extensions` add new actions and utilities to Roundup, which
 are mostly used to enhance web interface.
 Note that at this point web interface is not loaded, but extensions still
 can register actions for in tracker instance. This may be fixed in
 Roundup 1.6 by introducing ``init_web(client)`` callback or a more
 flexible extension point mechanism.
+* ``instance.registerUtil`` is used for adding `templating utilities`_
-* ``instance.registerUtil`` is used for adding `templating utilities`_
+(see `adding a time log to your issues`_ for an example)
-(see `adding a time log to your issues`_ for an example)
+* ``instance.registerAction`` is used to add more actions to instance
-* ``instance.registerAction`` is used to add more actions to instance
+and to web interface. See `Defining new web actions`_ for details.
-and to web interface. See `Defining new web actions`_ for details.
+Generic action can be added by inheriting from ``action.Action``
-Generic action can be added by inheriting from ``action.Action``
+instead of ``cgi.action.Action``.
-instead of ``cgi.action.Action``.
+.. _interfaces.py:
-interfaces.py - hooking into the core of roundup
+.. _modifying the core of Roundup:
+interfaces.py - hooking into the core of Roundup
 ================================================
-.. _interfaces.py:
+There is a magic trick for hooking into the core of Roundup. Using
-There is a magic trick for hooking into the core of roundup. Using
 this you can:
 * modify class data structures
 * monkey patch core code to add new functionality
 * modify the email gateway
 * add new rest endpoints
 but with great power comes great responsibility.
-Interfaces.py has been around since the earliest releases of roundup
+Interfaces.py has been around since the earliest releases of Roundup
 and used to be the main way to get a lot of customization done. In
-modern roundup, the extensions_ mechanism is used, but there are
+modern Roundup, the extensions_ mechanism is used, but there are
 places where interfaces.py is still useful. Note that the tracker
 directories are not on the Python system path when interfaces.py is
 evaluated. You need to add library directories explictly by
 modifying sys.path.
 In this case static files delivered using @@file will have cache
 headers set. These files are searched for along the `static_files`
 path in the tracker's `config.ini`. In the example above:
 * a css file (e.g. @@file/style.css) will be cached for an hour
 * javascript files (e.g. @@file/libraries/jquery.js) will be cached
 for 30 seconds
 * a file named rss.xml will be cached for 15 minutes
 * a file named local.js will be cached for 2 hours
 Note that a file name match overrides the mime type settings.
 Example: Implement password complexity checking
 test-issues@example.com  roundup-test@roundup-vm.example.com
 test-support@example.com roundup-test+support-a@roundup-vm.example.com
 test@support.example.com roundup-test+support-b@roundup-vm.example.com
-These modifications to the mail gateway for roundup allows anonymous
+These modifications to the mail gateway for Roundup allows anonymous
 submissions. It hides all of the requesters under the "support"
 user. It also makes some other modifications to the mail parser
 allowing keywords to be set and prefixes to be defined based on the
 delivery alias.
 	    else:
 		# parse the message normally
 		return roundup.mailgw.parsedMessage(mailgw, message)
 This is the most complex example section. The mail gateway is also one
-of the more complex subsystems in roundup, and modifying it is not
+of the more complex subsystems in Roundup, and modifying it is not
 trivial.
 Other Examples
 --------------
 A sequence of property names that are the only properties to apply the
 new Permission to (eg. ``... klass='user', properties=('name',
 'email') ...``)
 **props_only**
 A boolean value (set to false by default) that is a new feature
-in roundup 1.6.
+in Roundup 1.6.
 A permission defined using:
 ``properties=('list', 'of', 'property', 'names')``
 is used to determine access for things other than just those
 Protecting users from web application attacks
 ---------------------------------------------
 There is a class of attacks known as Cross Site Request Forgeries
 (CSRF). Malicious code running in the browser can making a
-request to roundup while you are logged into roundup.  The
+request to Roundup while you are logged into Roundup.  The
-malicious code piggy backs on your existing roundup session to
+malicious code piggy backs on your existing Roundup session to
 make changes without your knowledge. Roundup 1.6 has support for
 defending against this by analyzing the
 * Referer,
 * Origin, and
 HTTP headers. It compares the headers to the value of the web setting
 in the [tracker] section of the tracker's ``config.ini``.
 Also a per form token (also called a nonce) can be enabled for
 the tracker using the ``csrf_enforce_token`` option in
-config.ini.  When enabled, roundup will validate a hidden form
+config.ini.  When enabled, Roundup will validate a hidden form
 field called ``@csrf``. If the validation fails (or the token
 is used more than once) the request is rejected.  The ``@csrf``
 input field is added automatically by calling the ``submit``
 function/path. It can also be added manually by calling
-anti_csrf_nonce() directly. For example:
+anti_csrf_nonce() directly. For example::
 <input name="@csrf" type="hidden"
 tal:attributes="value python:utils.anti_csrf_nonce(lifetime=10)">
 By default a nonce lifetime is 2 weeks. However the lifetime (in
 The token protects you because malicious code supplied by another
 site is unable to obtain the token. Thus many attempts they make
 to submit a request are rejected.
 The protection on the xmlrpc interface is untested, but is based
-on a valid header check against the roundup url and the presence
+on a valid header check against the Roundup url and the presence
 of the ``X-REQUESTED-WITH`` header. Work to improve this is a
 future project after the 1.6 release.
 The enforcement levels can be modified in ``config.ini``. Refer to
 that file for details.
 Templating engines
 ~~~~~~~~~~~~~~~~~~
 Since version 1.4.20 Roundup supports two templating engines:
 * the original `Template Attribute Language`_ (TAL) engine from Zope
 * the standalone Chameleon templating engine. Chameleon is intended
 as a replacement for the original TAL engine, and supports the
 same syntax, but they are not 100% compatible. The major (and most
 likely the only) incompatibility is the default expression type being
 ``python:`` instead of ``path:``. See also "Incompatibilities and
 differences" section of `Chameleon documentation`__.
 Version 1.5.0 added experimental support for the `jinja2`_ templating
 language. You must install the `jinja2`_ module in order to use it. The
 ``jinja2`` template supplied with Roundup has the templates rewritten
 to use ``jinja2`` rather than TAL. A number of trackers are running
 The following variables are available to templates.
 **context**
 The current context. This is either None, a `hyperdb class wrapper`_
 or a `hyperdb item wrapper`_
 **request**
 Includes information about the current request, including:
-- the current index information (``filterspec``, ``filter`` args,
-``properties``, etc) parsed out of the form.
+- the current index information (``filterspec``, ``filter``
-- methods for easy filterspec link generation
+args, ``properties``, etc) parsed out of the form.
-- "form"
+- methods for easy filterspec link generation
-The current CGI form information as a mapping of form argument name
+- "form"
-to value (specifically a cgi.FieldStorage)
+The current CGI form information as a mapping of form argument name
-- "env" the CGI environment variables
+to value (specifically a cgi.FieldStorage)
-- "base" the base URL for this instance
+- "env" the CGI environment variables
-- "user" a HTMLItem instance for the current user
+- "base" the base URL for this instance
-- "language" as determined by the browser or config
+- "user" a HTMLItem instance for the current user
-- "classname" the current classname (possibly None)
+- "language" as determined by the browser or config
-- "template" the current template (suffix, also possibly None)
+- "classname" the current classname (possibly None)
+- "template" the current template (suffix, also possibly None)
 **config**
 This variable holds all the values defined in the tracker config.ini
 file (eg. TRACKER_NAME, etc.)
 **db**
 The current database, used to access arbitrary database items.
 roman           Current position in the sequence as lowercase roman
 numerals.
 Roman           Same as roman(), except uppercase.
 =============== =========================================================
+.. _templating utilities:
 The utils variable
 ~~~~~~~~~~~~~~~~~~
-.. _templating utilities:
 This is implemented by the
 ``roundup.cgi.templating.TemplatingUtils`` class, which may be extended
 with additional methods by extensions_.
 </td>
 </tr>
 The ``context/submit`` bit generates the submit button but also
 generates the @action and @csrf hidden fields. The @action field is
-used to tell roundup how to process the form. The @csrf field provides
+used to tell Roundup how to process the form. The @csrf field provides
 a unique single use token to defend against CSRF attacks. (More about
 anti-csrf measures can be found in ``upgrading.txt``.)
 Finally we finish off the tags we used at the start to do the METAL
 stuff::
 Finally we have to edit ``html/page.html`` again. This time, we need to
 tell it that when the user clicks on "Unassigned Issues" or "All Issues",
 the category column should be included in the resulting list. If you
 scroll down the page file, you can see the links with lots of options.
 The option that we are interested in is the ``:columns=`` one which
-tells roundup which fields of the issue to display. Simply add
+tells Roundup which fields of the issue to display. Simply add
 "category" to that list and it all should work.
 Adding a time log to your issues
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 On some systems the primary store of users is the UN*X passwd file. It
 holds information on users such as their username, real name, password
 and primary user group.
 Roundup can use this store as its primary source of user information,
-but it needs additional information too - email address(es), roundup
+but it needs additional information too - email address(es), Roundup
-Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
+Roles, vacation flags, Roundup hyperdb item ids, etc. Also, "retired"
 users must still exist in the user database, unlike some passwd files in
 which the users are removed when they no longer have access to a system.
 To make use of the passwd file, we therefore synchronise between the two
 user stores. We also use the passwd file to validate the user logins, as
 validation source`_. We keep the user lists in sync using a fairly
 simple script that runs once a day, or several times an hour if more
 immediate access is needed. In short, it:
 1. parses the passwd file, finding usernames, passwords and real names,
-2. compares that list to the current roundup user list:
+2. compares that list to the current Roundup user list:
 a. entries no longer in the passwd file are *retired*
 b. entries with mismatching real names are *updated*
 c. entries only exist in the passwd file are *created*
 Using an LDAP database for user information
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A script that reads users from an LDAP store using
 https://pypi.org/project/python-ldap/ and then compares the list to the users in the
-roundup user database would be pretty easy to write. You'd then have it run
+Roundup user database would be pretty easy to write. You'd then have it run
 once an hour / day (or on demand if you can work that into your LDAP store
 workflow). See the example `Using a UN*X passwd file as the user database`_
 for more information about doing this.
 To authenticate off the LDAP store (rather than using the passwords in the
 def init(instance):
 '''Override the default edit action with this new version'''
 instance.registerAction('edit', Edit2Action)
-This code is a wrapper for the roundup EditItemAction. It checks the
+This code is a wrapper for the Roundup EditItemAction. It checks the
 form's submit button to save the value element. The rest of the changes
 needed for the Silent Submit feature involves editing
 html/issue.item.html to add the silent submit button. In
 the stock issue.item.html the submit button is on a line that contains
 "submit button". Replace that line with something like the following::

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 7268:91125d474c1e