|
|
|
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.
- 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. (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.
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.
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
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.
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:
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.
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.
|
|
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 are 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 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 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.
A sample customized job specification might look like this:
|
# Sample customized jobspec
#
# Job: Job number
# Type: The type of request: "bug" or "feature"
# Status: Has it been fixed: "open", "closed", or "inprogress"
# Priority: How soon should this job be fixed?
# Values are "a", "b", "c", or "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
# Description: Textual description of the bug
Job: new
Type: unknown
Status: open
Priority: unknown
User: unowned
Reported_By: edk
Reported_Date: 2001/06/02 10:09:46
Mod_Date: 2001/06/03 14:22:38
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 don't tell you what the valid values of the fields are; your Perforce superuser 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 superuser.
|
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,
- 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 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
Search results can be narrowed by matching values within specific fields with the jobview syntax 'fieldname=value'. Value must be a single alphanumeric word.
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'
This will find all jobs with a Status: of open, a User: of edk, and the word filter in any
non-date field.
Using wildcards in jobviews
The wildcard "*" allows for partial word matches. The jobview "fieldname=string*" matches "string", "stringy", "stringlike", and so on.
Negating the sense of a query
The sense of a search term can be reversed by prefacing it with ^, the not operator.
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
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.
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:
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: 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:
- 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.
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: user=edk&status=open
|
All of Ed's jobs that meet these 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.
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. Jobs can be disassociated from changelists by deleting the job from the changelist's change form. Similarly, any job can be added to a changelist by adding it to a 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: edk
User: edk
Status: new
Description:
Updating "File" 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
it from the form and then quits from the editor. The changelist is submitted, and the job is not
associated with it.
Example:
Submit a changelist with an attached job.
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 "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.
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:
Manually attaching jobs to changelists.
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, you can use p4 fix 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 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 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 "Job Reporting" on page 122, or consult the Perforce Command Reference.
|
|
|
|
Please send comments and questions about this manual to
[email protected].
Copyright 1997-2001 Perforce Software. All rights reserved.
Last updated: 10/03/01
|