Perforce Defect Tracking Integration User's Guide

1. Introduction

This is the Perforce Defect Tracking Integration 0.3 User's Guide.

Warning: The Perforce Defect Tracking Integration version 0.4 is a is beta test software, only intended for use during the beta program of the project. The software will be defective. We recommend that you do not rely on the integration in your organization. The integration may destroy your data. See the project web site <http://www.ravenbrook.com/project/p4dti/> for information about planned releases. We are very interested in your feedback on the beta. Please write to p4dti-beta-feedback@ravenbrook.com.

This is outline documentation, still in development.

[What is this document? Who should be reading it? Reqs 1-5. Section not written yet. LMB 2000-10-15]

If you need more information on using Perforce, please see the Perforce User's Guide, the Perforce Command Reference, or the on-line help system. If you need more information on using your defect tracking system, please see the manuals for the system or consult your defect tracking administrator.

If you're administering the Perforce Defect Tracking Integration (P4DTI), you'll need our Perforce Defect Tracking Integration Administrator's Guide. If you're installing the P4DTI, the Administrator's Guide is the place to start.

2. Overview of the software

This section describes what the integration does and how it does it, and provides a summary of the benefits of installing the integration in your organization. It also contains some important information on how associations work and on what happens if you do something in Perforce that's illegal in the defect tracker.

2.1. What does the integration do?

[Section not written yet. LMB 2000-11-26]

2.2. How does it work?

[Section not written yet. LMB 2000-11-26]

2.3. How will it make my life easier?

[Section not written yet. LMB 2000-11-26]

2.4. Some general notes about associations between changelists and tasks

[Section not finished yet. LMB 2000-11-26]

Your organization should have a policy about which changelists to associate with tasks. For example, some organizations might want only the final check-in of a fix associated, and some might want all the intermediate stages associated. For information on your organization's policy, consult your manager or the integration administrator.

A changelist is only ever associated with a task once. If you associate it with the same task again using a different keyword, the effect is just to change the keyword.

You can delete associations between changelists and jobs in Perforce by using the p4 fix -d command. For details, see "Manually Associating Jobs with Changelists" in the Perforce User's Guide [Perforce 2000-10-09, chapter 10]. [These are mostly general points about associations that we could document in overview. RB 2000-11-10]

2.5. What if I do something in Perforce that's not allowed in the defect tracker, and vice versa?

If you do something in Perforce that the defect tracker doesn't allow — for example, if your action causes an error, or if it's forbidden by the DT's rules — then the replicator undoes the change in Perforce when it next wakes up, and sends you an e-mail message explaining what happened. The e-mail message contains your changes, so you won't have lost them.

[How likely is this? What sorts of things are illegal? How long will it take for the replicator to wake up? Should give them some sort of time estimate -- 10 minutes? An hour? It depends? How do they go about re-doing whatever they've done, if the way they originally did it is illegal? LMB 2000-11-26]

[We need to talk about what happens when you do something in Perforce that's illegal in the defect tracker (either an error, or forbidden by the rules that the DT has set up). The replicator undoes the change in Perforce when it next wakes up, and sends an e-mail message to the user explaining what happened. The e-mail message includes the changes that the user made, so they're not lost forever. Unfortunately, we can't let them know straight away. RB 2000-10-11]

3. Organization guide

This section describes some things you need to consider before adopting the integration in your organization.

[Section not written yet. LMB 2000-10-15]

3.1. Who will install the product

[Section not written yet. LMB 2000-10-15]

3.2. Who will configure the product

[Section not written yet. LMB 2000-10-15]

3.2.1. Configuration decisions

[Section not written yet. LMB 2000-10-15]

3.3. Who will administer the product

[Section not written yet. LMB 2000-10-15]

3.3.1. Resolving conflicts

[Section not written yet. LMB 2000-10-15]

3.4. Who will maintain the product

[Section not written yet. LMB 2000-10-15]

3.5. Training

[Section not written yet. LMB 2000-10-15]

4. Using the P4DT integration

[Section not written yet. LMB 2000-10-15]

4.1. Viewing a list of issues assigned to you

You can use Perforce to see the issues assigned to you. Each issue is represented by a Perforce job, and you can use the Perforce job commands.

Each job has a field containing the name of the user to whom it is assigned. The exact name of this field depends on which defect tracker you're using and how the integration has been configured for your organization. Ask your administrator if you're not certain which field to use. This section assumes that the field is called "Owner".

If you're using the Perforce Windows GUI, follow these steps:

1. Select the jobs pane by choosing Jobs → View Jobs.
2. Choose Jobs → Filter and enter a jobview [Perforce 2000-10-09, chapter 10] such as "owner=spqr" (where "spqr" is your Perforce userid). This restricts the jobs you see to those assigned to you.
3. You may also find it useful to click the Status column heading to sort the jobs by their status.

If you're using the Perforce command line, enter a p4 jobs command. For example, the command

p4 jobs -e "owner=spqr"

displays a list of jobs assigned to the user whose Perforce userid is "spqr".

Perforce release 2000.2 does not provide a way of viewing the list of jobs assigned to you from the Web GUI (P4Web) or any of the development environment plug-ins.

4.2. Associating submitted changelists with tasks

You can use Perforce to associate a change that you've already made with a task you've been assigned.

For example, suppose you realize that the changes you made yesterday will also resolve the tasks you've been assigned to work on today. You need to record this in the defect tracking system so that SQA can check that you're right.

If you're using the Perforce Windows GUI, you can do this as follows. Note: Due to a limitation in the Perforce GUI, this will change the status of all of the selected jobs to "closed". If you want to leave the status alone or change it to another value, you must use the command line. [This should be fixed by the beta release. RB 2000-11-10]

1. Select the Submitted Perforce Changelists pane by choosing Changelist → View Submitted Changelists.
2. Select the changelist that you want to associate.
3. Choose Changelist → Add Job Fix.
4. In the dialog that opens, select the set of jobs you want to associate with the changelist.
5. Click OK.

If you're using the Perforce command line, enter a p4 fix command. For example, the command

p4 fix -s resolved -c 4096 ENH00023 BUG001239

associates changelist 4096 with tasks ENH00023 and BUG001239 and changes their status to "resolved". If you don't specify a "-s" option, the task status is changed to "closed".

Perforce release 2000.2 does not provide a way of associating submitted changelists with jobs from the Web GUI (P4Web) or any of the development environment plug-ins.

4.3. Submitting changes and associating them with a task

You can use Perforce to check in your work, associate it with a task, and change the status of that task — all at the same time.

Suppose you're working on one or more tasks and have checked out and edited files to resolve those tasks. You now wish to submit the final changes and record the completion of the tasks in one step.

Note: Perforce release 2000.2 only allows a job to be changed to the "closed" status from the Perforce GUI when associating them with a changelist.

There are three ways to do this:

• automatically [Perforce 2000-10-09, chapter 10.5.1]
• manually [Perforce 2000-10-09, chapter 10.5.3]
• after submitting the changelist

[Need to give a one-line explanation of when each method is most useful so that users don't have to read more than necessary. LMB 2000-11-18]

4.3.1. Automatically

To use this method, you must first set a user jobview [Perforce 2000-10-09, chapter 10.5.1] to something like "owner=spqr", where "spqr" is your Perforce userid. You can do this using either of the following methods:

• In the Windows GUI, choose "Users → Edit spqr".
• From the command line, type p4 change to edit your user spec.

If you're using the Windows GUI and your jobview is set, a list of jobs with which you can associate changelists appears in the dialog when you submit or create a changelist. Select the list of jobs you want to associate your changelist with. When you submit your changelist, the status of those jobs changes to "closed" and the changelist is associated with them. [There's no interface to setting the status yet, so jobs will always go to "closed" if you choose them. RB 2000-11-10] If the list of jobs doesn't show up, then cancel the submission, press F5, and try again.

If you're using the command line and your jobview is set, a list of jobs with which you can associate changelists appears in the text form when you submit or create a changelist. Delete the jobs you don't want to associate with your changelist from the list. When you submit your changelist, the status of the jobs you left in the form changes to "closed" and the changelist is associated with them. [There's no interface to setting the status yet, so jobs will always go to "closed" if you choose them. RB 2000-11-10]

If you're using the Microsoft Visual Studio plug-in and your jobview is set, leave the check-in comment blank and click OK when the check-in dialog appears. This will open a second, more detailed, dialog that includes a list of jobs to choose from. Delete the jobs you don't want to associate with your changelist from the list. When you submit your changelist, the status of the jobs you left in the form changes to "closed" and the changelist is associated with them. [There's no interface to setting the status yet, so jobs will always go to "closed" if you choose them. RB 2000-11-10]

[The CodeWarrior (on Mac OS and Windows) plug-in shares code with the Visual Studio plug-in, but I'm not sure if the behaviour is quite the same. We need to find out. RB 2000-11-10]

Perforce release 2000.2 has no way of associating submitted changelists with jobs from the Web GUI (P4Web).

4.3.2. Manually

If you're using the Perforce Windows GUI, follow these steps:

1. Select the Pending Perforce Changelists pane by choosing Changelist → View Pending Changelists. (If the changes you want to associate are in the Default changelist, you first need to create a new pending changelist with those changes. To do this, choose Changelist → New and enter a description of your change.)
2. Select the changelist that you want to associate.
3. Choose Changelist → Add Job Fix.
4. Select the set of jobs you want to associate the changelist with in the dialog.
5. Click OK.

When you submit the changelist, the status of those jobs will change to "closed" and the changelist will be associated with them. [There's no interface to setting the status yet, so jobs will always go to "closed" if you choose them. RB 2000-11-10].

If you're using the Perforce command line, follow these steps:

1. If the changes you want to associate are in the Default changelist, you first need to create a new pending changelist with those changes. To do this, type p4 change and enter a description.

2. Then enter a command like

   p4 fix -s resolved -c 3004 ENH00034 BUG00094

   where "resolved" is the status you want the jobs to change to, "3004" is the pending changelist number, and "ENH00034" and "BUG00094" are the jobs you want to associate the changelist with.

Perforce release 2000.2 has no way of handling numbered pending changelists from the Web GUI (P4Web) or any of the development environment plug-ins, so this method is not available from those interfaces.

4.3.3. After submitting the changelist

You can submit the changelist and then associate it with the tasks. See Section 4.2.

4.4. Submitting work in progress and associating it with tasks

Note: Your organization's policy regarding associations between changes and tasks may not allow you to use this feature. For further information, see Section 2.4 and consult your manager or integration administrator.

If you're associating intermediate stages of changelists with tasks, you probably don't want to change the status of the task. The way to do this is to associate the changelist with the task as usual [see elsewhere], but with the same status as the task currently has. For example, in Perforce you can use the p4 fix command with the "-s" argument set to be the current status of that task. When associating the final check-in, the "-s" argument will be something like "fixed" or "resolved" or perhaps "closed". [We probably need to explain this in overview somewhere, and include instructions about making this policy in the management guide. RB 2000-11-10 Done in overview. LMB 2000-11-26]

This procedure is exactly like the procedures described in Section 4.3, except that, when fixing the job, you need to set the status to the job's current status. [There's no interface to doing this from the GUI, or during submission from any of the interfaces. But there should be by the beta. RB 2000-11-10]

If you're using the Perforce command line, follow these steps:

1. If the changes you want to associate are in the Default changelist, you first need to create a new pending changelist with those changes. To do this, type p4 change and enter a description.

2. Enter a command like

   p4 fix -s assigned -c 3004 ENH00034 BUG00094

   where "assigned" is the current status of the job, "3004" is the pending changelist number, and "ENH00034" and "BUG00094" are the jobs you want to associate the changelist with.

Perforce release 2000.2 has no way of handling numbered pending changelists from the Web GUI (P4Web) or any of the development environment plug-ins, so this method is not available from those interfaces. It is also not available from the Windows GUI.

4.5. Changing job status without associating changes

You can change the status of a job in Perforce without associating any changes. This feature is useful when:

• you want to add a note to the task record and change its status. For example, there might be a workaround that you need to tell people about, rather than fixing anything in the code.
• you have been assigned a task, but need to send it back to your manager because you can't do it for some reason.

To do this, just edit the job status. Depending on your organization's policies, you may need to add some text explaining why you've done this. (If you have made changes and have already submitted them, you need to link them to the job using the method described in Section 4.2.)

If you're using the Perforce Windows GUI, follow these steps:

1. Select the job whose status you need to edit.
2. Choose Job → Edit Job. [Need to check exact command name. LMB 2000-11-19]
3. Edit the status of the job appropriately. [Need to be more specific. LMB 2000-11-19]
4. If your organization's policy requires it, fill in the appropriate fields to explain why no change was needed.

If you're using the Perforce command line, enter a p4 job command and edit the status of the job appropriately. For example, the command

p4 job jobname

[Need to fill in this command with sample data and describe what it does. LMB 2000-11-19] For details, see "Creating and Editing Jobs using the Default Job Specification" in the Perforce User's Guide [Perforce 2000-10-09, chapter 10]. If your organization's policy requires it, fill in the appropriate fields to explain why no change was needed.

Perforce release 2000.2 does not provide a way of completing a task from the Web GUI (P4Web) or any of the development environment plug-ins.

[If the developer _has_ made changes earlier, they should link them to the job using the "Too late really" method. But sometimes an issue might change status with no change made. For example, the developer might want to send it back to the manager for re-assignment, because they can't fix it, or they might make a correction to documentation which is (shudder) not stored in Perforce. In that case, they want to change the job status without linking the job with a changelist. In that case, they just edit the job. RB 2000-11-16]

[Just edit the job status using the normal interface (see Perforce User's Guide), and perhaps fill in other fields to explain why no change was needed, depending on your organization's policy and workflow. RB 2000-11-10]

4.6. Creating a task

This feature is not yet supported from any of the Perforce interfaces.

[Just create a task as usual from the defect tracker's interface. We don't support creating tasks from the Perforce interface yet, but we might do by the beta. When we do, it'll just be a matter of creating a job as usual from Perforce's interface (see the Perforce User's Guide). RB 2000-11-10]

4.7. Finding the changes resulting from an issue

• find out what was done about a bug
• verify that an issue has been dealt with correctly
• check that all the changes associated with the issue are properly justified
• see what areas of the code have changed so that you can direct testing at those areas

If you're using the Perforce command line, enter a p4 fixes command. For example, the command

p4 fixes -j ENH00034

will list the changes resulting from task ENH00034. For details, see "Job Reporting" in the Perforce User's Guide.

Perforce release 2000.2 does not provide a way of finding the changes resulting from an issue from the Windows GUI, the Web GUI (P4Web), or any of the development environment plug-ins.

4.8. Finding the issues associated with a changelist

You can use Perforce to see the issues associated with a changelist.

If you're using the Perforce Windows GUI, follow these steps:

1. Select the changelist you are interested in.
2. Choose Changelist → Describe Changelist <number>.
3. Look under the Jobs Fixed heading to see the issues associated with this changelist.

If you're using the Perforce command line, enter a p4 fixes command. For example, the command

p4 fixes -c 4339

finds the issues associated with changelist 4339. For details, see "Job Reporting" in the Perforce User's Guide.

Perforce release 2000.2 does not provide a way of finding the issues associated with a changelist from the Web GUI (P4Web) or any of the development environment plug-ins.

4.9. Finding issues associated with files

You can use Perforce to find the issues associated with particular files.

If you're using the Perforce command line, enter a p4 fixes or a p4 jobs command. For example, the command

p4 fixes //depot/foo/bar/*.c

will list the associations and changelists for the files with a ".c" extension in the "/depot/foo/bar" directory, and the command

p4 jobs //depot/foo/bar/*.c

will list the jobs for the files with a ".c" extension in the "/depot/foo/bar" directory. For details, see "Job Reporting" in the Perforce User's Guide.

Perforce release 2000.2 does not provide a way of finding issues associated with files from the Windows GUI, the Web GUI (P4Web), or any of the development environment plug-ins.

[We don't plan to support this from the DT, because the DT doesn't know which files have changed, only the changelist numbers. The way to do that will be to follow a link from the DT interface to a web interface to Perforce. RB 2000-10-11]

4.10. Finding files that were changed to resolve issue

You can use Perforce to find out which files were changed in order to fix an issue.

To do this, you first need to find out the changes associated with the check-in, using one of the following methods:

Once you know the changelist, you can use a p4 describe command at the Perforce command line or you can use the Changelist → Describe command in the Windows GUI. For example, this command

p4 describe 4339

outputs a list of the files that were checked in to fix the issue and the diffs for those files.

If you now want to see the whole source tree, you can use a p4 sync command. For example, this command

p4 sync //depot/main/...@4339

synchronizes the entire tree below "main" to the state it was in at changelist 4339. You can also look at individual files using a p4 print command. For example, this command

p4 print //depot/main/spong.c@4339

writes the contents of the file spong.c as it was at changelist 4339 to the standard output.

For more details, see "How to Specify Older File Revisions" in the Perforce Command Line User's Guide [Perforce 2000-10-09].

Perforce release 2000.2 does not provide a way of finding files that were checked in for an issue from the Windows GUI, the Web GUI (P4Web), or any of the development environment plug-ins. [We might be able to do something from the GUI using the extensible "Tools" menu using a command like p4 fixes %j. RB 2000-11-26]

4.11. Finding issues associated with a version or release

[Section not written yet. LMB 2000-10-15]

4.12. Finding the version or release associated with an issue

[Section not written yet. LMB 2000-10-15]

4.13. Finding tasks being worked on in a workspace

If you use pending changelists and associate them with files, you can find out which tasks you have been working on in a particular workspace. This is useful when, for example, you are resuming work on a project after a few days away and can't quite remember which tasks you were last working on. (If you want to find out which workspace contains a particular task you have been working on, see Section 4.14.)

In order to use this feature, you must create a changelist and associate it with a job early on — this records your intention to resolve the job.

If you are using the Windows GUI, you can later find out which tasks you were working on by looking at the pending changelists you set up.

If you are using the Perforce command line, you can find out what you were working on by using a combination of the p4 changes and p4 fixes commands. For example, these commands

p4 changes -s pending filespec...
p4 fixes

[Need to fill in these commands with sample data and describe what each one does. LMB 2000-11-18]

Perforce release 2000.2 does not provide a way of finding tasks being worked on in a particular workspace from the Web GUI (P4Web) or any of the development environment plug-ins. [This isn't true. RB 2000-11-10]

[This relies on people using pending changelists and associating them with jobs. The developer checks out some files, creates a new changelist, and associates it with a job before they get very far with modifications. This records their intention to resolve the job. So they can find out what they're working on by looking at the pending changelists. From the command line, use p4 changes -s pending filespec... then use p4 fixes to figure out which jobs they're associated with. In the GUI, look at the pending changelists. RB 2000-11-10]

4.14. Finding the workspace in which a task is being worked on

If you use pending changelists and associate them with files, you can find out which workspace contains a particular task you have been working on. This is useful when, for example, you are resuming work on a project after a few days away and can't quite remember where the task you want to work on is. (If you want to find out which tasks you were working on in a particular workspace, see Section 4.13.)

If you are using the Perforce command line, you can find out which workspace you were working in by using a combination of the p4 fixes and p4 describe commands. For example, these commands

p4 fixes -j BUG0743
p4 describe 4339

first determine which changelist is associated with the job, and then determine in which client workspace the changelist is open. [Need to fill in these commands with sample data. LMB 2000-11-18]

Perforce release 2000.2 does not provide a way of finding the workspace in which a task is being worked on from the Windows GUI, the Web GUI (P4Web), or any of the development environment plug-ins.

[This relies on the same practice as section 4.13. Use p4 fixes -j jobname to find out which changelist is associated with the job, then use p4 describe changelist to find out in which client workspace the changelist is open. RB 2000-10-11]

4.15. Editing or adding to an issue

You can edit the contents of the job record in Perforce. This is useful when you want to:

• add more description to the job record
• write notes about how the job was fixed, what else needs to be done, and so on
• correct something in the job record

[This is the case where the user simply wants to edit the contents of the issue record. For example, to add some more description, or write some notes, or correct something. This might usefully be combined with, or referenced from, section 4.5, which is kind of a special case of this. RB 2000-10-20]

5. Glossary

[Section not written yet. LMB 2000-10-15]

A. References

B. Document History

Copyright © 2000 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute copies and derivative works of this document provided that (1) you do not charge a fee for this document or for its distribution, and (2) you retain as they appear all copyright and licence notices and document history entries, and (3) you append descriptions of your modifications to the document history.