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 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. Since jobs do nothing more than provide this information to the user, the job reporting facilities are particularly important.
The job facilities in Perforce do not provide a full-scale job tracking system. They can be used as is, or integrated with another system via a daemon. (Daemons are described in Chapter 11.)
Jobs are created with the p4 job command.
Sarah, who shares the same Perforce server as Ed, has found a bug in Elm's filtering code. Ed is fixing code, so Sarah creates a new job with p4 job and fills in the resulting form as follows:
Job: new
User: edk
Status: new
Description:
Filters on the "Reply-To:" field
don't work.
She has changed User: from her username to edk. Ed will see this job the next time he views any pending changelist with p4 submit or p4 change.
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, or is blank, 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.
By default, all open jobs owned by a particular user will appear in all Perforce changelists subsequently created by that user. A job is automatically 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 of any status may be added to a changelist.
Ed is unaware of the job that Sarah has assigned to him. He is currently working on an unrelated problem; he types p4 submit and sees the following:
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
Since the job is fixed in this changelist, Ed leaves the job on the form. When he quits from the editor, the job is marked as closed, and will not appear in any subsequent changelists unless it is reopened.
The types of jobs that appear in new changelists created by a particular user can be controlled through the p4 user form. This form's JobView field allows one of three values:
In all three cases, any unwanted job may be deleted from the form before leaving the editor, and additional jobs can be added.
p4 fix -c changenum jobname can be used to link any job, whether open, closed, or suspended, to any Perforce changelist, whether pending or submitted. If the job is open but the changelist has already been submitted, the job is closed. If the job has been closed but the changelist is pending, the job is reopened. Otherwise, the job keeps its current status.
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.
We've already seen two ways of changing a job's status:
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. .
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.
The commands that generate reports on jobs are: