XEmacs Tracker: User's Guide


This User Guide documents the XEmacs Issue Tracker at http://tracker.xemacs.org/.

It is based on user_guide.txt from the Roundup 1.4.2 distribution, but has been radically change to adapt it to XEmacs. Please report any bugs you find in it in the XEmacs Issue Tracker, module "tracker", keyword "doc incorrect" or "needs doc". If you are unable to register, send mail to <xemacs-services@xemacs.org>.

We're always happy to have help with "issue triage". If you'd like to volunteer, just review the classification guidelines below. Then go ahead and get started!


Registering a User in the XEmacs Tracker

The registration link is in the middle of the Login block in the sidebar. In principle, registration is simple. You give Roundup your preferred user name, password, full name, and principal email address, and (optionally) alternate email addresses. Roundup sends you a confirmation email, you reply to it, and you're registered.

In practice, it's a little harder than that. First, email delays will be experienced because first all email to the tracker needs to go through moderation (until I feel more confident that tracker spamming can be prevented), and then the tracker gets email once an hour on a cron job. (Eventually the tracker host will get a proper MX and that delay will be eliminated, too.) Outgoing email should be immediate, though. Your patience is greatly appreciated!

Second, if you happen to be one of the lucky contributers to have your issue already posted to the tracker via email, your email address will probably have already been registered, and you won't be able to register immediately.

If this happens, please bear with us and do one of the following things:

Once you have a user registered, you can change anything, including your username and principal email address, from the "Your Details" page linked from the "Hello, user" block of the sidebar. The only caveat is that it's difficult to change your principal email address to one of the alternate addresses or vice versa (there's a race condition checking for previous use of the email; someday I'll fix that).

The XEmacs Tracker in a Nutshell

The tracker holds information about issues in objects called items. Currently there are two classes of items: Issues and Users.


Note three conventions here: the first use of a term that makes clear its meaning is italicized. Classes of Roundup objects are Capitalized. Thus a user is a person, while a User is an object in the tracker database that represents a person. User Roles are also capitalized (described below). In general, most Roundup classes correspond quite closely to the real entities they model, and capitalization will only be used when introducing the term, and when making the distinction between Roundup objects and reality is important. It's almost always important when discussing human interaction with the system, so User Roles and those properties of Issues that take User values will always be capitalized. In a sort of abuse of notation, a person may be described as having a Roundup Role; obviously that means that the User representing that person has the specified Role.

Each item in the tracker has, along with its item class, an ID number that identifies it. To identify a particular Issue or User, we combine the class with the number to create a unique label, so that User 1 (who, incidentally, is always the "admin" user) is referred to as "user1". Issue number 315 is referred to as "issue315". This label is the item's designator.

Items in the database are never deleted, they're just "retired". You can still refer to them by ID - hence removing an item won't break references to it, and the item will continue to be properly displayed when an object referring to it is displayed. It's just that the item won't appear in any listings of "active" items of that type, including menus. You have to know it's there to reference it.

The Purpose of the Tracker

The tracker is intended to maintain the status of issues. It is not a good place for discussion, because it displays all comments in most-recent order, and you must scroll through them to find the information you want. Try to keep comments to short summaries, and to refer discussion to mailing lists. Longer commentary is most useful if it takes the form of a patch to the manuals.

Patches should not be pasted into the comments, but uploaded as separate files. The comment should indicate which patch(es) is (are) considered the current candidate for application to XEmacs. The obvious exception is for patches submitted by email, but even then most MUAs allow you to attach a patch as a file.

If the OP doesn't provide a test or recipe for reproduction of a bug, then exactly one "me too" comment is appropriate, and the status field should be bumped to "verified".

Accessing the Tracker

You may access the tracker in one of three ways:

  1. through the web interface,
  2. through the e-mail gateway, or
  3. using the command line tool.

The last is accessible only to administrators. Other users must use the web and e-mail interfaces. All three are explained below.

Issue Description and Classification

Issues are described by the required Title property and an optional Change Note. The Change Note can refer to Users, Messages, and other Issues by designators (like "user1", "msg32", or "issue222"). These are automatically converted to links by Roundup. (It is often important that a superseding Issue reference the Issue(s) it supersedes. This information is also available in the superseding Issue's history, but that's a little obscure.)

Issues are classified according to the required properties Type, Severity, Module, and Platform. Type defaults to "defect", and severity to "inconvenience". Platform currently has a default of "N/A", but this may change. The set of Modules includes several modules relating to the core C and Lisp code implementing the Emacs Lisp and editor primitives, modules relating to XEmacs services including the website, mailing lists, code repositories, and this tracker itself.

Type values

Type Description
"defect" behavior and documentation differ
"feature" new behavior is desired
"patch" a contribution of an implementation
"discuss" other; rarely appropriate

In general, issues of type "defect" may be resolved by correcting either the behavior or the documentation at the discretion of the XEmacs Development Team. Some documentation is implicit. For example, unless explicitly documented, it is reasonable to expect that the development mainline version will be compatible with recent GNU Emacs. A request to sync XEmacs to GNU Emacs may be reported with type "defect" or with type "feature" at the user's discretion. If XEmacs is explicitly documented to behave differently from GNU Emacs, a request to sync should be given type "feature".

The "patch" type indicates an issue that enters the tracker with an unsolicited implementation of a fix for a defect or a new feature. Patches will generally be treated as more important than other issues.

The "discuss" type is deprecated (discussions should take place on the general mailing lists, not in the tracker) and may be removed.

Platform values

Platform Description
"x86" CPU affected by the issue. "x86" should be assumed to be 32-bit. "ppc" covers both 32- and 64-bit versions.
"other cpu"
"unix" OS affected by the issue.
"other os"
"tty" User interface affected by the issue. "batch" is the no-console "xemacs -batch" invocation. "stream" is a direct interface to stdin/stdout without supporting full-screen operations like arbitrary cursor addressing (i.e., you're limited to princ and terpri). "tty" is an interface to a smart terminal that supports full-screen operations. The rest are the popular graphical user interfaces, at the level of "toolkits".
"other ui"
"N/A" Not applicable.

The table above shows the current list of distinguished platforms. The Platform property is a multilink, which means that several of the values may be selected simultaneously. So for example you may indicate that an issue affects both the "xt" and "gtk" GUIs on "unix" running on the "x86" CPU. The "N/A" platform means "not applicable". "N/A" is appropriate for most issues affecting Lisp and service modules.

The list is obviously incomplete, for example XEmacs is known to run on the Sparc and Alpha families of CPUs. Unix and NT could clearly each be subdivided and so on. The current list reflects the list of CPUs that the developers have access to and relevant experience with. It's easy to add more, but there's no point in trying to flag the attention of the developers with expertise on the HPPA platform when we don't have any. If you're willing to provide at least the service of helping to reproduce a problem when it's restricted to a platform not listed here explicitly, feel free to ask for its inclusion. Otherwise, it's a more honest reflection of the services we can provide for that platform's users to list it as "other", and current policy is to limit the selection of platforms to those that we can easily test and develop on.

Severity values

Severity Description
"crash" XEmacs exits inappropriately
"hang" XEmacs becomes completely unresponsive
"data loss" includes unrecoverable buffer corruption
"security" privacy violation, privilege escalation
"much work obstructed" a whole field of work is impossible
"some work obstructed" some useful operations are impossible
"inconvenience" workarounds are available
"inelegance" effective enough, but unattractive

The Severity property is the province of the reporting user, and measures the degree to which she is affected. The severities are more or less ordered (the first four are clearly more important than the last four, and the last four are listed in descending order of importance). Severity may generally be expected to correspond to Priority for the developers, but not always.

The security severity is special; only users with the Reviewer or Admin roles can see these issues, and they will not even appear in indexes or search results. (Currently not even the reporter can see a security issue.)


A user may assign Keywords to the issue. Although Keywords may be entered by hand as well as selected from a list, each Keyword must be registered before being used. Any user may create Keywords. However, before creating a Keyword, search carefully for an existing Keyword that serves the purpose. Proliferation of Keywords will make them less useful for issue filtering, and also make the selection interface clumsy.

If you identify Keywords that can be consolidated or simply retired, file a bug for them. An administrator can edit the Keyword list through the class view. Retired Keywords will remain available to issues that already reference them, but will not be available to add to issues in the future.

Issue life cycles and the development process

New issues may be submitted via the web or e-mail. The progress of work on the issue is summarized by the Status property, which takes on the following values.

Status values

Status Description
"new" submitted but no activity yet
"napping" a week of inactivity
"deferred" a month of inactivity / intentionally set aside
"verified" a developer or second user confirms the issue
"assigned" a developer has accepted responsibility
"committed" a change has been developed, tested, and committed
"documented" "committed" plus any relevant documentation committed
"done/needs work" enough of the proposed work is done to reduce priority
"closed" the work has been approved by a Reviewer

Users who are interested in the issue may add their Users to the issue's nosy list to receive mail when the issue is updated. The only Users automatically added to the nosy list are the "Assigned To" Developer and the Creator (the submitter of the original post). Note that if "Assigned To" changes, the former responsible developer is not automatically removed. (Creator can't be changed.)

By default, the newly created issue will have the status "new". The idealized timeline for an issue proceeds from "new", to "verified", "assigned", "committed", "documented" and finally "closed." While the various tasks may not be accomplished in that order, for example "committed" implies that an issue has been submitted and verified, and a Developer has accepted responsibility for the issue and committed an appropriate change. On the other hand, a patch might be offered by the submitter, but until the changed behavior has been confirmed to be desirable, the issue must stay in the "new" status because it hasn't been verified.

The "assigned" status should be accompanied by setting the Assigned-To Developer (and vice-versa; this is currently not enforced by the tracker). Users who have the Developer role will appear in the menu, as well as an item "Assign to me", i.e., the logged-in User (the logged-in User does not need to have the Developer role). Many contributors of small patches may want to assign the issue to themselves even though they aren't interested in more general participation in the project. If you are quite sure that a given Developer has an interest in that kind of issue, you may assign it to them, but in general you should only assign to yourself. Instead, mention the issue on the public discussion channels, like the XEmacs Beta mailing list.

When an issue's status is set to "closed", most standard queries will not display it in the list of results.

The "napping", "deferred", "documented", and "closed" statuses are special. The "napping" status is automatically assigned by Roundup when a week has passed with no activity by any Developer. (In the table of status values, the word "activity" implies the actor has Developer status in Roundup.) It will also be assigned by Roundup when a closed issue is reopened. In general, users (including Developers and Reviewers) should not assign the "napping" status. The "deferred" status is automatically assigned after a month of inactivity, or may be assigned by the Assigned To Developer, or by a Reviewer. The "closed" status may be assigned only by a Reviewer, or the maintainer of a Lisp package. The "documented" status may be used by the Creator to withdraw it.

In the XEmacs tracker, once an issue has been assigned, the convention is that only the Assigned To Developer (the developer listed in the Assigned To field) may update Status of the issue. (If necessary Reviewers may update the status, and only Reviewers may close an issue.) If the issue has not been verified, the Creator of the Issue may withdraw it by setting status to "documented", optionally providing a rationale in the Change Note, and setting the reason to "not a bug". Alternatively, any User may update a "new" issue to "verified". They should provide a Change Note explaining how they verified it. (The Creator should provide more than just "it happened again." A reproduction recipe or a formal test would be appropriate.)

An issue that is closed will have an associated Reason.

Reason values

Reason Description
"fixed" the issue was resolved and documented
"not a bug" any problem was external to XEmacs
"superseded" another issue subsumes this one
"won't fix" the problem is acknowledged but refused
"not our bug" the problem is acknowledged by another project

The "not a bug" reason means that behavior of XEmacs is as expected and is considered desirable. Typically the bug report is due to a user misunderstanding, or a difference of opinion about good design. The "not our bug" reason is used only when the defect has been determined to be in software upstream or downstream of XEmacs, and is acknowledged as such by the responsible project. In the absence of such acknowledgement (including the case of a defunct project or AWOL or recalcitrant maintainer), the issue should be closed as "won't fix". The reason, like the status, is the property of the responsible developer who closes the issue.

When a issue is closed because of a superseding issue, the number (not the designator) of the superseding issue should be entered in the superseder property. The superseder property is a multilink, so several superseding issues can be indicated.

Priority values

Priority Description
"critical" preempts all non-critical work
"urgent" should be done by next release
"normal" most issues have normal priority
"cosmetic" typos and poor formatting of display

The priority is generally the "property" of the responsible Developer, or the XEmacs Review Board.

Users, Roles, and properties

In Roundup, each user, whether submitter, developer, or tracker administrator, must register a User with the tracker. The User is strongly associated with a list of email addresses used to identify incoming mail from that user. (The tracker may be upgraded to authenticate and authorize users via PGP.) The user's identity is encapsulated in an object named something like "User1" (that is in fact the original Admin user). So you can actually change both your primary address (which Roundup uses to contact you, as well as identify email submissions) and the alternate addresses (used to identify email submissions). However these addresses must be unique in the system since they identify users, and there are several conditions in which you may encounter conflicts. In that case get in touch with the tracker adminstrator, Stephen Turnbull stephen@xemacs.org.

Each user may have several Roles, to which are attached various privileges when that user is logged in to the tracker. The project roles, which have various privileges, are Anonymous, User, Developer, and Reviewer. These privileges are not necessarily strictly increasing, so make sure you have all the roles you need and are authorized to have. There is also a Role called Admin that authorizes tracker administrators. Each User object automatically receives the User role.

The Developer role is assigned to any user who would like to volunteer to work on some area of interest to them. The difference between a Developer and a User is that Developers' names appear in the Assigned-To menu. Any user can assign an issue to themself. Being a Developer means that you're volunteering to have others assign appropriate issues to you. If you're not working on XEmacs almost daily, and regularly contributing patches, we would prefer that you not take the Developer role -- you can already assign to yourself, and nobody else knows your expertise, so they won't assign to you anyway. It just clutters the menu.

If you haven't been active in XEmacs, but would like to contribute by working on some specific area, you are welcome to add the Developer role to your user. But remember that it's not useful unless others know what you're good at. If you're not well-known yet, post to the XEmacs Contributors list <xemacs-beta@xemacs.org> and introduce yourself, and describe the kinds of issues (bugs or features) you want people to assign to you.

Reviewers are allowed to do things like close issues that they don't own. Only the adminstrator can create Reviewers.

The Roles should not be confused with the issue properties of Actor (a User who changes an issue), Assigned To (a Developer responsible for resolving an issue), and Creator (the User of the original submitter of the issue). They do confer special privileges in some circumstances, but only for the associated issue. On the other hand, the privileges conferred by a Role are global.

Activity properties

Several activity properties are automatically updated. These are Creator, Creation Date, Submitted, Actor, and Activity Date. The creator is the user who first submitted the issue, and the creation date the timestamp of submission. Because some issues have been imported in bulk from other databases (specifically the mailing list archives), it is useful to maintain a "submitted" field, which is initialized to the date of first submission (e.g., the RFC 2822 Date header for a mailing list or Usenet post). Actor and activity date are the user who most recently updated any of the properties of the issue, and the timestamp of the activity, respectively.

Issue Triage Guidelines

Volunteers of any level of experience are welcome to help classify as yet unclassified issues. You can do as many or as few as you like.

As a small incentive, normally the "priority" attribute is property of the Reviewers and/or the developer who takes responsibility for the issue, but for unclassified issues you are encouraged to set the priority (with some constraints explained below).


  1. Register your user (or use "Forgot Your Login?" to get a temporary password assigned if you already have one from a preloaded issue).
  2. Use the "Show Open" query in the "Issues" block of the sidebar to list open queries. The unclassified issues will show up as "(no priority set)" at the top of the list.
  3. Pick an item, click on the Title to edit it.
  4. Review the issue, and
    1. set the module (required, no default)
    2. set the platform (required, default is "N/A" which is the best setting for Lisp bugs -- platform should be set appropriately for crashes, build problems, and GUI bugs); note that multiple platforms may be selected
    3. set the severity, which is an assessment from the user's point of view of how important the issue is (required, default is "inconvenience"); note that if you set the severity to "security", and save the issue, you will not be able to edit it again (unless you are a Reviewer or Tracker admin)
    4. (optionally) set keywords, creating them if necessary; try to avoid creating keywords as the interface is still clumsy; note that multiple keywords may be selected
    5. (optionally) set priority, which is a guide to the urgency with which the developers should work on the issue (default is "normal")
    6. (optionally) review and edit the title, for example to remove the "[Bug: " prefix from M-x report-xemacs-bug.

Setting priority:

  1. Don't demote a bug you haven't experienced to "cosmetic" unless it's really really obviously cosmetic (eg a doc typo).
  2. Don't promote a bug to "critical". At the moment there's no show to stop :-( so there are no showstoppers.
  3. Don't change priority of an issue that has an Assigned To developer. That indicates the developer's assessment of when he'll get to it.
  4. At most 25 urgent bugs are allowed. If your bug makes it into the top 25 in your opinion, and there are already 25 urgent bugs, then pick one to demote to "normal" priority. Don't worry about getting the "least important" one, but be polite: if you can't find one that the developers will clearly consider less important than yours, you probably should not be promoting yours!

Setting status:

  1. Be conservative about updating status. You should only push status to "committed", "documented", or "closed" if you understand the issue and any related patches or documentation well enough to have written them yourself. (That doesn't mean you need to be able to write it in English!) If you find yourself doing this more than once or twice, consider nominating yourself for XEmacs Reviewer. (No joke, we always need more reviewers!)
  2. An issue should not be closed until you've confirmed that the issue is documented in the appropriate places. The mailing list archives do not count as documentation!
  3. Missing, incorrect, or hard-to-find documentation is a bug in itself, even if the related behavior is acceptable. Do not close an issue as "not a bug" simply because somebody explained why it works that way on the mailing list.
  4. If you find a patch labelled "committed" in the tracker, it's OK to assign the issue to the committer as committing a patch is a definite assumption of responsibility. However, by default you should bump status only as far as "assigned".

Setting keywords:

Keywords are important!

  1. Some keywords are workflow-related, the "has X" and "needs X" keywords in particular. The "has X" keyword means that such an item has been contributed, typically by the issue's creator, and needs to be confirmed before committing the change. The "needs X" keyword means that such an item must be developed and committed to resolve the issue.

    The "has X" and "needs X" keywords are not opposites. When a contributed X is verified and committed, the "has X" keyword should be removed. Similarly, when an X is developed and committed, the "needs X" keyword should be removed.

  2. Other keywords refer to XEmacs behavior, and are helpful to users in filtering out issues unrelated to their problem.

    At present, the following keywords for general areas of XEmacs behavior are available: display, i18n, input/output, motion, performance, search, and security. Feel free to add more if appropriate, but as mentioned I'd like to keep the number small for now. Try to keep new keywords at a pretty high level of generality.

Entering values in your Tracker

All interfaces to your tracker use the same format for entering values. This means the web interface for entering a new issue, the web interface for searching issues, the e-mail interface and even the command-line administration tool.

String and Numeric properties

These fields just take a simple text value, like It's broken.

Boolean properties

These fields take a value which indicates "yes"/"no", "true"/"false", "1"/"0" or "on"/"off".

Date properties

Date-and-time stamps are specified with the date in international standard format (yyyy-mm-dd) joined to the time (hh:mm:ss) by a period .. Dates in this form can be easily compared and are fairly readable when printed. An example of a valid stamp is 2000-06-24.13:03:59. We'll call this the "full date format". When Timestamp objects are printed as strings, they appear in the full date format.

For user input, some partial forms are also permitted: the whole time or just the seconds may be omitted; and the whole date may be omitted or just the year may be omitted. If the time is given, the time is interpreted in the user's local time zone. The Date constructor takes care of these conversions. In the following examples, suppose that yyyy is the current year, mm is the current month, and dd is the current day of the month.

  • "2000-04-17" means <Date 2000-04-17.00:00:00>
  • "01-25" means <Date yyyy-01-25.00:00:00>
  • "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
  • "08-13.22:13" means <Date yyyy-08-14.03:13:00>
  • "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
  • "14:25" means
  • <Date yyyy-mm-dd.19:25:00>
  • "8:47:11" means
  • <Date yyyy-mm-dd.13:47:11>
  • the special date "." means "right now"

When searching, a plain date entered as a search field will match that date exactly in the database. We may also accept ranges of dates. You can specify range of dates in one of two formats:

  1. English syntax:

    [From <value>][To <value>]

    Keywords "From" and "To" are case insensitive. Keyword "From" is optional.

  2. "Geek" syntax:


Either first or second <value> can be omitted in both syntaxes.

For example, if you enter string "from 9:00" to "Creation date" field, roundup will find all issues, that were created today since 9 AM.

The <value> may also be an interval, as described in the next section. Searching of "-2m; -1m" on activity field gives you issues which were active between period of time since 2 months up-till month ago.

Other possible examples (consider local time is 2003-03-08.22:07:48):

  • "from 2-12 to 4-2" means <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
  • "FROM 18:00 TO +2m" means <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
  • "12:00;" means <Range from 2003-03-08.12:00:00 to None>
  • "tO +3d" means <Range from None to 2003-03-11.20:07:48>
  • "2002-11-10; 2002-12-12" means <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
  • "; 20:00 +1d" means <Range from None to 2003-03-09.20:00:00>
  • "2003" means <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
  • "2003-04" means <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>

Interval properties

Date intervals are specified using the suffixes "y", "m", and "d". The suffix "w" (for "week") means 7 days. Time intervals are specified in hh:mm:ss format (the seconds may be omitted, but the hours and minutes may not).

  • "3y" means three years
  • "2y 1m" means two years and one month
  • "1m 25d" means one month and 25 days
  • "2w 3d" means two weeks and three days
  • "1d 2:50" means one day, two hours, and 50 minutes
  • "14:00" means 14 hours
  • "0:04:33" means four minutes and 33 seconds

Simple support for collision detection

Item edit pages remember when the item was last edited. When a form is submitted, the user will be informed if someone else has edited the item at the same time they tried to.

Web Interface


This document does not provide screenshots of the default look and feel. You may wish to look at the vendor's documentation for those.

The web interface is broken up into the following parts:

  1. lists of items,
  2. display, edit or entry of an item, and
  3. searching page.

Lists of Items

The first thing you'll see when you log into Roundup will be a list of open (ie. not resolved) issues. This list has been generated by a bunch of controls under the covers but for now, you can see something like:


The screen is divided up into three sections. There's a title which tells you where you are, a sidebar which contains useful navigation tools and a body which usually displays either a list of items or a single item from the tracker.

You may either register or log in. Registration takes you to:


Once you're logged in, the sidebar changes to:


You can now get to your "My Details" page:


Display, edit or entry of an item

Create a new issue with "create new" under the issue subheading. This will take you to:


Editing an issue uses the same form, though now you'll see attached files and messages, and the issue history at the bottom of the page:


These screens currently require a geometry of about 1000x750 for comfort.

Searching Page

Most values in the search form are entered via popup menus. The All Text and Title fields are free text. The ID field is an item designator. Creation Date and Activity are dates, times, or intervales. See entering values in your tracker for an explanation of what you may type into the search form.

Most popup menus have two special values: "don't care" and "unselected". "don't care" means that any value is acceptable. "unselected" means that no value have been set for this field. This is normally possible only for issues submitted by email. Use of the "unselected" value is useful to find issues which need to be updated to provide the information necessary to usefully search for them. The status menu in the search form has a third value: "unresolved." This means any of the values except "done/needs work" and "closed" (including the special value "unselected"). This is a good way to find current issues to work on.

You can also select one field to group on and one to sort on initially. The groups will be ordered according to the order for values of the "group on" property. Within each group, the items will be ordered according to the order for values of the "sort by" property. You can change or refine the grouping and sorting with the controls at the bottom of each search results page. If there is a large number of results (by default, more than 50), the list will be broken up into multiple pages. The query itself, as well as the sorting and grouping (including any refinements) will persist as you page through the list.

Saving queries

You may save queries in the tracker by giving the query a name. Each user may only have one query with a given name - if a subsequent search is performed with the same query name supplied, then it will edit the existing query of the same name.

Queries may be marked as "private". These queries are only visible to the user that created them. If they're not marked "private" then all other users may include the query in their list of "Your Queries". Marking it as private at a later date does not affect users already using the query, nor does deleting the query.

If a user subsequently creates or edits a public query, a new personal version of that query is made, with the same editing rules as described above.

Under the covers

The searching page converts your selections into the following arguments:

Argument Description
@sort sort by prop name, optionally preceeded with '-' to give descending or nothing for ascending sorting. The sort argument can have several props separated with comma.
@group group by prop name, optionally preceeded with '-' or to sort in descending or nothing for ascending order. The group argument can have several props separated with comma.
@columns selects the columns that should be displayed. Default is all.
@filter indicates which properties are being used in filtering. Default is none.
propname selects the values the item properties given by propname must have (very basic search/filter).
@search_text performs a full-text search (message bodies, issue titles, etc)

You may manually write URLS that contain these arguments, like so (whitespace has been added for clarity):


Access Controls

User access is controlled through Permissions. These are are grouped into Roles, and users have a comma-separated list of Roles assigned to them.

Permissions divide access controls up into answering questions like:

  • may the user edit issues ("Edit", "issue")
  • is the user allowed to use the web interface ("Web Access")
  • may the user edit other user's Roles through the web ("Web Roles")

Any number of new Permissions and Roles may be created as described in the customisation documentation. Examples of new access controls are:

  • only managers may sign off issues as complete
  • don't give users who register through e-mail web access
  • let some users edit the details of all users

E-Mail Gateway

Roundup trackers may be used to facilitate e-mail conversations around issues. The "nosy" list attached to each issue indicates the users who should receive e-mail when messages are added to the issue.

When e-mail comes into a tracker that identifies an issue in the subject line, the content of the e-mail is attached to the issue.

You may even create new issues from e-mail messages.

E-mail sent to a tracker is examined for several pieces of information:

  1. subject-line information identifying the purpose of the e-mail
  2. sender identification using the sender of the message
  3. e-mail message content which is to be extracted
  4. e-mail attachments which should be associated with the message

Subject-line information

The subject line of the incoming message is examined to find one of:

  1. the item that the message is responding to,
  2. the type of item the message should create, or
  3. we default the item class and try some trickiness

If the subject line contains a prefix in [square brackets] then we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are stripped off the subject line before we start looking for real information.

If an item designator (class name and id number, for example issue123) is found there, a new "msg" item is added to the "messages" property for that item, and any new "file" items are added to the "files" property for the item.

If just an item class name is found there, we attempt to create a new item of that class with its "messages" property initialized to contain the new "msg" item and its "files" property initialized to contain any new "file" items.

The third case above - where no [information] is provided, the tracker's MAIL_DEFAULT_CLASS configuration variable defines what class of item the message relates to. We try to match the subject line to an existing item of the default class, and if there's a match, the message is related to that matched item. If not, then a new item of the default class is created.

Setting Properties

The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command.

For example,

  • setting the priority of an issue:

    Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
  • adding yourself to a nosy list:

    Subject: Re: [issue2] we're out of widgets [nosy=+richard]
  • setting the nosy list to just you and cliff:

    Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
  • removing yourself from a nosy list and setting the priority:

    Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]

In all cases, the message relates to issue 2. The Re: prefix is stripped off.

Automatic Properties

status of new issues
When a new message is received that is not identified as being related to an existing issue, it creates a new issue. The status of the new issue is defaulted to "unread".
reopening of resolved issues
When a message is is received for a resolved issue, the issue status is automatically reset to "chatting" to indicate new information has been received.

Sender identification

If the sender of an e-mail is unknown to Roundup (looking up both user primary e-mail addresses and their alternate addresses) then a new user will be created. The new user will have their username set to the "user" part of "user@domain" in their e-mail address. Their password will be completely randomised, and they'll have to visit the web interface to have it changed. Some sites don't allow web access by users who register via e-mail like this.

E-Mail Message Content

Roundup only associates plain text (MIME type text/plain) as messages for items. Any other parts of a message are associated as downloadable files. If no plain text part is found, the message is rejected.

To do this, incoming messages are examined for multiple parts:

  • In a multipart/mixed message or part, each subpart is extracted and examined. The text/plain subparts are assembled to form the textual body of the message, to be stored in the file associated with a "msg" class item. Any parts of other types are each stored in separate files and given "file" class items that are linked to the "msg" item.
  • In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts.

If the message is a response to a previous message, and contains quoted sections, then these will be stripped out of the message if the EMAIL_KEEP_QUOTED_TEXT configuration variable is set to 'no'.

Message summary

The "summary" property on message items is taken from the first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin with a ">" or "|" character are considered "quoting sections". The first line of the first non-quoting section becomes the summary of the message.

Address handling

All of the addresses in the To: and Cc: headers of the incoming message are looked up among the tracker users, and the corresponding users are placed in the "recipients" property on the new "msg" item. The address in the From: header similarly determines the "author" property of the new "msg" item. The default handling for addresses that don't have corresponding users is to create new users with no passwords and a username equal to the address.

The addresses mentioned in the To:, From: and Cc: headers of the message may be added to the nosy list depending on:

Does the author of a message get placed on the nosy list automatically? If 'new' is used, then the author will only be added when a message creates a new issue. If 'yes', then the author will be added on followups too. If 'no', they're never added to the nosy.
Do the recipients (To:, Cc:) of a message get placed on the nosy list? If 'new' is used, then the recipients will only be added when a message creates a new issue. If 'yes', then the recipients will be added on followups too. If 'no', they're never added to the nosy.

Nosy List

Roundup watches for additions to the "messages" property of items.

When a new message is added, it is sent to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom.

If the author of the message is also in the nosy list for the item that the message is attached to, then the config var MESSAGES_TO_AUTHOR is queried to determine if they get a nosy list copy of the message too.

Mail gateway script command line


roundup-mailgw [[-C class] -S field=value]* <instance home> [method]

The roundup mail gateway may be called in one of three ways:

  • with an instance home as the only argument,
  • with both an instance home and a mail spool file, or
  • with both an instance home and a pop server account.

It also supports optional -C and -S arguments that allows you to set a fields for a class created by the roundup-mailgw. The default class if not specified is msg, but the other classes: issue, file, user can also be used. The -S or --set options uses the same property=value[;property=value] notation accepted by the command line roundup command or the commands that can be given on the Subject line of an e-mail message.

It can let you set the type of the message on a per e-mail address basis.

In the first case, the mail gateway reads a single message from the standard input and submits the message to the roundup.mailgw module.
UNIX mailbox:

In the second case, the gateway reads all messages from the mail spool file and submits each in turn to the roundup.mailgw module. The file is emptied once all messages have been successfully handled. The file is specified as:

mailbox /path/to/mailbox

In the third case, the gateway reads all messages from the POP server specified and submits each in turn to the roundup.mailgw module. The server is specified as:

pop username:password@server

The username and password may be omitted:

pop username@server
pop server

are both valid. The username and/or password will be prompted for if not supplied on the command-line.


Same as POP, but using Authenticated POP:

apop username:password@server

Command Line Tool

The basic usage is:

Usage: roundup-admin [options] [<command> <arguments>]

 -i instance home  -- specify the issue tracker "home directory" to administer
 -u                -- the user[:password] to use for commands
 -d                -- print full designators not just class id numbers
 -c                -- when outputting lists of data, comma-separate them.
              Same as '-S ","'.
 -S <string>       -- when outputting lists of data, string-separate them
 -s                -- when outputting lists of data, space-separate them.
              Same as '-S " "'.

 Only one of -s, -c or -S can be specified.

 roundup-admin -h
 roundup-admin help                       -- this help
 roundup-admin help <command>             -- command-specific help
 roundup-admin help all                   -- all available help

 create classname property=value ...
 display designator[,designator]*
 export [class[,class]] export_dir
 find classname propname=value ...
 get property designator[,designator]*
 help topic
 history designator
 import import_dir
 initialise [adminpw]
 install [template [backend [admin password]]]
 list classname [property]
 pack period | date
 retire designator[,designator]*
 security [Role name]
 set items property=value property=value ...
 specification classname
 table classname [property[,property]*]
Commands may be abbreviated as long as the abbreviation matches only one
command, e.g. l == li == lis == list.

All commands (except help) require a tracker specifier. This is just the path to the roundup tracker you're working with. A roundup tracker is where roundup keeps the database and configuration file that defines an issue tracker. It may be thought of as the issue tracker's "home directory". It may be specified in the environment variable TRACKER_HOME or on the command line as "-i tracker".

A designator is a classname and an itemid concatenated, eg. bug1, user10, ... Property values are represented as strings in command arguments and in the printed results:

When multiple items are specified to the roundup get or roundup set commands, the specified properties are retrieved or set on all the listed items. When multiple results are returned by the roundup get or roundup find commands, they are printed one per line (default) or joined by commas (with the "-c" option).

Where the command changes data, a login name/password is required. The login may be specified as either "name" or "name:password".

If either the name or password is not supplied, they are obtained from the command-line.

Using with the shell

With version 0.6.0 or newer of roundup (which introduced support for multiple designators to display and the -d, -S and -s flags):

To find all messages regarding chatting issues that contain the word "spam", for example, you could execute the following command from the directory where the database dumps its files:

shell% for issue in `roundup-admin -ds find issue status=chatting`; do
> grep -l spam `roundup-admin -ds ' ' get messages $issue`
> done

Or, using the -dc option, this can be written as a single command:

shell% grep -l spam `roundup get messages \
    \`roundup -dc find issue status=chatting\``

You can also display issue contents:

shell% roundup-admin display `roundup-admin -dc get messages \
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-16.21:23:03
messageid: None
summary: jkdskldjf
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-15.01:59:11
messageid: None
summary: jlkfjadsf

or status:

shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
      -dc -i /var/roundup/sysadmin get status issue3,issue1`

or status on a single line:

shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
         -dc -i /var/roundup/sysadmin get status issue3,issue1\``
unread deferred

which is the same as:

shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
         -dc -i /var/roundup/sysadmin get status issue3,issue1`
unread deferred

Also the tautological:

shell% roundup-admin get name \
   `roundup-admin -dc get status \`roundup-admin -dc find issue \

Remember the roundup commands that accept multiple designators accept them ',' separated so using '-dc' is almost always required.

Back to Table of Contents