This document describes additional functionality to be added to the Bugzilla bug tracking system. Definition ========== Currently, Bugzilla offers a fixed number of named fields to describe bugs. These fields are shared by every project in the system. The proposed additional functionalty is the ability to define additional fields on a per-project basis. These additional fields are called "custom fields". Custom fields will be available in four major varieties: integer, string, date, and selection. The first three of these types are collectively referred to as "scalar" types. All scalar fields can be set to a special "undefined" value in additional to the valid values described below. Integer ------- An integer custom field contains values which are integers. Such fields must be able to store at least the range of integers which are typically represented as a signed four-byte quantity. Bugzilla should signal an error condition if a user attempts to store an integer outside of the allowed range into an integer field. String ------ This type of field contains text which is intended to be readable by humans. However, for internationalization reasons, any binary data may be stored in a string field. Each string field is flagged as belonging to one of two varieties: short and long. A short string field can hold a maximum of 255 characters, and may contain no vertical whitespace characters (carriage return, newline, or vertical tab). It is represented on Bugzilla's Web interface using a single-line text form element. A long string field can hold up to 65535 characters, possibly containing vertical whitespace. It is represented on Bugzilla's Web interface as a multiline textarea form element. Date ---- A date field contains a date, and optionally a time of day. Bugzilla should signal an error condition if a user attempts to store an illegal date value in a date field. Examples: * An invalid day of the month: March 50, February 30 * An invalid date: February 29, 2001 * An invalid time: 12:66:00 Date fields are represented on Bugzilla's web interface as a single-line text form element. Dates are displayed in the form 'YYYY-MM-DD', and times are displayed in the form 'HH24:MM:SS'. When a user enters a date, it must conform to the these formats. Bugzilla should signal an error condition if a user supplies a date that is not in the proper format. Selection --------- A selection field takes its value from a set of distinct string values. No string value in any selection field's set of valid values may contain vertical whitespace, contain leading or trailing whitespace, or exceed 255 characters in length. Each selection field comes in one of two varieties: "single-selection" and "multiselection". A single-selection field's value is a subset of the field's possible values of size either zero or one. It is represented on Bugzilla's web interface as a drop-down listbox form element. A field whose value is the empty set is represented on the Web interface by a special "unset" string which is defined when the field is created. A multiselection field's value is an arbitrary subset of the field's possible values. It is represented on Bugzilla's web interface as a multiline listbox in which multiple simultaneous selections are allowed. The listbox's vertical size is equal to the number of possible selections or five, whichever is smaller. It must be possible to share a selection field's definition among multiple Bugzilla components, such that a change to the field's definition is reflected in all fields which share that definition. Logging ======= Whenever a user edits a bug and changes one or more custom fields, the changes must be logged. All changes to a bug made at the same time must be tagged with a unique transaction ID, so that it is possible to later determine which changes were made at the same time. Information logged with each transaction must include the identity of the user who made the changes and the date and time when the changes were made. The old and new values of each field modified during a transaction must be logged. Presentation ============ Custom fields are to be presented on each Bugzilla page that presents the standard Bugzilla fields. These pages include at least the following: On "show_bug.cgi" and "post_bug.cgi", the custom fields should be shown just prior to the list of attachments. On "enter_bug.cgi" and "long_list.cgi", the custom fields should be shown just after the "Description" text box. The Bugzilla administrator may edit Bugzilla's templates to display the custom fields in some other location on the page, or to display individual custom fields at chosen locations. The default template for each page must be intelligent enough to display at the "standard" location only those fields which have not been set to be shown elsewhere on the page. When a bug is being created or edited, custom fields are represented as per the field type descriptions above. When a bug is being displayed but not edited, scalar fields and single-selection fields are represented as simple text; multiselection fields are represented using disabled multiline listboxes. The query.cgi page requires more extensive modifications. Currently query.cgi knows only about Bugzilla's standard fields. Since all components share the same set of standard fields, these fields can be displayed before the user has chosen a Product at the top of the page. To add the capability to search on custom fields, a straightforward approach would be to require the user to first specify the projects within which to search, then display the usual query page augmented with the custom fields which exist in those projects. However, this is too invasive for projects which don't use custom fields, and also for queries which don't care about custom fields. Here is an alternate approach. A button is to be added to the query page, to the right of the "Product", "Component", and "Version" listboxes, labelled "Show custom fields for these projects". If the user clicks it, the query form is redisplayed, augmented with all custom fields in all of the selected projects. If no projects were selected, or if no selected project has any custom fields, the page is simply redisplayed as it was before. The user may freely change the target projects and press the "Show custom fields" button again. The query page will be redisplayed with new form elements for the most recently chosen projects. When custom fields are being shown, a second button is to be added below the "Show custom fields" button, labelled "Hide custom fields". When it is clicked, the query page is redisplayed as it was originally, without any custom field elements. It is an error for the user to select one or more target projects, show the custom fields for those components, change the target projects, and begin a search. In this case Bugzilla should redisplay the query page with an appropriate error message at the top. Different projects may define different custom fields with the same name. Therefore, custom field form elements for custom fields belonging to the same project will need to be grouped together, clearly labelled as belonging to that project. Custom string fields may be queried in the same manner as the stock fields "Comment" and "URL". That is, they may be matched against a user-supplied string using any of the following predicates: * contains all of the words/strings * contains any of the words/strings * contains the string * contains the string (exact case) * contains all of the words * contains any of the words * matches the regexp * doesn't match the regexp Custom integer fields may be queried against a user-supplied string (which must look like an integer) using the following predicates: * is equal to * is less than * is greater than * is less than or equal to * is greater than or equal to Custom date fields may be queried against a user-supplied string which must match a date or date/time pattern (YYYY-MM-DD, followed by whitespace and HH24:MM:SS for date/time fields). The available predicates are: * is exactly * is at or earlier than * is at or later than (The open versions of the latter two inequalities--ie, strictly earlier than or strictly later than--are probably not worth including.) Custom single-selection selection fields may be queried against a multiline listbox containing all valid values for the field. Multiple selections within this listbox are allowed. A bug matches this query term if this field's value is equal to ANY of the user-selected values. Custom multiselection selection fields may be queried against a multiline listbox containing all valid values for the fields. Multiple selections within this listbox are allowed. A pair of radiobuttons is placed next to the listbox which present two choices: "Any" and "All". Initially, "Any" is selected. If the "Any" button is selected at the time the query is initiated, then a bug matches this query term if any of the selected values are set in this field. If the "All" button is selected instead, then a bug matches this query term if all of the selected values are set in this field.