Chapter 7
Defect Tracking
A job is a numbered (or named) work request managed by the Perforce server. Perforce jobs enable you to track the status of bugs and enhancement requests and associate them with changelists that implement fixes and enhancements. You can search for jobs based on the contents of fields, the date the job was entered or last modified, and many other criteria.
Your Perforce administrator can customize the job specification for your site's requirements. For details on modifying the job specification, see the Perforce System Administrator's Guide.
If you want to integrate Perforce with your in-house defect tracking system, or develop an integration with a third-party defect tracking system, see the P4DTI product information page on the Perforce web site.
Managing jobs
To create a job using Perforce's default job-naming scheme, issue the p4 job command. To assign a name to a new job (or edit an existing job), issue the p4 job jobname command.
Gale discovers about a problem with Jam, so she creates a job by issuing the p4 job command
and describes it as follows:
Job: job000006
Status: open
User: gale
Date: 2005/11/14 17:12:21
Description:
MAXLINE on NT can't account for NT 4.0 expanded cmd buffer size.
|
The following table describes the fields in the default job specification.
Field Name
|
Description
|
Default
|
|---|
|
Job
|
The name of the job (white space is not allowed). By default, Perforce assigns job names using a numbering scheme (jobnnnnnn).
|
Last job number + 1
|
|
Status
|
- open: job has not yet been fixed.
- closed: job has been completed.
- suspended: job is not currently being worked on.
|
open
|
|
User
|
The user to whom the job is assigned, usually the person assigned to fix this particular problem.
|
Perforce user name of the job creator.
|
|
Date
|
The date the job was last modified.
|
Updated by the Perforce server when you save the job.
|
|
Description
|
Describes the work being requested, for example a bug description or request for enhancement.
|
None. You must enter a description.
|
To edit existing jobs, specify the job name when you issue the p4 job command:
p4 job jobname. Enter your changes in the job form, save the form and exit.
To delete a job, issue the p4 job -d jobname command.
Searching jobs
To search Perforce jobs, issue the p4 jobs -e jobview command, where jobview specifies search expressions described in the following sections. For more details, issue the p4 help jobview command.
Searching job text
You can use the expression 'word1 word2 ... wordN' to find jobs that contain all of word1 through wordN in any field (excluding date fields). Use single quotes on UNIX and double quotes on Windows.
When searching jobs, note the following restrictions:
- When you specify multiple words separated by whitespace, Perforce searches for jobs that contain all the words specified. To find jobs that contain any of the terms, separate the terms with the pipe ( |) character.
- Field names and text comparisons in expressions are not case-sensitive.
- Only alphanumeric text and punctuation can appear in an expression. To match the following characters, which are used by Perforce as logical operators, precede them with a backslash: =^&|()<>.
- You cannot search for phrases, only individual words.
Example:
Searching jobs for specific words
Bruno wants to find all jobs that contain the words filter, file, and mailbox. He types:
p4 jobs -e 'filter file mailbox'
Example:
Finding jobs that contain any of a set of words in any field
Bruno wants to find jobs that contain any of the words filter, file or mailbox. He types:
p4 jobs -e 'filter|file|mailbox'
You can use the * wildcard to match one or more characters. For example, the expression fieldname=string* matches string, strings, stringbuffer, and so on.
To search for words that contain wildcards, precede the wildcard with a backslash in the command. For instance, to search for *string (perhaps in reference to char *string), issue the following command:
Searching specific fields
To search based on the values in a specific field, specify field=value.
Example:
Finding jobs that contain words in specific fields
Bruno wants to find all open jobs related to filtering. He types:
p4 jobs -e 'Status=open User=bruno filter.c'
This command finds all jobs with a Status: of open, a User: of bruno, and the word
filter.c in any nondate field.
To find fields that do not contain a specified expression, precede it with ^, which is the NOT operator. The NOT operator ^ can be used only directly after an AND expression (space or &). For example, p4 jobs -e '^user=bruno' is not valid. To get around this restriction, use the * wildcard to add a search term before the ^ term; for example:
p4 jobs -e 'job=* ^user=bruno' returns all jobs not owned by Bruno.
Example:
Excluding jobs that contain specified values in a field
Bruno wants to find all open jobs he does not own that involve filtering. He types:
p4 jobs -e 'status=open ^user=bruno filter'
This command displays all open jobs that Bruno does not own that contain the word filter.
Using comparison operators
The following comparison operators are available.
|
=
|
Equal
|
|
>
|
Greater than
|
|
<
|
Less than
|
|
>=
|
Greater than or equal to
|
|
<=
|
Less than or equal to
|
The behavior of these operators depends upon the type of the field in the expression. The following table describes the field types and how they can be searched.
Field Type
|
Description
|
Notes
|
|---|
|
word
|
A single word
|
The equality operator (=) matches the value in the word field exactly.
The relational operators perform comparisons in ASCII order.
|
|
text
|
A block of text entered on the lines beneath the field name
|
The equality operator (=) matches the job if the value is found anywhere in the specified field.
The relational operators are of limited use here, because they'll match the job if any word in the specified field matches the provided value. For example, if a job has a text field ShortDescription: that contains only the phrase gui bug, and the expression is 'ShortDesc<filter', the job will match the expression, because bug<filter.
|
|
line
|
A single line of text entered on the same line as the field name
|
Same as text
|
|
select
|
One of a set of values. For example, job status can be open/suspended/closed
|
The equality operator (=) matches a job if the value in the field is the specified word. Relational operators perform comparisons in ASCII order.
|
|
date
| A date and optionally a time. For example, 2005/07/15:13:21:40
|
Dates are matched chronologically. If a time is not specified, the operators =, <=, and >= match the whole day.
|
If you're not sure of a field's type, issue the p4 jobspec -o command, which displays your job specification. The field called Fields: lists the job fields' names and data types.
Searching date fields
To search date fields, specify the date using the format yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss. If you omit time, the equality operator (=) matches the entire day.
Example:
Using dates within expressions
Bruno wants to view all jobs modified on July 13, 2005. He enters
p4 jobs -e 'ModifiedDate=2005/07/13'
Fixing jobs
To fix a job, you link it to a changelist and submit the changelist. Perforce automatically changes the value of a job's status field to closed when the changelist is submitted.
Jobs can be linked to changelists in one of three ways:
- By setting the JobView: field in the p4 user form to an expression that matches the job.
- With the p4 fix command.
- By editing the p4 submit form.
You can modify job status directly by editing the job, but if you close a job manually, there's no association with the changelist that fixed the job. If you have altered your site's job specification by deleting the Status: field, jobs can still be linked to changelists, but status cannot be changed when the changelist is submitted. (In most cases, this is not a desired form of operation.) See the chapter on editing job specifications in the Perforce System Administrator's Guide for more details.
To remove jobs from a changelist, issue the p4 fix -d command.
Linking automatically
You can modify your Perforce user specification to automatically attach open jobs to any changelists you create. To set up automatic inclusion, issue the p4 user command and set the JobView: field value to a valid expression that locates the jobs you want attached.
Example:
Automatically linking jobs to changelists
Bruno wants to see all open jobs that he owns in all changelists he creates. He types p4 user
and adds the JobView: field:
User: bruno
Update: 2005/06/02 13:11:57
Access: 2005/06/03 20:11:07
JobView: user=bruno&status=open
|
All of Bruno's open jobs now are automatically attached to his default changelist. When he
submits changelists, he must be sure to delete jobs that aren't fixed by the changelist he is
submitting.
Linking manually
To link a job to a changelist manually, issue the p4 fix -c changenum jobname command. If the changelist has already been submitted, the value of the job's Status: field is changed to closed. Otherwise, the status is not changed.
Example:
Manually linking jobs to changelists
You can use p4 fix to link a changelist to a job owned by another user.
Sarah has just submitted a job called options-bug to Bruno, but the bug has already been
fixed in Bruno's previously submitted changelist 18. Bruno links the job to the changelist by
typing:
Because changelist 18 has already been submitted, the job's status is changed to closed.
Linking jobs to changelists
To link jobs to changelists when submitting or editing the changelist, enter the job names in the Jobs: field of the changelist specification. When you submit the changelist, the job is (by default) closed.
To unlink a job from a pending changelist, edit the changelist and delete its name from the Jobs: field. To unlink a job from a submitted changelist, issue the p4 fix -d -c changenum jobname command.
Please send comments and questions about this manual to
[email protected].
Copyright 2005-2007 Perforce Software. All rights reserved.
Last updated: 11/29/07