Perforce 2004.2 User's Guide
<< Previous Chapter
Branching
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Reporting and Data Mining

Chapter 10
Job Tracking

A job is a written description of some modification to be made to a source code set. A job might be a bug description, like "the system crashes on invalid input", or it might be a system improvement request, like "please make the program run faster."

Whereas a job represents work that is intended, a changelist represents work actually done. Perforce's job tracking mechanism enables you to link jobs to the changelists that implement the work requested by the job. A job can later be looked up to determine if and when it was fixed, which file revisions implemented the fix, and who fixed it. A job linked to a numbered changelist is marked as completed when the changelist is submitted.

Jobs perform no functions internally to Perforce; rather, they are provided as a method of keeping track of information such as what changes to the source are needed, which user is responsible for implementing the job, and which file revisions contain the implementation of the job. The type of information tracked by the jobs system can be customized; fields in the job form can be added, changed, and deleted by Perforce administrators.

Job Usage Overview

There are five related but distinct aspects of using jobs.

The remainder of this chapter discusses how these tasks are accomplished.

Using the default job specification

Jobs are created with the p4 job command.

Because job fields differ from site to site, the fields in jobs at your site might be very different than what you see above. The default p4 job form's fields are:

Field Name
Description
Default

Job

The name of the job. Whitespace is not permitted in job names.

new

Status

open, closed, suspended, or new.

An open job is one that has been created but has not yet been fixed.

A closed job is one that has been completed.

A suspended job is an open job that is not currently being worked on.

Jobs with status new exist only while a new job is being created; they change to status open as soon as the form has been completed and the job added to the database.

new; changes to open after job creation form is closed.

User

The user whom the job is assigned to, usually the username of the person assigned to fix this particular problem.

Perforce username of the person creating the job.

Date

The date the job was last modified, displayed as YYYY/MM/DD HH/MM/SS

The date and time at the moment this job was last modified.

Description

Arbitrary text assigned by the user. Usually a written description of the problem that is meant to be fixed.

Text that must be changed

If p4 job is called with no parameters, a new job is created. The name that appears on the form is new, but this can be changed by the user to any desired string.   If the Job: field is left as new, Perforce will assign the job the name jobN, where N is a sequentially-assigned six-digit number.

Existing jobs can be edited with p4 job jobname. The user and description can be changed arbitrarily; the status can be changed to any of the three valid status values open, closed, or suspended. When you call p4 job jobname with a nonexistent jobname, Perforce creates a new job. (A job, if submitted with a Status: of new, has this status automatically changed to open upon completion of the job form.)

Using a custom job specification

A Perforce administrator can add and change fields within your server's jobs template with the p4 jobspec command. If this has been done, there might be additional fields in your p4 jobs form, and the names of the fields described above might have changed.

A sample customized job specification might look like this:

# Custom Job fields:
# Job:    The job name. 'new' generates a sequenced job number.
# Status: Either 'open', 'closed', or 'suspended'. Can be changed
# User:   The user who created the job. Can be changed.
# Date:   The date this specification was last modified.
# Type:          The type of the job. Acceptable values are
#                'bug', 'sir', 'problem' or 'unknown'
# Priority:      How soon should this job be fixed?
#                Values are 'a', 'b', 'c', or 'unknown'
# Subsystem:     One of server/gui/doc/mac/misc/unknown
# Owned_by:      Who's fixing the bug
# Description: Comments about the job. Required.

Job:    new
Status: open
User:   setme
Type:   setme
Priority:       unknown
Subsystem:      setme
Owned_by:       edk
Description:
        <enter description here>

Some of the fields have been set by the administrator to use one value out of a set of values; for example, Priority: must be one of a, b, c, or unknown. The p4 job fields don't tell you what the valid values of the fields are; your Perforce administrator can tell you this in comments at the top of the job form. If you find the information in the comments for your jobs to be insufficient to enter jobs properly, please tell your Perforce administrator.

Viewing jobs by content with jobviews

Jobs can be reported with p4 jobs. In its simplest form, with no arguments, p4 jobs will list every job stored in your Perforce server. However, p4 job -e jobview will list all jobs that match the criteria contained in jobview.

Throughout the following discussion, the following rules apply:

Finding jobs containing particular words

The jobview 'word1 word2 ... wordN' can be used to find jobs that contain all of word1 through wordN in any field (excluding date fields).

Spaces between search terms in jobviews act as boolean and's. You can use ampersands instead of spaces in jobviews, so the jobviews 'joe sue' and 'joe&sue' are identical.

To find jobs that contain any of the terms, separate the terms with the '|' character.

Finding jobs by field values

Search results can be narrowed by matching values within specific fields with the jobview syntax 'fieldname=value'. Value must be a single alphanumeric word.

Using and escaping wildcards in jobviews

The wildcard "*" enables you to perform partial word matches. The jobview "fieldname=string*" matches "string", "stringy", "stringlike", and so on.

To search for words that happen to contain wildcards, escape them at the command line. For instance, to search for "*string" (perhaps in reference to char *string), you'd use the following:

Negating the sense of a query

The sense of a search term can be reversed by prefacing it with ^, the not operator.

The not operator ^ can be used only directly after an and (space or &). For instance, the command p4 jobs -e '^user=edk' is not permitted.

You can use the * wildcard to work around this restriction: p4 jobs -e 'job=* ^user=edk' returns all jobs with a user field not matching edk.

Using dates in jobviews

Jobs can be matched by date by expressing the date as yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss. If you don't provide a specific time, the equality operator = matches the entire day.

Comparison operators and field types

The usual comparison operators are available. They are:

=

>

<

>=

<=

The behavior of these operators depends upon the type of the field in the jobview.The field types are:

Field Type
Explanation
Examples

word

A single word

A user name: edk

text

A block of text

A job's description

line

A single line of text. Differs from text fields only in that line values are entered on the same line as the field name, and text values are entered on the lines beneath the field name.

An email address

A user's real name, for example Linda Hopper

select

One of a set of values

A job's status:

open/suspended/closed

date

A date value

The date and time of job creation:

1998/07/15:13:21:4

Field types are often obvious from context; a field called mod_date, for example, is most likely a date field. If you're not sure of a field's type, run p4 jobspec -o, which outputs the job specification your local jobspec. The field called Fields: lists the job fields' names and datatypes.

The jobview comparison operators behave differently depending upon the type of field they're used with. The comparison operators match the different field types as follows:

Field Type
Use of Comparison Operators in Jobviews

word

The equality operator = must match the value in the word field exactly.

The inequality operators perform comparisons in ASCII order.

text

The equality operator = matches the job if the word given as the value is found anywhere in the specified field.

The inequality operators are of limited use here, since 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 jobview is 'ShortDesc<filter', the job will match the jobview, because bug<filter.

line

See text, above.

select

The equality operator = matches a job if the value of the named field is the specified word. Inequality operators perform comparisons in ASCII order.

date

Dates are matched chronologically. If a specific time is not provided, the operators =, <=, and >= will match the whole day.

Linking Jobs to Changelists

Perforce automatically changes the value of a job's status field to closed when the job is linked to a particular changelist, and the changelist is submitted.

Jobs can be linked to changelists in one of two ways:

Linking jobs to changelists with the JobView: field

The p4 user form can be used to automatically include particular jobs on any new changelists created by that user. To do this, call p4 user and change the JobView: field value to any valid jobview.

Linking jobs to changelists with p4 fix

p4 fix -c changenum jobname can be used to link any job to any changelist. If the changelist has already been submitted, the value of the job's Status: field is changed to closed. Otherwise, the job keeps its current status.

Linking jobs to changelists when submitting

You can also add jobs to changelists by editing the Jobs: field (or creating a Jobs: field if none exists) in the p4 submit form.

Any job can be linked to a changelist by adding it to a changelist's change form, or unlinked from a changelist by deleting the job from the changelist's change form.

Automatic update of job status

The value of a job's Status field is automatically changed to closed when one of its associated changelists is successfully submitted.

What if there's no status field?

The discussion in this section has assumed that the server's job specification still contains the default Status: field. If the job specification has been altered so that this is no longer true, jobs can still be linked to changelists, but nothing in the job changes when the changelist is submitted. (In most cases, this is not a desired form of operation.) Please see the chapter on editing job specifications in the Perforce System Administrator's Guide for more details.

Deleting Jobs

A job can be unlinked from any changelist with p4 fix -d -c changenum jobname.

Jobs can be deleted entirely with p4 job -d jobname.

Integrating with External Defect Tracking Systems

If you want to integrate Perforce with your in-house defect tracking system, or develop an integration with a third-party defect tracking system, P4DTI is probably the best place to start.

To get started with P4DTI, see the P4DTI product information page at:

Available from this page are the TeamShare and Bugzilla implementations, an overview of the P4DTI's capabilities, and a kit (including source code and developer documentation) for building integrations with other products or in-house systems.

Even if you don't use the P4DTI kit as a starting point, you can still use Perforce's job system as the interface between Perforce and your defect tracker. See the Perforce System Administrator's Guide for more information.

Job Reporting Commands

The job reporting commands can be used to show the relationship between files, changelists, and their associated jobs.

To See a Listing of...
Use This Command:

...all jobs that match particular criteria

p4 jobs -e jobview

...all the jobs that were fixed by changelists that affected particular file(s)

p4 jobs filespec

...all changelists and file revisions that fixed a particular job

p4 fixes -j jobname

...all jobs linked to a particular changelist

p4 fixes -c changenum

...all jobs fixed by changelists that contain particular files or file revisions

p4 fixes filespec

Other job reporting variations are available. For more examples, please see "Job Reporting" on page 139, as well as the Perforce Command Reference.


Perforce 2004.2 User's Guide
<< Previous Chapter
Branching
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Reporting and Data Mining
Please send comments and questions about this manual to [email protected].
Copyright 1997-2004 Perforce Software. All rights reserved.
Last updated: 08/19/04