User Guide. September 28, Your Tracker in a Nutshell Accessing the Tracker... 2

Transcription

1 User Guide September 28, 2002 version 1.9 Contents 1 Your Tracker in a Nutshell Accessing the Tracker Contents Your Tracker in a Nutshell Accessing the Tracker Web Interface Lists of Items Display, edit or entry of an item Searching Page Under the covers Access Controls Gateway Subject-line information Setting Properties Message Content Message summary Address handling Nosy List Command Line Tool Note: this document will refer to issues as the primary store of information in the tracker. This is the default of the classic template, bubt may vary in any given installation. 1

2 1 Your Tracker in a Nutshell Your tracker holds information about issues in bundles we call items. An item may be an issue (a bug or feature request) or a user. The issue-ness or user-ness is called the item s class. So, for bug reports and features, the class is issue, and for users the class is user. Each item in the tracker has an id number that identifies it along with its item class. 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. We call that label the item s designator. 1.1 Accessing the Tracker You may access your tracker through one of three ways: 1. through the web interface, 2. through the gateway, or 3. using the command line tool. The last is usually only used by administrators. Most users will use the web and interfaces. All three are explained below. Web Interface Note: this document contains screenshots of the default look and feel. Your site may have a slightly (or very) different look, but the functionality will be very similar, and the concepts still hold. 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: you may either register or log in. Registration takes you to: Once you re logged in, the screen changes slightly to: Note that the sidebar menu has changed slightly, so you can now get to your My Details page: Note the new information on this page - the history. Display, edit or entry of an item Create a new issue with create new under the issue subheading. This will take you to: The nosy list is explained below. Enter some information and click submit new entry and you ll be rewarded with: or, if you don t enter all the required information (or some other error occurs) you ll get something like: 2

3 Searching Page XXX: some information about how searching works Under the covers Index views may be modified by the following arguments: Argument Description :sort sort by prop name, optionally preceeded with - to give descending or nothing for ascending sorting. :group group by prop name, optionally preceeded with - or to sort in descending or nothing for ascending order. :filter selects which props should be displayed in the filter section. Default is all. :columns selects the columns that should be displayed. Default is all. propname selects the values the item properties given by propname must have (very basic search/filter). Access Controls XXX Gateway sent to Roundup is examined for several pieces of information: 1. subject-line information identifying the purpose of the 2. message content which is to be extracted 3. 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. Note that 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. 3

4 Setting Properties The 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: Subject: Re: [issue2] we re out of widgets [nosy=richard] removing yourself from a nosy list: Subject: Re: [issue2] we re out of widgets [nosy=-richard] In all cases, the message relates to issue 2. The Re: prefix is stripped off. 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 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: 4

5 ADD AUTHOR TO NOSY 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. ADD RECIPIENTS TO 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. Command Line Tool The basic usage is: Help: roundup-admin -h roundup-admin help -- this help roundup-admin help <command> -- command-specific help roundup-admin help all -- all available help Options: -i instance home -- specify the issue tracker "home directory" to administer -u -- the user[:password] to use for commands -c -- when outputting lists of data, just comma-separate them Commands: commit create classname property=value... display 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] 5

6 pack period date reindex retire designator[,designator]* rollback security [Role name] set designator[,designator]* propname=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: Strings are, well, strings. Password values will display as their encoded value. Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained below.: Input of... Means... " :45" :45:00 " " :00:00 "01-25" yyyy :00:00 " :13" yyyy :13:00 " :32:43" yyyy :32:43 "14:25" yyyy-mm-dd.19:25:00 "8:47:11" yyyy-mm-dd.13:47:11 "." "right now" Link values are printed as item designators. When given as an argument, item designators and key strings are both accepted. Multilink values are printed as lists of item designators joined by commas. When given as an argument, item designators and key strings are both accepted; an empty string, a single item, or a list of items joined by commas is accepted. 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. ROUNDUP LOGIN environment variable the -u command-line option If either the name or password is not supplied, they are obtained from the command-line. Back to Table of Contents 6