|
|
|
Chapter 5
Customizing Perforce:
Job Specifications
|
|
Perforce's jobs feature allows changelists to be linked to enhancement requests, problem reports, and other user-defined tasks. Perforce also offers P4DTI (Perforce Defect Tracking Integration) as a way to integrate third-party defect tracking tools with Perforce. See "Working with third-party defect tracking systems" on page 79 for details.
The Perforce user's use of p4 job is discussed in the Perforce User's Guide. This chapter covers superuser modification of the jobs system.
Perforce's default jobs template has five fields for tracking jobs. These fields are sufficient for small-scale operations, but as projects managed by Perforce grow, the information stored in these fields may be insufficient. To modify the job template, use the p4 jobspec command. You must be a Perforce superuser to use p4 jobspec.
This chapter discusses the mechanics of altering the Perforce job template. Certain changes to the template are forbidden. Others are permissible, but are not recommended.
Warning!
|
Improper modifications to the Perforce job template can lead to corruption of your server's database. Recommendations, caveats, and warnings about changes to job templates are summarized at the end of this chapter.
|
|
The Default Perforce Job Template
|
|
To understand how Perforce jobs are specified, we will examine the default Perforce job template. The examples that follow in this chapter are based upon modifications to the default Perforce job template.
A job created with the default Perforce job template has this format:
|
# A Perforce Job Specification.
#
# 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.
# Description: Comments about the job. Required.
Job: new
Status: open
User: edk
Date: 1998/06/03 23:16:43
Description:
<enter description here>
|
The template from which this job was created can be viewed and edited with p4 jobspec. The default job specification template looks like this:
|
# A Perforce Job Specification.
#
# Updating this form can be dangerous!
# See 'p4 help jobspec' for proper directions.
Fields:
101 Job word 32 required
102 Status select 10 required
103 User word 32 required
104 Date date 20 once
105 Description text 0 required
Comments:
# A Perforce Job Specification.
#
# 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.
# Description: Comments about the job. Required.
Values:
Status open/suspended/closed
Presets:
Status open
User $user
Date $now
Description $blank
|
|
The Job Template's Fields
|
|
There are six fields and field types in the p4 jobspec form. These fields define the template for all Perforce jobs stored on your server. The fields and field types are:
Field / Field Type
|
Meaning
|
|---|
|
Fields:
|
A list of fields to be included in each job.
Each field consists of an ID#, a name, a datatype, a length, and a setting.
|
|
Required:
|
A list of fields for which values must be entered.
|
|
Readonly:
|
A list of fields, the default values of which cannot be changed by the user.
Each field in this list requires a corresponding Presets: entry in the job specification.
|
|
Values:
|
A list of fields whose datatype is select.
For each select field, you must add a line containing the field's name, a space, and its list of acceptable values, separated by slashes.
|
|
Presets:
|
A list of fields and their default values.
Values can be either literal strings or variables supported by Perforce.
|
|
Comments:
|
The comments that appear at the top of the p4 job form.
These comments are also used by P4Win, the Perforce Windows client.
|
The Fields: field
The p4 jobspec field Fields: lists the fields to be tracked by your jobs. The default Fields: field lists these fields:
|
Fields:
101 Job word 32 required
102 Status select 10 required
103 User word 32 required
104 Date date 20 once
105 Description text 0 required
|
Each field must be listed on a separate line, and is comprised of five separate descriptors:
Field
Descriptor
|
Meaning
|
|---|
|
ID#
|
A unique integer identifier by which this field is indexed. After a field has been created and jobs entered into the system, the name of this field can change, but the data becomes inaccessible if the ID number changes.
ID numbers must be between 101 and 199.
|
|
Name
|
The name of the field as it should appear on the p4 job form.
|
|
Data Type
|
One of five datatypes (word, text, line, select, or date), as described in the next table.
|
|
Length
|
The recommended size of the field's text box as displayed in P4Win, the Perforce Windows client. To display a text box with room for multiple lines of input, use a length of 0; to display a single line, enter the Length as the maximum number of characters in the line.
The value of this field has no effect on jobs edited from the Perforce command line, and is not related to the actual length of the values stored by the server.
|
|
Persistence
|
Determines whether a field is read-only, contains default values, is required, and so on. The valid values for this field are:
- optional: field can take any value or can be deleted.
- default: a default value is provided, but it can be changed or erased.
- required: a default is given; it can be changed but the field can't be left empty.
- once: read-only; the field is set once to a default value and is never changed.
- always: read-only; the field value is reset to the default value when the job is saved. Useful only with the $now variable to change job modification dates, and with the $user variable to change the name of the user who last modified the job.
In version 98.2 of Perforce, a field's persistence was specified in a very different way. If you have upgraded from 98.2, no conversion need be done; the old persistences will appear in the p4 jobspec form in the new template.
|
The five field datatypes are:
Field Type
|
Explanation
|
Example
|
|---|
|
word
|
A single word.
|
A userid: edk
|
|
text
|
A block of text that can span multiple lines.
|
A job's description
|
|
line
|
One line of text.
|
A user's real name: Ed K.
|
|
select
|
One of a set of values.
Each field with datatype select must have a corresponding line in the Values: field entered into the job specification.
|
A job's status. One of:
open/suspended/closed
|
|
date
|
A date value.
|
The date and time of job creation:
1998/07/15:13:21:46
|
The Presets: field
All fields with a persistence of anything other than optional require default values. To assign a default value to a field, create a line in the jobspec form under Presets, consisting of the field name to which you're assigning the default value. Any single-line string can be used as a default value.
Three variables are available for use as default values:
Variable
|
Value
|
|---|
|
$user
|
The Perforce user creating the job, as specified by the P4USER environment or registry variable, or as overridden with p4 -u username job.
|
|
$now
|
The date and time at the moment the job is saved.
|
|
$blank
|
The text <enter description here>.
When users enter jobs, any fields in your jobspec with a preset of $blank must be filled in by the user before the job is added to the system.
|
The lines in the Presets: field for the standard jobs template are:
|
Presets:
Status open
User $user
Date $now
Description $blank
|
The Values: fields
You specify the set of possible values for any field of datatype select by entering lines in the Values: field. Each line should contain the name of the field, a space, and the list of possible values, separated by slashes.
In the default Perforce job specification, the Status: field is the only select field, and its possible values are defined as follows:
|
Values:
Status open/suspended/closed
|
Note
|
Prior to version 2000.1 of Perforce, the Values: and Presets: fields were specified differently.
If you have scripts that rely upon the old style of jobspecs, you might have to modify them. (Scripts that manipulate jobs, but not jobspecs, do not require modification.)
|
The Comments: field
The Comments: field supplies the comments that appear at the top of the p4 job form. Because p4 job does not automatically tell your users the valid values of select fields, which fields are required, and so on, your comments must tell your users everything they need to know about each field.
Each line of the Comments: field must be indented by at least one tab stop from the left margin, and must begin with the comment character #. The comments for the default p4 job template appear as:
|
Comments:
# A Perforce Job Specification.
#
# 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.
# Description: Comments about the job. Required.
|
If you administer a Perforce server and your users use P4Win, the Perforce Windows client, you must take extra care when writing your comments.
P4Win displays these comments in two ways:
- When the P4Win user creates or edits a job and presses the Form Info button in the job dialog box, a popup window displays the comments.
- As the (Windows) cursor moves over each field, the first line of the comment following the colon after the field name in the jobspec is displayed in a ToolTip. The remainder of each of these lines is displayed as the ToolTip for the field that matches the first word of the line. Only the first line of the comment is displayed.
- For instance, the ToolTip for the Status: field in the preceding jobspec reads:
Either 'open', 'closed', or 'suspended'. Can be changed
|
Caveats, Warnings, and Recommendations
|
|
Although the material in this section has already been presented elsewhere in this chapter, it is important enough to bear repeating. Please follow the guidelines presented here when editing job specifications with p4 jobspec.
Warning!
|
Please read and understand the material in this section before attempting to edit a job specification.
|
- After a field has been created and jobs have been entered, do not change the field's ID#. Any data entered in that field through p4 job will be inaccessible.
- Field names can be changed at any time. When changing a field's name, be sure to also change the fieldname in other p4 jobspec fields that reference this fieldname. For example, if you create a new field 106 named severity and subsequently rename it to bug-severity, then the corresponding line in the jobspec's Presets: field must be changed to bug-severity to reflect the change.
- The comments that you write in the Comments: field are the only way to let your users know the requirements for each field. Make these comments understandable and complete. These comments are treated specially in P4Win, the Perforce Windows client. For P4Win ToolTip compatibility, the first line of each field's comment should be understandable if read on its own.
- Leave the default fields 101 to 105 in the jobs system, and use p4 jobspec only to work with new fields. Do not change the names or types of fields 101 to 105 for any reason.
- Field ID# 101, the job's name, is required by Perforce and must not be deleted.
- Field ID# 102, the job's status, can be deleted; however, Perforce will subsequently be unable to update the status of jobs linked to particular changelists. If this field is present, Perforce will always set the value of this field to closed when a changelist containing this job is submitted, even if closed has been deleted from the list of possible values in the jobspec. This is highly undesirable behavior; do not change the name of field 102.
- Field ID# 105 is assumed to be a job description by Perforce clients. If present, it is also used by p4 change and p4 submit to describe the jobs fixed by the changelist.
|
Example: A Custom Template
|
|
The following example shows a more complicated jobspec and the resulting job form:
|
# A Custom Job Specification.
#
# Updating this form can be dangerous!
# See 'p4 help jobspec' for proper directions.
Fields:
101 Job word 32 required
102 Type select 10 required
103 Status select 10 required
104 Priority select 10 required
105 Subsystem select 10 required
106 Reported_by word 32 required
107 Reported_date date 20 once
108 Description text 0 required
# Custom Job fields:
#
# 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'
# Subsystem: One of p4/gui/doc/mac/misc/unknown
# Reported_by: Who's fixing the bug
# Reported_date: When the bug was first entered
# Description: Textual description of the bug
Values:
Type bug/sir/problem/unknown
Status open/closed/suspended
Priority A/B/C/unknown
Subsystem server/gui/doc/mac/misc/unknown
Presets:
Type setme
Status open
Priority unknown
Subsystem setme
Reported_by $user
Reported_date $now
Description $blank
|
Running p4 job against this jobspec displays the following job form:
|
# Custom Job fields:
#
# 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'
# Subsystem: One of p4/gui/doc/mac/misc/unknown
# Reported_by: Who reported the bug
# Reported_date: When the bug was first entered
# Description: Textual description of the bug
Job: new
Type: unknown
Status: open
Priority: unknown
Subsystem: unknown
Reported_by: edk
Reported_date: 2001/06/04 02:13:10
Description:
<enter description here>
|
The order of the listing under Fields: in the p4 jobspec form determines the order in which the fields appear to users in job forms; fields need not be ordered by numeric identifier.
|
Working with third-party defect tracking systems
|
|
With P4DTI, you can integrate Perforce with any third-party defect tracking or process management software.
Activity in your Perforce depot (enhancements, bug fixes, propagation of changes into release branches, and so forth) can be automatically entered into your defect tracking system by P4DTI. Conversely, issues and status entered into your defect tracking system (such as bug reports, change orders, work assignments) can be converted automatically to Perforce metadata for access by Perforce users.
P4DTI can be easily extended to other products; TeamShare and Bugzilla are the first two integrations published.
P4DTI is open source and available under a FreeBSD-like license.
Using P4DTI - Perforce Defect Tracking Integration
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.
Building your own integration
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. Depending on the application, the interface you set up will consist of one or more of the following:
- A trigger or script on the defect tracking system side that adds, updates, or deletes a job in Perforce every time a bug is added, updated, or deleted in the defect tracking system.
- The third-party system should generate the data and pass it to a script which reformats the data to resemble the form used by a manual (interactive) invocation of p4 job. The script can then pipe the generated form to a the standard input of a p4 job -i command.
- (The -i flag to p4 job allows p4 job to read a job form directly from the standard input, rather than using the interactive "form-and-editor" approach typical of user operations. Further information on automating Perforce with the -i option is available in the Perforce Command Reference.)
- A trigger on the Perforce side that checks changelists being submitted for any necessary bug fix information.
- A Perforce review daemon that checks successfully-submitted changelists for job fixes and issues the appropriate commands to update the corresponding data in your defect tracking system.
For more about triggers and review daemons, including examples, see "Scripting Perforce: Daemons and Triggers" on page 83.
Getting more information
In addition to the P4DTI-based TeamTrack and Bugzilla integrations, Perforce customers currently integrate Perforce with their own home-grown defect tracking systems, and with third-party systems such as Remedy, Scopus, and ClearTrack.
If you are interested in seeing what other Perforce users have done, visit the Perforce web site and examine the perforce-user mailing list archives, which are available under our Documentation page.
You may also wish to consider posting to perforce-user to ask if anyone has integrated Perforce with the third-party tool you're interested in, as someone may have already done all the setup work required to work with your system.
|
|
|
|
Please send comments and questions about this manual to
[email protected].
Copyright 1999-2001 Perforce Software. All rights reserved.
Last updated: 10/03/01
|