P4DTI DESIGN MEETINGS WITH PERFORCE, 2000-07 Richard Brooksby, 2000-08-08 1. INTRODUCTION This document records design meetings that took place between Richard Brooksby of Ravenbrook Limited, and Christopher Seiwald of Perforce Software on 2000-07-11 and 2000-07-12. Tony Smith of Perforce Software also attended as an observer. This document is not confidential. The intended readership of this document is the P4DTI project staff. 2. EXECUTIVE SUMMARY 3. MEETING AGENDA The main purpose of the meetings was to decide how to implement changes to the Perforce SCM software to support the replication architecture for integrating it with defect tracking systems, as part of the P4DTI project. Before the meeting, Richard Brooksby and Gareth Rees identified the set of requirements that were most pressing. They were 1, 30, 36, 39-40, 43, 49, 51-55, 56-59, and 76. 4. MEETING NOTES 4.1. Maintenance No decision was made about maintenance arrangements. Ravenbrook will discuss maintenance with the new engineering manager at Perforce Software, Kathy Baldanza . Requirement 30 (maintenance) remains unresolved. 4.2. Perforce API Documentation Doug Jeffreys has Perforce API documentation on his schedule. Ravenbrook will discuss it with him and review his work to make sure it meets P4DTI project requirements. Requirement 36 (driving Perforce from the defect tracker early) depends on the API documentation. [In fact, since the defect tracking clients of tTrack and Bugzilla are web based, the API turned out to be largely irrelevant, at least initially. Driving Perforce from the defect tracking client means driving it from a web browser. This is a much harder problem [RB 2000-07-12] [GDR 2000-08-21, 5]. However, documentation will be needed for other defect tracking systems with their own clients. RB 2000-08-21] [It also transpired that Doug Jeffrey's schedule didn't include the Perforce API for some time, so Ravenbrook will need to do any documentation necessary for this project [LW 2000-08-04]. RB 2000-08-21] 4.3. Recording impact of change on a task Perforce Software will extend the "fixes relation" (the Perforce database records which store the fact that a changelist "fixes" a job) to include a keyword, so that the intended impact of the changelist on the job can be recorded, rather than assuming that a changelist always fixes and closes a job. Perforce Software will change Perforce so that jobs don't automatically get closed by fixes, but perhaps change to other states. The destination state and the "nature of association" keyword will be the same, so that something like p4 fix -s tested -c 549 job004232 takes job004232 to the "tested" state. The current behaviour of Perforce will be retained by having the default keyword be "closed". Requirement 49 (recording impact of change on a task) will be met by using the keyword to record the intended impact of a changelist on a job, and replicating the "fixes relation" to the DTDB. Unresolved issues: - How does the keyword appear and get chosen in forms (such as the submit form)? - How does the keyword appear and get chosen in the p4win GUI and other clients? Perforce Software will add parameters to "p4 fixes" and "p4 jobs" which allow filtering by fix keyword. For example "p4 fixes -s closed" to see which changelists closed jobs, so that you can tell what's been closed in a particular codeline. Perforce Software is not concerned about retaining compatibility of the textual output of Perforce in these cases. 4.4. Recording check-out information Requirements 51 (why is something checked out) and 52 (where is partially checked out work). The replicator will use a "fix" between a pending (not yet submitted) changelist and a job to record which edits (check-outs) are related to which issues. This is already supported by Perforce. When the pending changelist is submitted it may be renumbered, but this is handled correctly by the Perforce server. Requirement 51 (why is something checked out) will be met by going from the files checked out to the pending changelist they're under to the job with which they're associated to the corresponding DT issue. This will only be possible from the Perforce interface, because the relationship between files and changelists won't be replicated to the DTDB. Requirement 52 (where is partially checked out work) will be met by going from the DT issue to the corresponding job to the pending changelists which are associated with it to the files checked out under those changelists. This will only be possible from the Perforce interface, because the relationship between files and changelists won't be replicated to the DTDB. [A later meeting with Glyphic Technologies suggested that using pending changelists was a bad idea, because it's not well supported by Perforce [GDR 2000-08-21, 3]. RB 2000-08-21] 4.5. Associating files with issues The association of files with jobs will initially be implemented by a text field. Later the P4S may be modified to enforce filespec syntax in the field. Even later the P4S may be modified to support queries about which jobs are associated with which files. The design of utilities working on these associated files needs to be discussed. Requirement 54 (associating files) will be met from the Perforce interface by simply editing the associated files text field. Operations like "check out associated files" (to meet requirements 43 and 53) would have to go in the GUI as well as the command line and all the other interfaces, making this quite complicated. This is a hard requirement to meet. Also, the analyst may not specify exactly the files. And, checking out files isn't that hard, and the user can copy the files from the association list. Bringing the list of associated files up in the editor is more important than checking them out. So requirement 43 (check out associated files) may be met using utility scripts provided as part of the integration. Requirement 53 (branch and merge associated files) may be met in the same way. Requirement 53 (branching and merging associated files) wasn't discussed. Requirement 55 (recording nature of association) wasn't discussed. 4.6. Enforcing workflow restrictions The Perforce permissions implementation won't scale to cope with complicated and changing sets of permissions on files. These would make the size and space required by the server unacceptable. It would take too muchre-engineering to make protections scalable enough. Therefore requirments 56 to 59 will not be met. Perforce has no mechanism for enforcing workflow, and none is planned. Perforce Software beleives that workflow enforcement is beyond the scope of their software design. Therefore, when a user changes a job illegally the replicator will set it back and notify the user, including their attempted changes. 4.7. Consistency The P4S will be modified to keep a table of updates to jobs, changes, users, groups, and other entities that need to be replicated to the DTDB. The table will be keyed by a sequence number. The P4API (and perhaps the command-line P4 client) will be extended to contain a call to allow the replicator to ask what has been updated since a certain sequence number, and a call to delete the records of updates between two sequence numbers. The keeping of this table may be enabled by the existence of a counter in the counters table. The replicator may keep a counter to record which updates it has processed. 4.8. Using Defect Tracker as a Perforce Client Requirements 39 and 40 (Perforce actions on files from the defect tracker) were not discussed at these meetings. 4.9. Perforce Effort Chris believed that the solutions described in this document would not take him more than a few weeks to implement. A. REFERENCES [GDR 2000-08-21] "Meeting with Glyphic"; Gareth Rees; Ravenbrook Limited; 2000-08-21. [LW 2000-08-04] "Re: [dt] Perforce API documentation" (e-mail message); Laura Wingerd; Geodesic Systems; 2000-08-04 11:01:57 -0700; . [RB 2000-07-12] "The web browser as the tracker-client" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-07-12 13:17:24 -0700; . Copyright (C) 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 verbatim copies of this document provided that you do not charge a fee for this document or for its distribution. $Id: //info.ravenbrook.com/project/p4dti/doc/2000-08-08/perforce-meeting/index.txt#1 $