gnatsweb/715: Sequence of Fields Among Create, Edit, and Query Results

[bug-gnats]

>Number:         715
>Category:       gnatsweb
>Synopsis:       Sequence of Fields Among Create, Edit, and Query Results
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    unassigned
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Wed Dec 20 10:06:09 -0600 2006
>Originator:     Craig Senior
>Release:        Gnatsweb v4.0.0
>Organization:
Public Works and Government Services Canada
>Environment:
>Description:
The sequence of fields in the Create, Edit, View Results, and Query Results 
screens are controlled by the sequence of fields in dbconfig. The problem with 
this is it might be desireable to have different sequences. Specifically, we 
wanted to have "Notify-List" in what we call the PR Identification section of 
Create Problem Report, higher up on the screen. When we run a query, however, 
Notify-List appears to the left of important fields like Synopsis if the user 
chooses the query default.

It would be very helpful if we could specify a left-to-right sequence of fields 
for Query results that was different from the sequence for Create, Edit, and 
View Results.
>How-To-Repeat:
N/A
>Fix:
Workarounds:
Resequence fields in a less desireable order that balances the needs of both 
data entry screens and query results.

Teach users to specify non-default queries and save those queries for reuse.
>Notify-List:    
>Unformatted:
 ----gnatsweb-attachment----
 Content-Type: text/plain; name="dbconfig 2006-12-18 Resequence.txt"
 Content-Disposition: inline; filename="dbconfig 2006-12-18 Resequence.txt"
 
 # Filename: dbconfig
 
 # This configuration file describes the configuration for GNATS.
 # It describes the types of data stored in fields,
 # the order of fields in the index file,
 # and the format of results returned from query-pr.
 
 # Text after a # is considered a comment, and is ignored.
 
 # DATABASE GENERAL
 # 
--------------------------------------------------------------------------------------------------------
 # The first section describes various aspects of the database.
 
 database-info {
    # If true, mail is sent to the gnats-admin instead of the submitter
    # If false, mail is sent to the submitter
    debug-mode false
 
    # If true, all Received: headers are kept in the PR
    # If false, only the first one is kept
    keep-all-received-headers false
 
    # If true, we track required PR times and notify the responsible
    # people when the times expire.
    notify-about-expired-prs true
 
    # Send PR submitter an acknowledgement for a newly-submitted PR;
    # the format of the message is the "mail-format" query format.
    send-submitter-ack true
 
    # The directory where at-pr and mail-pr can be found.
    libexecdir "/usr/local/libexec/gnats"
 
    # The hours of a business day, in 24-hour format
    business-day-hours 8-17
 
    # The starting and ending days of the week that define the business day
    business-week-days 1-5
 
    # If true, automatically create directories for categories if they don't 
exist
    create-category-dirs true
 
    # The default permission mask for new category directories.
    # NOTE: If local users on the GNATS server will run
    # tools such as query-pr, you might need to set permissions to 0755.
    category-dir-perms "0750"
 }
 
 # 
--------------------------------------------------------------------------------------------------------
 # FIELD DESCRIPTIONS
 # 
--------------------------------------------------------------------------------------------------------
 # The second section describes each field in the PR.
 
 # The name specified is also used as the field header in the PR, with
 # a `>' prepended and a `:' appended.
 
 
 # Identification
 # --------------------------------------------------------
 
 field "Number" {
    # This entry describes a builtin field; "number" is the internal name of 
the field.
    #  (The builtin names correspond to the old gnats field names, and are
    # case-insensitive as are field names.)
    builtin-name "number"
 
    # One-line description of the field, in human-readable form.
    description "PR Number"
 
    # Integer values are stored in this field.
    integer {
        # This must be -1 -- code in various programs relies on the first
        # character of the field being a '-' if the value wasn't specified.
        # Really, it shouldn't have a default.
        default "-1"
    }
    # The field value may not be edited.
    read-only
 }
 
 
 field "Submitter-ID" {
    builtin-name "submitter-id"
    description "The person who typed in the PR"
    enumerated-in-file {
        path "submitters"
        fields {
            "submitter" "fullname" "type" "rtime" "contact" "notify"
        }
        key "submitter"
    }
    textsearch
 }
 
 
 field "Submitter-Name" {
    builtin-name "originator"
    description "Person who typed in the PR"
    text
    query-default inexact-regexp
    textsearch
 }
 
 
 field "Organization" {
    description "Organization of Submitter"
    # The field may contain multiple lines of text.
    multitext
 }
 
 
 field "Notify-List" {
    description "Addresses to notify of significant PR changes"
    text
    query-default inexact-regexp
    textsearch
 }
 
 
 # Problem Description
 # --------------------------------------------------------
 
 field "Synopsis" {
    builtin-name "synopsis"
    description "One-line summary of the PR"
    text
    # When doing queries on this field, by default regexps do not need to
    # match the contents of the field exactly - other possible value is 
"exact-regexp"
    query-default inexact-regexp
    textsearch
 }
 
 
 field "Description" {
    builtin-name "description"
    description "Detailed symptoms and circumstances of problem"
    multitext
 }
 
 
 field "Environment" {
    description "Machine, OS, libraries"
    multitext
 }
 
 
 field "Release-Found-In" {
    description "Release number or tag"
    text
    query-default inexact-regexp
    textsearch
 }
 
 
 field "Category" {
    builtin-name "category"
    description "To what component does the PR apply?"
 
    # Values for this field are enumerated in a separate file.
 
    enumerated-in-file {
        # The "categories" file is located in the
        # gnats-adm subdirectory of the database.
        path "categories"
 
        # The file has 4 fields separated by colons (:).
        fields {
            "category" "fullname" "person" "notify"
        }
        # The file is keyed on this field. It must be the first field listed 
above.
        key "category"
    }
    # Search this field when doing a --text search in query-pr
    textsearch
 }
 
 
 field "Class" {
    description "Type of request"
    enumerated-in-file {
        path "classes"
        fields { "class" "type" "description" }
        key "class"
    }
    textsearch
 }
 
 
 field "Confidential" {
    builtin-name "confidential"
    description "Yes/no flag indicating if the PR contents are confidential"
    # Enumerated field with two possible values: yes (default) and no
    enum {
        values { "yes" "no" }
        default "no"
    }
    textsearch
    # This field may not be queried unless the user has full permissions to 
search it
    restricted
 }
 
 
 field "Severity" {
    builtin-name "severity"
    description "Impact of the problem?"
    enum {
        values { "very high" "high" "medium" "low" "enhancement"}
        default "low"
        # Suggest a default when a PR is being input. To leave blank use ""
        input-default "low"
    }
    textsearch
 }
 
 
 field "Priority" {
    builtin-name "priority"
    description "How soon is the fix required?"
    enum {
        values { "very high" "high" "medium" "low" "enhancement"}
        default "low"
        # Suggest a default when a PR is being input. To leave blank use ""
        input-default "low"
    }
    query-default exact-regexp
    textsearch
 }
 
 
 field "How-To-Repeat" {
    description "Code/input/steps to reproduce problem"
    multitext
 }
 
 
 # Assignment and State
 # --------------------------------------------------------
 
 field "Responsible" {
    builtin-name "responsible"
    description "The user responsible for the PR"
    enumerated-in-file {
        path "responsible"
        fields {
            "responsible" "fullname" "alias"
        }
        key "responsible"
        # Allow any value, because old GNATS didn't require
        # all possible responsible users in the responsible file -- 
        # it also looks in the password database.
        
        # The flag indicates that the value in the field doesn't have to
        # match one of the entries in the administrative file.
        allow-any-value
    }
    textsearch
    # When the field is edited, add an audit-trail entry and a reason for the 
change
    on-change {
        add-audit-trail
        require-change-reason
    }
 
 # Terminate the entry in the index after the first space.  (We might be able 
to handle
 # this by allowing a format character in the index spec.)
    nospaces-in-index
 }
 
 
 field "State" {
    builtin-name "state"
    description "The state of the PR"
    enumerated-in-file {
        path "states"
        fields { "state" "type" "description" }
        key "state"
    }
    textsearch
 
    # When the field is edited, add an audit-trail entry and a reason for the 
change
    on-change {
        add-audit-trail
        require-change-reason
    }
 
 # An example of how to set the Closed-Date: field when the State: field is 
changed to "closed"
 # A \ followed by a newline is ignored, and \n in strings is translated to the 
EOL character.
 
 # Only do the edit if the new State type is "closed" and if
 #    a) the previous State wasn't of type closed, or
 #    b) the Closed-Date is not yet defined
 # With this rule, we keep the Closed-Date if we change from a "closed" state
 # to another "closed" state.
    on-change "State[type]==\"closed\" \
              & (oldpr:State[Type]!=\"closed\" | Closed-Date==\"\")" {
 
 # Set the Closed-Date field to the current date.  (We can also
 # use $OldValue and $NewValue here and any of the PR field values.)
 
        set-field "Closed-Date" {
            "%s"
            "$CurrentDate"
        }
    }
 
 
 # If the new PR State: field type is not closed...then clear the Closed-Date 
field
 
    on-change "State[type]!=\"closed\"" {
        # Null it out.
        set-field "Closed-Date" {
            ""
        }
    }
 }
 
 
 # Problem Solution
 # --------------------------------------------------------
 
 field "Fix" {
    description "How to workaround or fix problem, if known"
    multitext {
        default "Workaround: \n\n Fix: \n"
    }
 }
 
 
 field "Release-To-Fix-In" {
    #Added this field as free text to identify the Release that will fix the 
problem
    description "Release that will fix the problem"
    enum {
    values { "UnKnown" "Rel20_PKG4" "Rel20_PKG5" "Rel20_PKG6" "Rel20_PKG7" 
"Future" "Maintenance Rel" "Never" }
   default "UnKnown"
    }
    textsearch  
 }
 
 
 field "Release-Note" {
    multitext
 }
 
 
 # Unparsed text ends up in this field
 field "Misc-Text-and-Activity-Log" {
    builtin-name "unformatted"
    description "Miscellaneous Text and Activity Log"
    multitext
 }
 
 
 field "Audit-Trail" {
    builtin-name "audit-trail"
    description "GNATS-generated log of changes to the PR"
    multitext
 }
 
 
 # Dates
 # --------------------------------------------------------
 
 field "Arrival-Date" {
    builtin-name "arrival-date"
    description "Arrival date of the PR"
    # A date field.  Dates formats are validated before they are stored
    # Date fields may also be empty
    date
    # The field value may not be edited
    read-only
 }
 
 
 field "Closed-Date" {
    builtin-name "closed-date"
    description "Date the PR was closed"
    date
    # The field value may not be edited
    read-only
 }
 
 
 field "Last-Modified" {
    builtin-name "last-modified"
    description "Last modification date of the PR"
    date
    # The field may not be edited
    read-only
 }
 
 
 # QUERIES
 # 
--------------------------------------------------------------------------------------------------------
 # This section describes the output of various queries
 
 # For a full query, print all fields in the format of a normal PR.
 
 query "full" {
    fields all
 }
 
 
 # Used for edits.  The field contents are displayed "raw".
 query "edit" {
    fields all
    raw
 }
 
 # If a list of fields is given without any format specifier, the fields are 
printed
 # in the same format as they appear in a PR, with headers.
 
 # The standard query type is performed by default if no format is specified to 
query-pr.
 
 query "standard" {
    fields {
        "Number" "Category" "Synopsis" "Confidential" "Severity"
        "Priority" "Responsible" "State" "Class" "Submitter-ID"
        "Arrival-Date" "Closed-Date" "Last-Modified" "Submitter-Name"
        "Release-Found-In"
    }
 }
 
 
 # The format string uses printf-style formatting to format its output.
 # No headers are printed, and a trailing EOL character is always
 # output. \n in the string is replaced with the proper EOL character.
 
 # The format characters are:
 #    %s - plain string.
 #    %S - similar to %s, but the string is terminated at the first space
 #      that occurs in the field contents.  Used for the Responsible: field.
 #    %d - integer value.  This is normally used to print out enumerated
 #      fields with their integer equivalent, or to print out dates
 #      as "seconds since Jan 1, 1970".
 #    %D - formatted date field.
 #    %Q - SQL-formatted date field.
 #    %F - write the entire field with the header and a newline, as if
 #      it were being written to a PR.  Any positional indicators and
 #      such are ignored.
 #
 # For most %-formats the usual `-' and `+' positional specifiers may be given.
 #
 # This is the --summary format in query-pr.
 #
 query "summary" {
    format "%8s %-8.8S %-8.8s %-9.9s %-9.9s %-8.8s %-10.10s %s"
    fields {
        "Number" "Responsible" "Category" "State" "Severity" "Priority"
        "Submitter-ID" "Synopsis"
    }
 }
 
 
 # The next two are historical silliness.
 #
 query "sql" {
    format 
"%-8.8s|%-16.16s|%-128.128s|%-3.3s|%1.1d|%1.1d|%-16.16S|%1.1d|%1.1d|%-16.16s|%-21.21Q|%-64.64s|%-64.64s|%-21.21Q|%-21.21Q|"
    fields {
        "Number" "Category" "Synopsis" "Confidential" "Severity" "Priority"
        "Responsible" "State" "Class" "Submitter-ID" "Arrival-Date"
        "Submitter-Name" "Release-Found-In" "Last-Modified" "Closed-Date"
    }
 }
 
 query "sql2" {
    format "%s|%s|%s|%s|%d|%d|%S|%d|%d|%s|%Q|%s|%s|%Q|%Q|"
    fields {
        "Number" "Category" "Synopsis" "Confidential" "Severity" "Priority"
        "Responsible" "State" "Class" "Submitter-ID" "Arrival-Date"
        "Submitter-Name" "Release-Found-In" "Last-Modified" "Closed-Date"
    }
 }
 
 
 #
 # The format used for Audit-Trail entries.  The following parameters
 # are passed in, and can be used in addition to any of the PR fields:
 # $FieldName -- the name of the field that changed
 # $OldValue -- the old value of the field
 # $NewValue -- the new field value
 # $EditUserEmailAddr -- the email address of the user editing the field
 # $CurrentDate -- the current date
 # $ChangeReason -- the reason for the change (blank if no reason was supplied)
 #
 audit-trail-format {
    format "\
 %s-Changed-From-To: %s->%s\n\
 %s-Changed-By: %s\n\
 %s-Changed-When: %s\n\
 %s-Changed-Why:\n\
 %s\n\n"
 
    fields {
        "$FieldName" "$OldValue" "$NewValue"
        "$FieldName" "$EditUserEmailAddr"
        "$FieldName" "$CurrentDate"
        "$FieldName" "$ChangeReason"
    }
 }
 
 # This message is used for an initial response back to the PR submitter.
 
 mail-format "initial-response-to-submitter" {
    from-address {
        fixed-address "gnats-admin"
    }
 
    # For addresses that are joined with |, we try each one from left to right,
    #  until we find one that's non-empty. Multiple addresses may be listed
    to-addresses {
        "Reply-To:" | "From:" | "From" | "Submitter-ID"
    }
 
    header {
        format "Subject: Re: %s/%s: %s\n"
 
        fields { "Category" "Number" "Subject:" }
    }
 
    body {
 format "Thank you for your problem report.\n\
 It has the internal identification `%s/%s'.\n\
 The individual assigned to look at your PR is:\n\
 %s. \n\
 \n\
 %F%F%F%F\n\
 "
        fields { "Category" "Number" "Responsible"
                 "Category" "Responsible" "Synopsis" "Arrival-Date" }
    }
 }
 
 # The message sent to the responsible parties when a new non-pending PR 
arrives.
 
 mail-format "initial-pr-notification" {
    # Who the mail is from.
    from-address {
        "From:" | "From"
    }
 
    # Send mail to the responsible person, the addresses listed in
    # the contact and notify fields of the submitter adm file entry for
    # the Submitter-ID, and the notify person listed in the category adm file.
    to-addresses {
        "Responsible"
        "Submitter-ID[contact]"
        "Submitter-ID[notify]"
        "Category[notify]"
    }
 
    # The reply-to address; either use the Reply-To: or From: header values 
    # from the PR or from the Submitter-ID's mail address.
    reply-to {
        "Reply-To:" | "From:" | "Submitter-ID"
    }
 
    # Any additional header text we want to add.  Must have a newline at the 
end of each line.
    header {
        format "Subject: %s/%s: %s\nCc: %s\n"
        fields { "Category" "Number" "Subject:" "Notify-List" }
    }
 
    body {
 # Need to add this feature, or something like it.
 #      ($ExpireTime != "") {
 #              format "\tThe contract type is `%s' with a response time of %d 
business hours.\n"
 #              fields { "Submitter-ID[type]" "$ExpireTime" }
 #      }
 #       %P is "write the entire PR".
        format "%P"
        # And if there's a %-format...there has to be an associated field.  
        fields { "$" }
    }
 }
 
 
 # Format used for initial PRs that end up as pending PRs.
 mail-format "initial-pr-notification-pending" {
    from-address {
        "From:" | "From"
    }
 
    # Tell only gnats-admin about it.
    to-addresses {
        fixed-address "gnats-admin"
    }
 
    reply-to {
        "Reply-To:" | "From:" | "Submitter-ID"
    }
 
    header {
        format "Subject: %s/%s: %s (pending)\nCc: %s\n"
        fields { "Category" "Number" "Subject:" "Notify-List" }
    }
 
    body {
 
 #      ($ExpireTime != "") {
 #              format "\tThe contract type is `%s' with a response time of %d 
business hours.\n"
 #              fields { "Submitter-ID[type]" "$ExpireTime" }
 #      }
        format "%P"
        fields { "$" }
    }
 }
 
 
 # Used when a response to a PR is received via email.
 
 # The following parameters are passed in:
 # $MailFrom -- the From: line of the original message
 # $MailTo -- the To: line of the original message
 # $MailSubject: The Subject: line of the original message
 # $MailCC: The CC: line of the original message
 # $NewAuditTrail -- the text of the new audit trail entry (the body of the 
message)
 #
 mail-format "appended-email-response" {
    from-address {
        "$MailFrom"
    }
 
    # Send a copy to the user that sent in the message
    to-addresses {
        "Responsible"
        "Submitter-ID[contact]"
    }
 
    reply-to {
        "$MailFrom"
    }
 
    header {
        format "Subject: %s/%s: %s\n"
        fields { "Category" "Number" "$MailSubject" }
    }
 
    body {
        format "The following reply was made to PR %s/%s; it has been noted by 
GNATS.\n\n%s"
        fields { "Category" "Number" "$NewAuditTrail" }
    }
 }
 
 
 # Used to send mail for a change that generates an Audit-Trail entry.
 # The following parameters are available:
 # $EditUserEmailAddr -- the email address of the user editing the PR
 # $OldResponsible -- the previous Responsible field entry, if it was changed
 # $NewAuditTrail -- the Audit-Trail: entries that have been appended by the 
edits
 
 mail-format "audit-mail" {
    from-address {
        "$EditUserEmailAddr"
    }
 
    
    to-addresses {
        "Responsible"
        "$OldResponsible"
        "Category[notify]"
        "Submitter-ID[contact]"
        "$EditUserEmailAddr"
        "Reply-To:" | "From:" | "From"
    }
 
    reply-to {
        fixed-address "bugs"
    }
 
    header {
        format "Subject: Re: %s/%s\nCc: %s\n"
        fields { "Category" "Number" "Notify-List" }
    }
 
    body {
        format "Synopsis: %s\n\n%s\n"
        fields { "Synopsis" "$NewAuditTrail" }
    }
 }
 
 
 # Used to send mail when a PR is deleted.
 # The following parameters are available:
 # $EditUserEmailAddr -- the email address of the user deleting the PR
 # $PRNum -- the number of the PR that was deleted
 # Can't refer to the deleted PR at this point--it's been deleted.
 
 mail-format "deleted-pr-mail" {
    from-address {
        "$EditUserEmailAddr"
    }
 
    to-addresses {
        fixed-address "gnats-admin"
    }
 
    header {
        format "Subject: Deleted PR %s\n"
        fields { "$PRNum" }
    }
 
    body {
        format "PR %s was deleted by user %s.\n"
        fields { "$PRNum" "$EditUserEmailAddr" }
    }
 }
 
 # Global on-change sections are executed once for each PR edit.
 
 # This one takes care of setting the Last-Modified field.  The following
 # format parameters are available:
 
 # $CurrentDate -- the current date
 # $EditUserEmailAddr -- the email address of the user making the change(s)
 
 on-change {
    set-field "Last-Modified" { "%s" "$CurrentDate" }
 }
 
 # The index entry lists the fields that appear in the index.  For now, the PR
 # ID (consisting of "category/number") is always first in the index records,
 # and is not explicitly given here.
 
 # The binary-index keyword indicates that a binary file format will be used
 # to store the index.  This has several advantages over ASCII format,
 # such as avoiding problems with quoting field separators (didn't work 
properly in GNATS v3).
 
 # If ASCII format is used (by setting binary-index to false) a '|' is used by 
default
 # as the separator between fields.  An alternate field separator may be given 
with the "separator" keyword.
 
 index {
    # Name of the index file in the gnats-adm directory.  The name is 
respected, but you can
    # have only one index entry per database. The index is keyed by PR number.
    path "index"
 
    # The fields in the index, in the order they will appear
    fields {
        "Submitter-ID" "Responsible" "State" "Confidential" "Severity"
        "Priority" "Arrival-Date" "Last-Modified" "Closed-Date" "Class"
        "Submitter-Name" "Release-Found-In" "Synopsis"
    }
    # Use a binary format when binary-index is set to true.
    binary-index true
 }
 
 # initial-entry describes which fields should be present on initial entry;
 # used by send-pr (for example) to decide the fields to include in the template
 
 # Listed in the order in which they should appear in the template
 initial-entry {
    fields {
        "Submitter-ID" "Notify-List" "Submitter-Name" "Organization"
        "Synopsis" "Confidential" "Severity" "Priority" "Category"
        "Class" "Release-Found-In" "Environment" "Description" "How-To-Repeat"
        "Fix"
    }
 }