Track Bugs Using Jobs

How do you use jobs to track bugs?

Info & Tags

Article #:
52
Created:
04/25/07
Modified:
01/09/08

TASK

How do I use Perforce jobs to track bugs?

SOLUTION

In a nutshell:

  • To report a new bug, you create a job.
  • To close a bug, you list it in the changelist when you submit a fix for it.

This simple mechanism enables Perforce's built-in job tracking and reporting features. In this note you'll find examples of how to report and close bugs, and a few very brief examples of how to mine for bug tracking information.

Reporting a bug

Each bug is entered as a separate Perforce job. To report a new bug, use: 

p4 job

This command displays a job spec in the text editor. Type in a description of the bug. When you leave the editor, a job number (e.g., job000021) is assigned to the bug.

Listing open bugs

The p4 jobs command lists bugs. To list all open bugs, use: 

p4 jobs -e "status=open"

Searching for bug reports

To search for a bug report, use p4 jobs to list a select subset of jobs, specifying keywords from the bug description . For example: 

p4 jobs -e "status=open login failure"

Closing a bug or changing its status

To close a bug, enter it in a "Jobs" field in the changelist form that comes up when you run p4 submit. For example, in the changelist form you would put: 

Description:
Clear out login data so stale values don't
prevent user from re-entering
Jobs:
job000021


When the changelist is submitted, any jobs listed in it are closed. You can also change the status to "inprogress" or some other status.

If you forget to list a job when you submit a change list, you can close (or change the status of) a bug after the fact, using p4 fix. For example, if change list 324 fixed job000021, issue the following command: 

p4 fix -c 324 job000021

or to change its status to "in_progress": 

p4 fix -c 324 -s in_progress job000021

If a submitted change list is only a partial fix, or if it turns out not to be a fix at all, you can always reopen the bug by running p4 job and changing the "Status" field in the form to "open". Specify the job name on the command, for example: 

p4 job job000021

Automatically listing open bugs in changelists

You can set up your user spec so that selected open jobs are listed automatically when you do a p4 submit. For instance, you might want to have all open bugs that have JavaScript or ASP in the description. Whenever you edit a changelist, you'll see all your open bugs listed in the "Jobs" field, and you can delete the ones you didn't fix. To set this up for yourself, use p4 user to edit your user specification and add a "Jobview" field to it: 

User:pat

Jobview:javascript|asp

Listing bugs fixed in a particular codeline

Perforce keeps track of which bugs are fixed in specific codelines. To see which bugs have been fixed in the //depot/rel3.0 codeline, for example, issue the following command: 

p4 jobs //depot/rel3.0/...

Perforce can also show you bug fixes that have been integrated from one codeline to another. For example, say you fix job000021 in //depot/rel3.0. Then you integrate changes from //depot/rel3.0 to //depot/rel3.1. When you list release 3.1 jobs using this command: 

p4 jobs -i //depot/rel3.1/...

you'll find that job000021 appears in this list as well.

Listing related changelists and bug fixes

The p4 fixes command shows which changelists are related to which bugs. For example, to show all changelists that were submitted to fix job000021, issue the following command: 

p4 fixes -j job000021

Conversely, to show all bugs that were fixed by changelist 324, issue the following command: 

p4 fixes -c 324

To show all bugs fixed by changes to files below a certain path, issue the following command: 

p4 fixes //depot/path-to-files/...

Customizing job specs

The default fields of a Perforce job spec are status, user, date, and description. You can customize the job spec template to support more sophisticated defect tracking. For instance, you can add fields like priority, product area, owner, and so forth. To customize the job spec template use the p4 jobspec command. Only users with admin access level can run the p4 jobspec command.

More information

Please visit our Technical Documentation page to find:

  • The Perforce Command Reference, which describes all the arguments and flags you can use with the p4 commands mentioned above.
  • The P4 User's Guide, which gives detailed information about entering and fixing jobs, job reporting, and using jobviews.
  • The Perforce System Administrator's Guide, which tells how to customize job specs.
  • The P4 to P4Win Translation Guide, which shows the P4Win equivalents of p4 commands.

Please visit our 2003 Users Conference page to find:

  • The conference presentation A Bug's Life: Using Perforce to Propagate and Track Bug Fixes in Evolving Software, which shows a methodology on how to track bug fixes.