Perforce 98.2: Job Tracking

Perforce 98.2 p4 User's Guide


<< Previous Chapter Branching	Table of Contents Index Perforce on the Web	Next Chapter >> Change Review

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 when I press return", 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 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 particular 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 superusers.

Job Usage Overview

There are five related but distinct aspects of using jobs

Reference

The use of p4 jobspec to alter the job template is discussed in the Job Specification chapter.

The Perforce superuser 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.
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.

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

Creating and Editing Jobs using the Default Job Specification

Jobs are created with the p4 job command.

Example

Creating a Job

Sarah's Perforce server uses Perforce's default jobs specification. A bug in Elm's filtering subsystem has been reported to Sarah, 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
User: edk
Status: new
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. The default p4 job form's fields are:

Note

Since the fields that compose a job are modifiable by the Perforce superuser, the fields you see when you run p4 job might be very different then those discussed in this section.


Field Name	Description	Default
`Job`	The name of the job. Whitespace is not allowed in the name.	`new`
`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.
`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. `New` jobs exist only while a new job is being created.	`new`; changes to `open` after job creation form is closed.
`Date`	The date the job was created, displayed as `YYYY/MM/DD HH/MM/SS`	The date and time at the moment this job was created. Changes to this field will be ignored.
`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 owner and description can be changed arbitrarily; the status can be changed to any of the three valid status values open, closed, or suspended. If p4 job jobname is called with a non-existing jobname, a new job is created.

Creating and Editing Jobs with Custom Job Specifications

A Perforce superuser can add and change fields within your server's jobs template with the p4 jobspec command. If this has been done, there may be additional fields in your p4 jobs form, and the names of the fields described above may have changed. At Perforce, our jobs look (in part) like this:

Note

All the examples that follow in this chapter assume that the job specification at the right is being used.


`# Perforce Jobs at Perforce:` `#` `# Job: Job number` `# Type: The type of the job. Acceptable values are` `# "bug", "sir", "problem" or "unknown"` `# Status: Has the job been fixed: Acceptable values are` `# "open", "closed", or "suspended"` `# Priority: How soon should this job be fixed?` `# Values are "a", "b", "c", or "unknown"` `# (This is NOT the same as severity!)` `# Subsystem: One of p4/gui/doc/mac/misc/unknown` `# Owned_by: Who's fixing the bug` `# Reported_by: Who reported the bug` `# Reported_date: When the bug was first entered` `# Mod_date: Last time the bug was updated` `# Call_Numbers: If from calltrack, the call numbers` `# Customers: Email addresses of customers, one per line` `# Description: Textual description of the bug` `Job: new` `Type: unknown` `Status: open` `Priority: unknown` `Subsystem: unknown` `Owner: unowned` `Reported_By: rlo` `Reported_Date: 1998/06/03 15:09:46` `Mod_Date: 1998/06/03 15:09:46` `Description:` `<enter description here>`

Some of the fields have been set by the superuser to allow one of a set of values; for example, Priority: must be one of a, b, c, or unknown. The p4 job fields do not tell you what the valid values of a field are; this information is communicated to the user via the comments at the top of the job form, which are written by the superuser when editing the job specification. If you find the information in the comments for your jobs to be insufficient to enter jobs properly, please tell your Perforce super-user.

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:

textual comparisons within jobviews are case-insensitive, as are the field names that appear in jobviews;
only alphanumeric text can appear in a jobview;
wildcards can't be used;
there is currently no way to search for particular phrases. Jobviews can search jobs only by individual words.

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

Example

Finding all jobs that contain specific 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. To find jobs that contain any of the terms, separate the terms with the `|` character.

Note

An ampersand (&) may be used in place of a space in a jobview; thus, the jobviews
`joe sue'
and
`joe&sue' are identical. The difference is in the binding: & has highest precedence, then |, then spaces.

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

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

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

p4 jobs -e `status=open owner=edk filter'

This will find all jobs with a status: of open, an owner: of edk, and the word filter in any non-date field.

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 a specific time is not provided, the equality operator = matches the entire day.

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 usual comparison operators are available. They are:

= > < >= <=

Note

A field's type will often be 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 the superuser created at your site. The field entitled Fields: contains the job fields' names and datatypes.

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: `Elliott Smith`
`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:46`

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. The 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 will automatically change 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:

automatically, by setting the JobView: field in the p4 user form to a jobview that matches the job;
manually, with the p4 fix command.

Automatically Linking Jobs to Changelists with the p4 user Form

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.

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: owner=edk&status=open

All of Ed's jobs that meet this JobView: criteria will 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.

Automatically Performed Functions

The value of a job's status field is automatically changed to closed when one of its associated changelists is successfully submitted. Jobs can be disassociated from changelists by deleting the job from the changelist's change form, and any job can be added to a changelist.

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 owner: field to edk). He is currently working on an unrelated problem; he types p4 submit and sees the following:

Change: new
Client: edk
User: edk
Status: new
Description:
Updating "File" files
Jobs:
   job000125          # Filters on the "Reply-To" field d
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 it from the form and then quits from the editor. The changelist is submitted; the job is not associated with it.

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

Change: new
Client: edk
User: rlo
Status: new
Description:
Fixes a number of filter problems
Jobs:
   job000125 # Filters on the "Reply-To" field d
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.

Manually Associating Jobs with Changelists

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.

Example

Using p4 fix to attach a job to a changelist

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 with p4 fix -c 18 options-bug. Since the changelist has already been submitted, the job's status is changed to closed.

It is never necessary to use p4 fix to link an open job to a changelist newly created by the owner of the job, since this is done automatically. However, p4 fix can be used to link a changelist to a job owned by another user.

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 will change when the changelist is submitted. Please see the chapter Editing Job Specifications for more details.

Deleting Jobs

A job that has been linked to a changelist can be unlinked from that changelist with p4 fix -d -c changenum jobname. Jobs can be deleted entirely with p4 job -d jobname.

Integrating to External Defect Tracking Systems

The Perforce job reporting functionality can be used to integrate jobs into external programs, such as defect tracking systems, via daemons. Please see the next chapter for more information on daemons.

Job Reporting

The job reporting commands can be used to show the correspondence between files and the jobs they fix.


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 the Reporting and Data Mining chapter, or consult the Command Reference.

Perforce 98.2 p4 User's Guide


<< Previous Chapter Branching	Table of Contents Index Perforce on the Web	Next Chapter >> Change Review