Perforce 2007.3 P4 User's Guide
<< Previous Chapter
Codelines and Branching
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Scripting and Reporting

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.

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:

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.

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.

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.

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:

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.

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.

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.


Perforce 2007.3 P4 User's Guide
<< Previous Chapter
Codelines and Branching
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Scripting and Reporting
Please send comments and questions about this manual to [email protected].
Copyright 2005-2007 Perforce Software. All rights reserved.
Last updated: 11/29/07