Chapter 10
Job Tracking

Whereas a job represents work that is intended, a changelist represents work actually done. Perforce's job tracking mechanism allows jobs to be linked 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

• The Perforce superuser or administrator decides what fields are to be tracked in your system's jobs, the possible values of a job's fields, and their default values. This job template is edited with the p4 jobspec command. (See the Perforce System Administrator's Guide for details on how to edit the job specification. The job specification need not be changed before users can create jobs).

• Jobs can be created and edited by any user with p4 job.

• The p4 jobs command can be used to look up all the jobs that meet specified criteria.

• Jobs can be linked to changelists automatically or manually; when a job is linked to a changelist, the job is marked as closed when the changelist is submitted.

• The jobs that have been fixed can be displayed with Perforce reporting commands. These commands can list all jobs that fixed particular files or file revisions, all the jobs that were fixed in a particular changelist, or all the changelists that were linked to a particular job fix.

Creating and editing jobs using the default job specification

Example:  Creating a job

Sarah's Perforce server uses Perforce's default jobs specification. Sarah knows about a job in Elm's filtering subsystem, and she knows that Ed is responsible for Elm filters. Sarah creates a new job with p4 job and fills in the resulting form as follows:

Job:    new Status: open User:   edk Date:   1998/05/18 17:15:40 Description:         Filters on the "Reply-To:" field         don't work.

Sarah has filled in a description and has changed User: to edk.

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

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.)

Creating and editing jobs with custom job specifications

A sample customized job specification might look like this:

Some of the fields have been set by the administrator to allow one 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

Throughout the following discussion, the following rules apply:

• Textual comparisons within jobviews are case-insensitive, as are the field names that appear in jobviews,

• only alphanumeric text and punctuation can appear in a jobview,

• there is currently no way to search for particular phrases. Jobviews can search jobs only by individual words.

Finding jobs containing particular words

Example:  Finding jobs that contain all of a set of words in any field.

Ed wants to find all jobs that contain the words filter, file, and mailbox. He types:

p4 jobs -e 'filter file mailbox'

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.

Example:  Finding jobs that contain any of a set of words in any field.

Ed wants to find jobs that contains any of the words filter, file or mailbox. He types:

p4 jobs -e 'filter|file|mailbox'

Finding jobs by field values

Example:  Finding jobs that contain words in specific fields

Ed wants to find all open jobs related to filtering of which he is the owner. He types:

p4 jobs -e 'status=open user=edk filter.c'

This will find all jobs with a Status: of open, a User: of edk, and the word filter.c in any non-date field.

Using and escaping wildcards in jobviews

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:

p4 jobs -e '\*string'

Negating the sense of a query

Example:  Finding jobs that don't contain particular words.

Ed wants to find all open jobs related to filtering of which he is not the owner. He types:

p4 jobs -e 'status=open ^user=edk filter'

This displays all jobs with a Status: of open, a User: of anyone but edk, and the word filter in any non-date field.

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

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

Using dates in jobviews

Example:  Using dates within jobviews.

Ed wants to view all jobs modified on July 13, 1998. He enters

p4 jobs -e 'mod_date=1998/07/13'

Comparison operators and field types

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

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:

Linking Jobs to Changelists

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

• Automatically, by setting the JobView: field in the p4 user form to a jobview that matches the job, and

• manually, with the p4 fix command.

• manually, by editing them within the p4 submit form.

Linking jobs to changelists with the JobView: field

Example:  Automatically linking jobs to changelists with the p4 user form's JobView field.

Ed wants to see all open jobs that he owns in all changelists he creates. He types p4 user and adds a JobView: field:

User:     edk Update:   1998/06/02 13:11:57 Access:   1998/06/03 20:11:07 JobView:  user=edk&status=open

All of Ed's jobs that meet these JobView: criteria automatically appear on all changelists he creates. He can, and should, delete jobs that aren't fixed by the changelist from the changelist form before submission. When a changelist is submitted, the jobs linked to it will have their status: field's value changed to closed.

Linking jobs to changelists with p4 fix

Example:  Manually attaching jobs to changelists.

You can use p4 fix to link a changelist to a job owned by another user.

Sarah has submitted a job called options-bug to Ed. Unbeknownst to Sarah, the bug reported by the job was fixed in Ed's previously submitted changelist 18. Ed links the job to the previously submitted changelist by typing:

p4 fix -c 18 options-bug

Since changelist 18 has already been submitted, the job's status is changed to closed.

Linking jobs to changelists from within the 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.

Example:  Including and excluding jobs from changelists.

Ed has set his p4 user's JobView: field as in the example above. He is unaware of a job that Sarah has made Ed the owner of (when she entered the job, she set the User: field to edk). He is currently working on an unrelated problem; he types p4 submit and sees the following:

Change: new Client: eds_ws User:   edk Status: new Description:         Updating "File" I/O files Jobs:         job000125        # Filters on "Reply-To" field don't work Files:         //depot/src/file.c         # edit         //depot/src/file_util.c    # edit         //depot/src/fileio.c       # edit

Since this job is unrelated to the work he's been doing, and since it hasn't been fixed, he deletes job000125 from the form and then quits from the editor. The changelist is submitted without job000125 being associated with the changelist.

Automatic update of job status

Example:  Submitting a changelist with an attached job.

Ed uses the reporting commands to read the details about job job000125. He fixes this problem, and a number of other bugs; when he next types p4 submit, he sees:

Change: new Client: eds_ws User:   edk Status: new Description:         Fixes a number of filter problems Jobs:         job000125          # Filters on "Reply-To" field don't work Files:           //depot/filter/actions.c    # edit         //depot/filter/audit.c      # edit         //depot/filter/filter.c     # edit

Since the job is fixed in this changelist, Ed leaves the job on the form. When he quits from the editor, the job's status is changed to closed.

What if there's no status field?

Deleting Jobs

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

Integrating with External Defect Tracking Systems

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

http://www.perforce.com/perforce/products/p4dti.html

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

Other job reporting variations are available. For more examples, please see "Job Reporting" on page 133, or consult the Perforce Command Reference.