Defect Tracking
A job is a numbered (or named) work request managed by Perforce. 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 Server Administrator's Guide: Fundamentals.
To integrate Perforce with your in-house defect tracking system, or to develop an integration with a third-party defect tracking system, use P4DTG, the Perforce Defect Tracking Gateway. P4DTG is an integrated platform that includes both a graphical configuration editor and a replication engine. For more information, see:
http://www.perforce.com/product/components/defect_tracking_gateway
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.
Example 39. Creating a job
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: 2011/11/14 17:12:21
Description:
MAXLINE can't account for expanded cmd buffer size.
The following table describes the fields in the default job specification.
|
Field Name |
Description |
Default |
|---|---|---|
|
|
The name of the job (white space is not allowed). By default, Perforce assigns
job names using a numbering scheme
( |
Last job number + 1 |
|
|
|
|
|
|
The user to whom the job is assigned, usually the person assigned to fix this particular problem. |
Perforce user name of the job creator. |
|
|
The date the job was last modified. |
Updated by Perforce when you save the job. |
|
|
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 ' to find jobs that contain all of
word1 word2 ...
wordN'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 40. 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 41. 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:
p4 jobs -e '\*string'
Searching specific fields
To search based on the values in a specific field, specify
field=value.
Example 42. 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 43. 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: =,
>, <, >=,
<=, and ^ for Boolean NOT.
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 |
|---|---|---|
|
|
A single word |
The equality operator ( The relational operators perform comparisons in ASCII order. |
|
|
A block of text entered on the lines beneath the field name. |
The equality operator ( 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 |
|
|
A single line of text entered on the same line as the field name. |
Same as |
|
|
One of a set of values. For example, job status can be
|
The equality operator ( |
|
|
A date and optionally a time. For example,
|
Dates are matched chronologically. If a time is not specified, the operators
|
|
bulk |
Like |
These fields are not searchable with p4 jobs -e. |
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 44. Using dates within expressions
Bruno wants to view all jobs modified on July 13, 2011. He enters:
p4 jobs -e 'ModifiedDate=2011/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 Server Administrator's Guide: Fundamentals 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 45. 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: 2011/06/02 13:11:57 Access: 2011/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 46. 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:
p4 fix -c 18 options-bug
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.