Helix SwarmHelix Swarm

index.html

  • //
  • guest/
  • hari_krishna_dara/
  • perforce/
  • p4dti/
  • release/
  • 2.2.2/
  • ig/
  • index.html #1
  • View
  • Commits
  • Open Download .zip Download (175 KB) 
  1. <?xml version="1.0" encoding="UTF-8"?>
  2.  
  3. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
  4.  
  5. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  6.  
  7. <head>
  8.  
  9. <title>Perforce Defect Tracking Integration Integrator's Guide</title>
  10.  
  11. </head>
  12.  
  13. <body bgcolor="#FFFFFF" text="#000000" link="#000099" vlink="#660066" alink="#FF0000">
  14.  
  15. <div align="center">
  16.  
  17. <p><i><a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration Project</a></i></p>
  18.  
  19. <hr />
  20.  
  21.  
  22. <h1>Perforce Defect Tracking Integration Integrator's Guide</h1>
  23.  
  24. <address>
  25. <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>,
  26. <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>,
  27. 2000-10-16
  28. </address>
  29.  
  30. </div>
  31.  
  32.  
  33. <h2><a id="section-Contents" name="section-Contents">Contents</a></h2>
  34.  
  35. <ul>
  36.  
  37. <li><a href="#section-1">1. Introduction</a>
  38.  
  39.   <ul>
  40.  
  41.   <li><a href="#section-1.1">1.1. Kit layout</a></li>
  42.  
  43.   <li><a href="#section-1.2">1.2. Levels of requirement</a></li>
  44.  
  45.   </ul>
  46.  
  47. </li>
  48.  
  49. <li><a href="#section-2">2. Understanding the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
  50.  
  51.   <ul>
  52.  
  53.   <li><a href="#section-2.1">2.1. Prerequisites</a></li>
  54.  
  55.   <li><a href="#section-2.2">2.2. Requirements overview</a></li>
  56.  
  57.   <li><a href="#section-2.3">2.3. Architecture overview</a></li>
  58.  
  59.   <li><a href="#section-2.4">2.4. Design overview</a></li>
  60.  
  61.   </ul>
  62.  
  63. </li>
  64.  
  65. <li><a href="#section-3">3. What you need to do</a>
  66.  
  67.   <ul>
  68.  
  69.   <li><a href="#section-3.1">3.1. Before you start work</a></li>
  70.  
  71.   <li><a href="#section-3.2">3.2. Getting help</a></li>
  72.  
  73.   <li><a href="#section-3.3">3.3. Adapting an existing integration</a></li>
  74.  
  75.   <li><a href="#section-3.4">3.4. Developing a new integration</a></li>
  76.  
  77.   <li><a href="#section-3.5">3.5. Optional features</a></li>
  78.  
  79.   </ul>
  80.  
  81. </li>
  82.  
  83. <li><a href="#section-4">4. Defect tracker database schema extensions</a>
  84.  
  85.   <ul>
  86.  
  87.   <li><a href="#section-4.1">4.1. Issues</a></li>
  88.  
  89.   <li><a href="#section-4.2">4.2. Changelists</a></li>
  90.  
  91.   <li><a href="#section-4.3">4.3. Fixes</a></li>
  92.  
  93.   <li><a href="#section-4.4">4.4. Filespecs</a></li>
  94.  
  95.   <li><a href="#section-4.5">4.5. Replicator configuration and state</a></li>
  96.  
  97.   <li><a href="#section-4.6">4.6. Discovering what's changed</a></li>
  98.  
  99.   <li><a href="#section-4.7">4.7. Distinguishing replicated changes from other changes</a></li>
  100.  
  101.   <li><a href="#section-4.8">4.8. Perforce users who don't have licenses in the defect tracker</a></li>
  102.  
  103.   </ul>
  104.  
  105. </li>
  106.  
  107. <li><a href="#section-5">5. Coding conventions</a>
  108.  
  109.   <ul>
  110.  
  111.   <li><a href="#section-5.1">5.1. Messages</a></li>
  112.  
  113.   <li><a href="#section-5.2">5.2. Message catalogs</a></li>
  114.  
  115.   <li><a href="#section-5.3">5.3. Logging</a></li>
  116.  
  117.   <li><a href="#section-5.4">5.4. Errors</a></li>
  118.  
  119.   <li><a href="#section-5.5">5.5. Source code layout</a></li>
  120.  
  121.   <li><a href="#section-5.6">5.6. Making changes</a></li>
  122.  
  123.   </ul>
  124.  
  125. </li>
  126.  
  127. <li><a href="#section-6">6. The Python interface to the defect tracker</a></li>
  128.  
  129. <li><a href="#section-7">7. The defect tracker module</a>
  130.  
  131.   <ul>
  132.  
  133.   <li><a href="#section-7.1">7.1. The <code class="source">defect_tracker</code> class</a></li>
  134.  
  135.   <li><a href="#section-7.2">7.2. The <code class="source">defect_tracker_issue</code> class</a>
  136.  
  137.     <ul>
  138.  
  139.     <li><a href="#section-7.2.1">7.2.1. Issue identifiers</a></li>
  140.  
  141.     <li><a href="#section-7.2.2">7.2.2. Issues are dictionaries</a></li>
  142.  
  143.     </ul>
  144.  
  145.   </li>
  146.  
  147.   <li><a href="#section-7.3">7.3. The <code class="source">defect_tracker_fix</code> class</a></li>
  148.  
  149.   <li><a href="#section-7.4">7.4. The <code class="source">defect_tracker_filespec</code> class</a></li>
  150.  
  151.   <li><a href="#section-7.5">7.5. The <code class="source">translator</code> class</a>
  152.  
  153.     <ul>
  154.  
  155.     <li><a href="#section-7.5.1">7.5.1. Date translator</a></li>
  156.  
  157.     <li><a href="#section-7.5.2">7.5.2. State translator</a></li>
  158.  
  159.     <li><a href="#section-7.5.3">7.5.3. Text translator</a></li>
  160.  
  161.     <li><a href="#section-7.5.4">7.5.4. User translator</a></li>
  162.  
  163.     </ul>
  164.  
  165.   </li>
  166.  
  167.   <li><a href="#section-7.6">7.6. Cursors</a></li>
  168.  
  169.   </ul>
  170.  
  171. </li>
  172.  
  173. <li><a href="#section-8">8. Configuration</a>
  174.  
  175.   <ul>
  176.  
  177.   <li><a href="#section-8.1">8.1. The configuration generator</a></li>
  178.  
  179.   <li><a href="#section-8.2">8.2. Perforce interface configuration</a></li>
  180.  
  181.   <li><a href="#section-8.3">8.3. Replicator configuration</a></li>
  182.  
  183.   <li><a href="#section-8.4">8.4. Perforce jobspecs</a></li>
  184.  
  185.   <li><a href="#section-8.5">8.5. Adapting the configuration module</a></li>
  186.  
  187.   <li><a href="#section-8.6">8.6. Making your own configurations</a>
  188.  
  189.     <ul>
  190.  
  191.     <li><a href="#section-8.6.1">8.6.1. Steps to making your own configuration</a></li>
  192.  
  193.     <li><a href="#section-8.6.2">8.6.2. Example: custom jobspec and translators</a></li>
  194.  
  195.     </ul>
  196.  
  197.   </li>
  198.  
  199.   </ul>
  200.  
  201. </li>
  202.  
  203. <li><a href="#section-9">9. Building and testing</a></li>
  204.  
  205. <li><a href="#section-10">10. Providing a defect tracker interface to Perforce relations</a></li>
  206.  
  207. <li><a href="#section-11">11. Adapting the manuals</a></li>
  208.  
  209. <li><a href="#section-12">12. Making your work available to the community</a>
  210.  
  211.   <ul>
  212.  
  213.   <li><a href="#section-12.1">12.1. Reporting defects</a></li>
  214.  
  215.   <li><a href="#section-12.2">12.2. Making a contribution</a></li>
  216.  
  217.   </ul>
  218.  
  219. </li>
  220.  
  221. <li><a href="#section-13">13. Changes since previous releases</a>
  222.  
  223.   <ul>
  224.  
  225.   <li><a href="#section-13.1">13.1. Changes since release 1.1.1</a></li>
  226.  
  227.   <li><a href="#section-13.2">13.2. Changes since release 1.1.6</a></li>
  228.  
  229.   <li><a href="#section-13.3">13.3. Changes since release 1.2.1</a></li>
  230.  
  231.   <li><a href="#section-13.4">13.4. Changes since release 1.3.3</a></li>
  232.  
  233.   </ul>
  234.  
  235. </li>
  236.  
  237. <li><a href="#section-A">A. References</a></li>
  238.  
  239. <li><a href="#section-B">B. Document History</a></li>
  240.  
  241. </ul>
  242.  
  243.  
  244. <h2><a id="section-1" name="section-1">1. Introduction</a></h2>
  245.  
  246. <p> This is the Perforce Defect Tracking Integration (<abbr
  247. title="Perforce Defect Tracking Integration">P4DTI</abbr>) Integrator's
  248. Guide.  It explains how to extend the <abbr title="Perforce Defect
  249. Tracking Integration">P4DTI</abbr> to work with defect tracking systems
  250. that aren't supported by the standard distribution, or adapt the <abbr
  251. title="Perforce Defect Tracking Integration">P4DTI</abbr> to work with a
  252. supported defect tracker but in some way that isn't supported. </p>
  253.  
  254. <p> The intended readership is developers adapting or extending the
  255. <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, and
  256. project staff. </p>
  257.  
  258. <p> This manual is not confidential. </p>
  259.  
  260.  
  261. <h3><a id="section-1.1" name="section-1.1">1.1. Kit layout</a></h3>
  262.  
  263. <p> The Integration Kit is a copy of the development sources for the
  264. <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>.  The
  265. directory layout is summarized in the <a
  266. href="http://www.ravenbrook.com/project/p4dti/version/2.2/">index to the kit</a>. </p>
  267.  
  268.  
  269. <h3><a id="section-1.2" name="section-1.2">1.2. Levels of requirement</a></h3>
  270.  
  271. <p> I use some words in a precise way to express the importance of an
  272. instruction. </p>
  273.  
  274. <ul>
  275.  
  276.   <li><p> I say "must" when the instruction is critical.  This means
  277. that the integration will fail if the instruction is not
  278. followed. </p></li>
  279.  
  280.   <li><p> I say "should" when the instruction is essential.  This means
  281. that integration will be of noticeably lower quality than the supported
  282. integrations if the instruction is not followed.  However, it won't
  283. fail. </p></li>
  284.  
  285.   <li><p> I say "may" when the instruction is optional.  This means that
  286. the integration will not suffer much if you don't follow the
  287. instruction. </p></li>
  288.  
  289. </ul>
  290.  
  291.  
  292. <h2><a id="section-2" name="section-2">2. Understanding the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
  293.  
  294. <p> This section gives an overview of the requirements, architecture and
  295. design of the <abbr title="Perforce Defect Tracking
  296. Integration">P4DTI</abbr>, with references to the documents that provide
  297. more detail.  You must have a good overall understanding of the <abbr
  298. title="Perforce Defect Tracking Integration">P4DTI</abbr> in order to
  299. extend or adapt it. </p>
  300.  
  301.  
  302. <h3><a id="section-2.1" name="section-2.1">2.1. Prerequisites</a></h3>
  303.  
  304. <p> This manual assumes you are familiar with the following subjects:
  305. </p>
  306.  
  307. <ul>
  308.  
  309.   <li><p> The jobs subsystem of Perforce, and the relationship between
  310.   jobs, fixes and changelists [<a
  311.   href="http://www.perforce.com/perforce/doc.031/manuals/p4guide/10_jobtrack.html">Perforce
  312.   2003-07-15a, 10</a>]. </p></li>
  313.  
  314.   <li><p> How the <abbr title="Perforce Defect Tracking
  315.   Integration">P4DTI</abbr> works, from the administrator's point of
  316.   view.  I strongly recommend that you download, install, configure and
  317.   run one of the supported integrations, following the <cite>Perforce
  318.   Defect Tracking Integration Administrator's Guide</cite> [<a
  319.   href="../ag/index.html">RB 2000-08-10a</a>], so that
  320.   you know what the administrator has to know and do, where the data is
  321.   stored, what problems can occur. </p></li>
  322.  
  323.   <li><p> How the <abbr title="Perforce Defect Tracking
  324.   Integration">P4DTI</abbr> works, from the user's point of view.  I
  325.   strongly recommend that you try out one of the supported integrations,
  326.   carrying out all the tasks in the <cite>Perforce Defect Tracking
  327.   Integration User's Guide</cite> [<a
  328.   href="../ug/index.html">RB 2000-08-10b</a>], so that
  329.   you know what it's like to use, and what benefit the users
  330.   get. </p></li>
  331.  
  332.   <li><p> The programming language Python.  See the <a
  333.   href="http://www.python.org/">Python web site
  334.   &lt;http://www.python.org/&gt;</a> for downloads and documentation.
  335.   If you're new to Python, try the tutorial [<a
  336.   href="http://www.python.org/doc/current/tut/tut.html">van Rossum
  337.   2000-10-16</a>], or the book <cite>Programming Python</cite> [<a
  338.   href="#ref-Lutz-1996">Lutz 1996</a>]. </p></li>
  339.  
  340. </ul>
  341.  
  342.  
  343. <h3><a id="section-2.2" name="section-2.2">2.2. Requirements overview</a></h3>
  344.  
  345. <p> The five most important requirements are these [<a
  346. href="http://www.ravenbrook.com/project/p4dti/req/#req-1">GDR
  347. 2000-05-24, 1-5</a>]: </p>
  348.  
  349. <ul>
  350.  
  351. <li><p> Defect tracker state is consistent with the state of the product
  352. sources. </p></li>
  353.  
  354. <li><p> The defect tracking integration makes the jobs of the developers
  355. and managers easier (i.e. make it easier for them to produce a quality
  356. product etc.). </p></li>
  357.  
  358. <li><p> It is easy to discover why the product sources are the way they
  359. are, and why they have changed, in terms of the customer
  360. requirements. </p></li>
  361.  
  362. <li><p> The interface that allows Perforce to be integrated with defect
  363. tracking systems is public, documented, and maintained. </p></li>
  364.  
  365. <li><p> The integration provides the ability to ask questions involving
  366. both the defect tracking system and the <abbr title="Source
  367. Configuration Management">SCM</abbr> system. </p></li>
  368.  
  369. </ul>
  370.  
  371. <p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
  372. meets <a
  373. href="http://www.ravenbrook.com/project/p4dti/req/#req-1">requirement
  374. 1</a> and <a
  375. href="http://www.ravenbrook.com/project/p4dti/req/#req-5">requirement
  376. 5</a> by replicating data between the defect tracker and Perforce (see
  377. <a href="#section-2.3">section 2.3</a>).  It meets <a
  378. href="http://www.ravenbrook.com/project/p4dti/req/#req-2">requirement
  379. 2</a> by making it possible for developers to do their routine defect
  380. tracking activity entirely from Perforce (by making the defects
  381. available through Perforce's jobs interface).  It meets <a
  382. href="http://www.ravenbrook.com/project/p4dti/req/#req-3">requirement
  383. 3</a> by supplying a user guide [<a
  384. href="../ug/index.html">RB 2000-08-10b</a>] that
  385. describes a development process in which issues are linked to changes by
  386. making fixes in Perforce.  It meets <a
  387. href="http://www.ravenbrook.com/project/p4dti/req/#req-4">requirement
  388. 4</a> by making the project sources and documents <a
  389. href="http://www.ravenbrook.com/project/p4dti/">available to the
  390. public</a>. </p>
  391.  
  392. <p> See the <cite>Perforce Defect Tracking Integration Project
  393. Requirements</cite> [<a
  394. href="http://www.ravenbrook.com/project/p4dti/req/">GDR 2000-05-24</a>]
  395. for a full and maintained set of requirements and references to their
  396. original sources. </p>
  397.  
  398.  
  399. <h3><a id="section-2.3" name="section-2.3">2.3. Architecture overview</a></h3>
  400.  
  401. <p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
  402. meets these requirements using a replication architecture [<a
  403. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/architecture/">RB 2000-08-10c</a>].
  404. A replicator process repeatedly polls two databases (Perforce and the
  405. defect tracker) and copies entities from one to the other.  This makes
  406. and keep them consistent, to meet <a
  407. href="http://www.ravenbrook.com/project/p4dti/req/#req-1">requirement
  408. 1</a>; it makes them available to users of both systems, to meet <a
  409. href="http://www.ravenbrook.com/project/p4dti/req/#req-2">requirement
  410. 2</a>; and it makes them available for queries combining data from both
  411. systems, to meet <a
  412. href="http://www.ravenbrook.com/project/p4dti/req/#req-5">requirement
  413. 5</a>. </p>
  414.  
  415. <p> The replicator replicates four relations: </p>
  416.  
  417. <ul>
  418.  
  419. <li><p> <b>Issues</b> are replicated from the defect tracker to Perforce
  420. (where they appear as jobs).  Changes to issues and jobs are replicated
  421. in both directions, but the Perforce jobs are considered to be a
  422. subsidiary copy of the real data in the defect tracker.  This means that
  423. when the two databases differ (for example, because they have been
  424. changed simultaneously) the defect tracker is considered to be
  425. definitive. </p></li>
  426.  
  427. <li><p> <b>Changelist descriptions</b> are replicated from Perforce to the
  428. defect tracker. </p></li>
  429.  
  430. <li><p> <b>Fixes</b> (links between issues and changelists) are
  431. replicated in both directions. </p></li>
  432.  
  433. <li> <p> <b>Filespecs</b> (links between issues and files) are replicated in both directions. </p> </li>
  434.  
  435. </ul>
  436.  
  437. <p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
  438. replicates the filespec relation in order to support use cases like
  439. "Associate revisions of documents with task" [<a
  440. href="http://www.ravenbrook.com/project/p4dti/doc/2000-05-03/reqs-and-use-cases/">GDR
  441. 2000-05-03, 6.2</a>] and "Check out copies of revisions of documents
  442. associated with task" [<a
  443. href="http://www.ravenbrook.com/project/p4dti/doc/2000-05-03/reqs-and-use-cases/">GDR
  444. 2000-05-03, 6.3</a>] and to support defect trackers like DevTrack by
  445. TechExcel that provide a revision control interface based on associating
  446. documents with an issue.  However, because the currently supported defect tracker
  447. (Bugzilla) has no such feature, and because alpha and
  448. beta testing showed no demand for use cases involving associating
  449. documents with tasks, we haven't made any use of this relation (for
  450. example, it's not documented in the user's guide).  However, it's there
  451. if you need it for integrating with your defect tracker. </p>
  452.  
  453.  
  454. <h3><a id="section-2.4" name="section-2.4">2.4. Design overview</a></h3>
  455.  
  456. <p> The replicator is designed to be highly independent of both Perforce
  457. and the defect tracker, using public interfaces wherever possible, so
  458. that the integration doesn't have to change frequently to keep up with
  459. the systems it integrates (<a
  460. href="http://www.ravenbrook.com/project/p4dti/req/#req-27">requirement
  461. 27</a>) and the cost of maintenance is low (<a
  462. href="http://www.ravenbrook.com/project/p4dti/req/#req-30">requirement
  463. 30</a>).  It runs as a separate process and uses public protocols to
  464. access both databases.  It doesn't require any special support from
  465. either system (though users benefit if the defect tracker provides an
  466. interface to Perforce fixes; (see <a href="#section-10">section
  467. 10</a>). </p>
  468.  
  469. <p> The replicator is written in the interpreted programming language
  470. Python, a portable, stable, readable and open programming language (to
  471. meet <a
  472. href="http://www.ravenbrook.com/project/p4dti/req/#req-21">requirement
  473. 21</a>, <a
  474. href="http://www.ravenbrook.com/project/p4dti/req/#req-24">requirement
  475. 24</a>, <a
  476. href="http://www.ravenbrook.com/project/p4dti/req/#req-25">requirement
  477. 25</a>, and <a
  478. href="http://www.ravenbrook.com/project/p4dti/req/#req-26">requirement
  479. 26</a>.). </p>
  480.  
  481. <p> <a href="#figure-1">Figure 1</a> below shows the broad outlines of
  482. how the replicator is constructed.  Parts in black are shared by the
  483. integrations with all defect trackers.  The components in red are the
  484. components that you must write in order to integrate with your defect
  485. tracker. </p>
  486.  
  487. <p> If you need to modify any other components to integrate with your
  488. defect tracker, that's a defect in the integration kit.  Please report
  489. it (see <a href="#section-12.1">section 12.1</a>) or make the necessary
  490. modifications and submit them as a contribution (see <a
  491. href="#section-12.2">section 12.2</a>). </p>
  492.  
  493. <div align="center">
  494.  
  495. <p> <a id="figure-1" name="figure-1">Figure 1</a>. Replicator block
  496. diagram </p>
  497.  
  498. <img src="replicator-design.gif" alt="Replicator block diagram"
  499. usemap="#map-1" width="444" height="467" />
  500.  
  501. </div>
  502.  
  503. <map id="map-1" name="map-1">
  504.  
  505. <p> The replicator is divided into these components: </p>
  506.  
  507. <ul>
  508.  
  509. <li><p> <a href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/replicator.py"
  510. shape="rect" coords="187,1,302,65"><code
  511. class="filename">replicator.py</code></a>, a module that runs the
  512. replication algorithm and reports failures by e-mail [<a
  513. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/">GDR
  514. 2000-09-13</a>]. </p></li>
  515.  
  516. <li><p> A defect tracker module, called <code
  517. class="filename">dt_<i>defect_tracker</i>.py</code> (<code
  518. class="filename">dt_abc.py</code> in <a href="#figure-1">figure 1</a>).
  519. This defines a subclass of <code class="filename">defect_tracker</code>.
  520. It is responsible for fetching, translating and updating entities in the
  521. defect tracker database at a high level of abstraction (see <a
  522. href="#section-7" shape="poly"
  523. coords="105,59,171,59,171,79,244,79,244,142,128,142,128,79,105,79">section
  524. 7</a>).  For each new defect tracker, you need to write such a
  525. module. </p></li>
  526.  
  527. <li><p> A defect tracker interface.  This provides a low-level interface
  528. to the defect tracker, allowing entities to be fetched from and stored
  529. in records in the defect tracker's database (see <a href="#section-6"
  530. shape="poly"
  531. coords="47,136,113,136,113,156,186,156,186,219,70,219,70,156,47,156">section
  532. 6</a>).  For each new defect tracker, you need to write such a module.
  533. To avoid the replicator needing any internal state, the defect tracker
  534. interface stores any persistent information needed by the replicator in
  535. the defect tracker's database; see <a href="#section-4" shape="poly"
  536. coords="32,427,113,427,113,442,182,442,182,460,113,460,113,467,32,467">section
  537. 4</a> for the necessary schema extensions. </p></li>
  538.  
  539. <li><p> A configuration generator.  This is responsible for taking the
  540. raw configuration supplied by the <abbr title="Perforce Defect Tracking
  541. Integration">P4DTI</abbr> administrator and building a detailed
  542. configuration suitable for the replicator (see <a
  543. href="#section-8">section 8</a>). </p></li>
  544.  
  545. <li><p> Supporting components, including an interface to Perforce (<a
  546. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/p4.py" shape="rect"
  547. coords="258,79,375,141"><code class="filename">p4.py</code></a>, a
  548. message system, and configuration checking functions. </p></li>
  549.  
  550. </ul>
  551.  
  552. </map>
  553.  
  554.  
  555. <h2><a id="section-3" name="section-3">3. What you need to do</a></h2>
  556.  
  557. <p> This section gives an overview of the work required in adapting an
  558. existing integration or developing a new integration. </p>
  559.  
  560.  
  561.  
  562. <h3><a id="section-3.1" name="section-3.1">3.1. Before you start work</a></h3>
  563.  
  564. <p> Someone might already have developed the integration or adaption
  565. that you plan to work on.  Take a look at the <a
  566. href="http://www.ravenbrook.com/project/p4dti/contrib/"><abbr
  567. title="Perforce Defect Tracking Integration">P4DTI</abbr> contributions
  568. page &lt;http://www.ravenbrook.com/project/p4dti/contrib/&gt;</a>. </p>
  569.  
  570. <p> Someone might be currently be working on the integration or adaption
  571. that you plan to work on.  If so, <a
  572. href="http://www.perforce.com/perforce/support.html">Perforce
  573. support</a> may know about them. </p>
  574.  
  575. <p> The feature you want may in fact be part of the supported <abbr
  576. title="Perforce Defect Tracking Integration">P4DTI</abbr> product and it
  577. is missing from the manuals or the manuals are unclear.  If so, <a
  578. href="http://www.perforce.com/perforce/support.html">Perforce
  579. support</a> can tell you.  And if the manuals are unclear or missing
  580. information, then please submit a defect report (see <a
  581. href="#section-12.1">section 12.1</a>). </p>
  582.  
  583.  
  584. <h3><a id="section-3.2" name="section-3.2">3.2. Getting help</a></h3>
  585.  
  586. <p> The Perforce Defect Tracking Integration Kit is a supported
  587. product. If you have trouble adapting the <abbr title="Perforce Defect
  588. Tracking Integration">P4DTI</abbr> or developing an integration after
  589. following the instructions in here, contact <a
  590. href="http://www.perforce.com/perforce/support.html">Perforce
  591. support</a> for help. </p>
  592.  
  593. <p> <a href="http://www.ravenbrook.com/services/perforce/">Ravenbrook
  594. Limited</a> may be able to develop or consult on adaptions and
  595. extensions to the <abbr title="Perforce Defect Tracking
  596. Integration">P4DTI</abbr>. </p>
  597.  
  598.  
  599. <h3><a id="section-3.3" name="section-3.3">3.3. Adapting an existing integration</a></h3>
  600.  
  601. <p> You may need to adapt the <abbr title="Perforce Defect Tracking
  602. Integration">P4DTI</abbr> to work with a supported defect tracker but in
  603. some way that isn't supported.  For example: </p>
  604.  
  605. <ul>
  606.  
  607. <li> You want more control over which defect tracker issues are
  608. replicated to Perforce. </li>
  609.  
  610. <li> You want to change the names of the fields in Perforce. </li>
  611.  
  612. <li> You want to match up the fields in an unusual way, for example you
  613. have a single field in the defect tracker that ought to be two fields in
  614. Perforce (or vice versa). </li>
  615.  
  616. <li> You want to translate values in a field in a different way. </li>
  617.  
  618. <li> You want to use a locally customized version of Bugzilla. </li>
  619.  
  620. </ul>
  621.  
  622. <p> In these and many similar cases, make the <abbr title="Perforce
  623. Defect Tracking Integration">P4DTI</abbr> do what you want by writing a
  624. "configuration generator" (see <a href="#section-8.6">section
  625. 8.6</a>). </p>
  626.  
  627. <p> But don't skip straight to that section.  At least skim the rest of
  628. the manual.  You'll need to understand many of the details in order to
  629. write a configuration generator, especially how to write translator
  630. classes (see <a href="#section-7.5">section 7.5</a>) and how the
  631. configuration works (see <a href="#section-8">section 8</a>). </p>
  632.  
  633.  
  634. <h3><a id="section-3.4" name="section-3.4">3.4. Developing a new integration</a></h3>
  635.  
  636. <p> Follow these steps to integrate Perforce with a new defect tracker:
  637. </p>
  638.  
  639. <ol>
  640.  
  641.   <li><p> Choose a name for the integration.  This should be the name of
  642.   the defect tracker, for example "Bugzilla".  This name
  643.   (when converted to lower case) must be used as part of the names of
  644.   modules making up the integration (see <a href="#section-7">section
  645.   7</a> and <a href="#section-8">section 8</a>). </p></li>
  646.  
  647.   <li><p> Decide which of the optional features you are going to support
  648.   (see <a href="#section-3.5">section 3.5</a>). </p></li>
  649.  
  650.   <li>
  651.  
  652.   <p> Provide full implementations of these components: </p>
  653.  
  654.   <ol type="a">
  655.  
  656.     <li><p> A documented design for extensions for the defect tracker
  657.     database schema (see <a href="#section-4">section 4</a>); </p></li>
  658.  
  659.     <li><p> A Python interface to the defect tracker (see <a
  660.     href="#section-6">section 6</a>); </p></li>
  661.  
  662.     <li><p> A defect tracker module (see <a href="#section-7">section
  663.     7</a>); </p></li>
  664.  
  665.     <li><p> A configuration generator (see <a href="#section-8">section
  666.     8</a>). </p></li>
  667.  
  668.   </ol>
  669.  
  670.   </li>
  671.  
  672.   <li><p> You should develop and apply tests (both automated and manual)
  673.   of your integration (see <a href="#section-9">section 9</a>). </p>
  674.   </li>
  675.  
  676.   <li><p> You should provide a defect tracker interface to the Perforce
  677.   relations, if possible (see <a href="#section-10">section
  678.   10</a>).</p></li>
  679.  
  680.   <li><p> You must adapt or extend these components: </p>
  681.  
  682.   <ol type="a">
  683.  
  684.     <li><p> The configuration module <a
  685.     href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/config.py"><code
  686.     class="filename">config.py</code></a> (see <a
  687.     href="#section-8.5">section 8.5</a>). </p></li>
  688.  
  689.     <li><p> The Administrator's Guide (see <a href="#section-11">section
  690.     11</a>); </p></li>
  691.  
  692.     <li><p> The User's Guide (see <a href="#section-11">section 11</a>);
  693.     </p></li>
  694.  
  695.   </ol>
  696.  
  697.   <p> All other components are designed to be portable between defect
  698.   trackers.  If your integration cannot be made to work without changing
  699.   the portable components, then there is a defect in the <abbr
  700.   title="Perforce Defect Tracking Integration">P4DTI</abbr> Integration
  701.   Kit.  Please report this (see <a href="#section-12.1">section
  702.   12.1</a>). </p>
  703.  
  704.   </li>
  705.  
  706.   <li><p> Once all the work outlined above is completed and tested to
  707.   your satisfaction, you should make your work available to the
  708.   community so that others can benefit from your efforts (see <a
  709.   href="#section-12.2">section 12.2</a>). </p></li>
  710.  
  711. </ol>
  712.  
  713. <p> I estimate that at least 10 weeks of effort are required to develop,
  714. test, document and release a new integration [<a
  715. href="http://www.ravenbrook.com/project/p4dti/doc/2000-05-30/arch-analysis/#section-2.21.1">GDR
  716. 2000-05-30</a>] </p>
  717.  
  718.  
  719. <h3><a id="section-3.5" name="section-3.5">3.5. Optional features</a></h3>
  720.  
  721. <p> The features in the following list are optional.  You should
  722. implement as many as possible.  Use the <a
  723. href="#defect_tracker.supports"><code
  724. class="source">supports</code></a> method of your defect tracker
  725. interface to specify to the <abbr title="Perforce Defect Tracking
  726. Integration">P4DTI</abbr> the features that you support. </p>
  727.  
  728. <dl>
  729.  
  730.   <dt><a id="feature-fixes" name="feature-fixes">fixes</a></dt>
  731.  
  732.   <dd><p> Replication of fixes between Perforce and the defect tracker,
  733.   and replication of changeslists from Perforce to the defect tracker.
  734.   </p></dd>
  735.  
  736.   <dt><a id="feature-filespecs" name="feature-filespecs">filespecs</a></dt>
  737.  
  738.   <dd><p> Replication of file specifications between Perforce and the
  739.   defect tracker. </p></dd>
  740.  
  741.   <dt><a id="feature-migrate_issues" name="feature-migrate_issues">migrate_issues</a></dt>
  742.  
  743.   <dd><p> Creation of new issues in the defect tracker based on jobs in
  744.   Perforce (during migration). </p></dd>
  745.  
  746.   <dt><a id="feature-new_issues" name="feature-new_issues">new_issues</a></dt>
  747.  
  748.   <dd><p> Creation of new issues in the defect tracker based on jobs in
  749.   Perforce (during normal operation of the <abbr title="Perforce Defect
  750.   Tracking Integration">P4DTI</abbr>). </p></dd>
  751.  
  752.   <dt><a id="feature-new_users" name="feature-new_users">new_users</a></dt>
  753.  
  754.   <dd><p> Creation of new users in the defect tracker based on users in
  755.   Perforce. </p></dd>
  756.  
  757. </dl>
  758.  
  759.  
  760. <h2><a id="section-4" name="section-4">4. Defect tracker database schema extensions</a></h2>
  761.  
  762. <p> You must extend the database schema by adding new fields to the
  763. issue relation (see <a href="#section-4.1">section 4.1</a>), and adding
  764. three new relations: the changelist relation (see <a
  765. href="#section-4.2">section 4.2</a>), the fixes relation (see <a
  766. href="#section-4.3">section 4.3</a>), and the filespecs relation (see <a
  767. href="#section-4.4">section 4.4</a>).  You should add another relation
  768. to the database, to store the replicator state and configuration (see <a
  769. href="#section-4.5">section 4.5</a>).  These schema extensions must be
  770. documented so that users of your integration can implement database
  771. queries and reports that use this data, to meet <a
  772. href="http://www.ravenbrook.com/project/p4dti/req/#req-5">requirement
  773. 5</a>. </p>
  774.  
  775. <p> These relations should be stored in separate tables if possible, to
  776. most easily support queries and reporting using standard database tools.
  777. However, some defect trackers do not support this. </p>
  778.  
  779. <blockquote><p> <i>Example.</i> TeamTrack release 4.5 doesn't support
  780. the addition of tables to its database schema, so the TeamTrack schema
  781. extensions squashed these relations into a single table, using a type
  782. field to distinguish them [<a
  783. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/#section-2.1">GDR
  784. 2000-09-04, 2.1</a>]. </p></blockquote>
  785.  
  786. <p> The design must support multiple replicators replicating from a
  787. single defect tracker, and support a single replicator replicating to
  788. multiple Perforce servers from one defect tracker, in order to meet <a
  789. href="http://www.ravenbrook.com/project/p4dti/req/#req-96">requirement
  790. 96</a>.  To support this, each relation includes a replicator identifier
  791. which identifies the replicator which is handling replication for that
  792. record, and a Perforce server identifier, which identifies the Perforce
  793. server that the record is replicated to. </p>
  794.  
  795. <blockquote><p> <i>Examples.</i> The TeamTrack database schema
  796. extensions [<a
  797. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/">GDR
  798. 2000-09-04</a>] and the Bugzilla database schema extensions [<a
  799. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/bugzilla-p4dti-schema/">NB
  800. 2000-11-14b</a>].  </p></blockquote>
  801.  
  802.  
  803. <h3><a id="section-4.1" name="section-4.1">4.1. Issues</a></h3>
  804.  
  805. <p> The issue relation must be extended with these fields: </p>
  806.  
  807. <table border="1" cellspacing="0" cellpadding="5">
  808.  
  809. <tr valign="top" align="left">
  810.  
  811.   <th>Field contents</th>
  812.  
  813.   <th>Field type</th>
  814.  
  815. </tr>
  816.  
  817. <tr valign="top">
  818.  
  819.   <td>Replicator identifier of the replicator that is in charge of
  820.   replicating this issue, or the empty string or NULL if the issue is
  821.   not replicated.</td>
  822.  
  823.   <td><code class="source">char(32)</code></td>
  824.  
  825. </tr>
  826.  
  827. <tr valign="top">
  828.  
  829.   <td>Server identifier of the Perforce server to which this issue is
  830.   replicated, or the empty string or NULL if the issue is not
  831.   replicated.</td>
  832.  
  833.   <td><code class="source">char(32)</code></td>
  834.  
  835. </tr>
  836.  
  837. <tr valign="top">
  838.  
  839.   <td>Name of Perforce job to which this issue is replicated, or the
  840.   empty string or NULL if the issue is not replicated.</td>
  841.  
  842.   <td><code class="source">char(1024)</code> (or <code
  843.   class="source">varchar(1024)</code> since most jobnames are
  844.   short).</td>
  845.  
  846. </tr>
  847.  
  848. </table>
  849.  
  850. <p> You may add these fields to the defect tracker's issue table, or
  851. you may store them in a separate table and use the issue key to relate
  852. the two tables. </p>
  853.  
  854. <blockquote><p> <i>Examples.</i> The TeamTrack integration added the new
  855. fields to the existing <code class="source">TS_CASES</code> table [<a
  856. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/#section-3.1">GDR
  857. 2000-09-04, 3.1</a>].  The Bugzilla integration creates a table <code
  858. class="source">p4dti_bugs</code> containing the new fields and
  859. associates them with the <code class="source">bugs</code> table using
  860. the <code class="source">bug_id</code> field [<a
  861. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/bugzilla-p4dti-schema/">NB
  862. 2000-11-14b</a>].  </p></blockquote>
  863.  
  864.  
  865. <h3><a id="section-4.2" name="section-4.2">4.2. Changelists</a></h3>
  866.  
  867. <p> (Changelists belong to the <a href="#feature-fixes">fixes</a>
  868. feature.) </p>
  869.  
  870. <p> The changelist relation has these fields: </p>
  871.  
  872. <table border="1" cellspacing="0" cellpadding="5">
  873.  
  874. <tr valign="top" align="left">
  875.  
  876.   <th>Field contents</th>
  877.  
  878.   <th>Field type</th>
  879.  
  880. </tr>
  881.  
  882. <tr valign="top">
  883.  
  884.   <td>Replicator identifier.</td>
  885.  
  886.   <td><code class="source">char(32)</code></td>
  887.  
  888. </tr>
  889.  
  890. <tr valign="top">
  891.  
  892.   <td>Perforce server identifier.</td>
  893.  
  894.   <td><code class="source">char(32)</code></td>
  895.  
  896. </tr>
  897.  
  898. <tr valign="top">
  899.  
  900.   <td>Change number.</td>
  901.  
  902.   <td><code class="source">int</code></td>
  903.  
  904. </tr>
  905.  
  906. <tr valign="top">
  907.  
  908.   <td>User who created the change.</td>
  909.  
  910.   <td>A foreign key reference to the defect tracker's user relation
  911.   giving the user who created or submitted the change.</td>
  912.  
  913. </tr>
  914.  
  915. <tr valign="top">
  916.  
  917.   <td>Change status.</td>
  918.  
  919.   <td>An enumeration with two values: pending or submitted.</td>
  920.  
  921. </tr>
  922.  
  923. <tr valign="top">
  924.  
  925.   <td>Date the change was last modified.</td>
  926.  
  927.   <td>A date and time.</td>
  928.  
  929. </tr>
  930.  
  931. <tr valign="top">
  932.  
  933.   <td>Change description.</td>
  934.  
  935.   <td>Text, unlimited in length.</td>
  936.  
  937. </tr>
  938.  
  939. <tr valign="top">
  940.  
  941.   <td>Client from which the change was submitted.</td>
  942.  
  943.   <td><code class="source">char(1024)</code> (or <code
  944.   class="source">varchar(1024)</code> since most client names are
  945.   short).</td>
  946.  
  947. </tr>
  948.  
  949. </table>
  950.  
  951. <p> The combination of (change number, Perforce server identifier) is
  952. the primary key for this relation: there can only be one change with a
  953. particular number on a Perforce server. </p>
  954.  
  955.  
  956. <h3><a id="section-4.3" name="section-4.3">4.3. Fixes</a></h3>
  957.  
  958. <p> (Fixes belong to the <a href="#feature-fixes">fixes</a> feature.)
  959. </p>
  960.  
  961. <p> The fixes relation has these fields: </p>
  962.  
  963. <table border="1" cellspacing="0" cellpadding="5">
  964.  
  965. <tr valign="top" align="left">
  966.  
  967.   <th>Field contents</th>
  968.  
  969.   <th>Field type</th>
  970.  
  971. </tr>
  972.  
  973. <tr valign="top">
  974.  
  975.   <td>Replicator identifier.</td>
  976.  
  977.   <td><code class="source">char(32)</code></td>
  978.  
  979. </tr>
  980.  
  981. <tr valign="top">
  982.  
  983.   <td>Perforce server identifier.</td>
  984.  
  985.   <td><code class="source">char(32)</code></td>
  986.  
  987. </tr>
  988.  
  989. <tr valign="top">
  990.  
  991.   <td>Issue.</td>
  992.  
  993.   <td>A foreign key reference to the defect tracker's issue relation,
  994.   giving the issue which is fixed by the change.</td>
  995.  
  996. </tr>
  997.  
  998. <tr valign="top">
  999.  
  1000.   <td>Change number</td>
  1001.  
  1002.   <td><code class="source">int</code></td>
  1003.  
  1004. </tr>
  1005.  
  1006. <tr valign="top">
  1007.  
  1008.   <td>Date the fix was last modified.</td>
  1009.  
  1010.   <td>A date and time.</td>
  1011.  
  1012. </tr>
  1013.  
  1014. <tr valign="top">
  1015.  
  1016.   <td>User who created the fix.</td>
  1017.  
  1018.   <td>A foreign key reference to the defect tracker's user relation,
  1019.   giving the user who last modified the fix.</td>
  1020.  
  1021. </tr>
  1022.  
  1023. <tr valign="top">
  1024.  
  1025.   <td>Status the job was/will be fixed to.</td>
  1026.  
  1027.   <td><code class="source">char(1024)</code> (or <code
  1028.   class="source">varchar(1024)</code> since most job statuses are
  1029.   short).</td>
  1030.  
  1031. </tr>
  1032.  
  1033. <tr valign="top">
  1034.  
  1035.   <td>Client from which the fix was made.</td>
  1036.  
  1037.   <td><code class="source">char(1024)</code> (or <code
  1038.   class="source">varchar(1024)</code> since most client names are
  1039.   short).</td>
  1040.  
  1041. </tr>
  1042.  
  1043. </table>
  1044.  
  1045. <p> The combination of (issue, change number, Perforce server
  1046. identifier) is the primary key for this relation: there can only be one
  1047. fix between a change and an issue on a Perforce server. </p>
  1048.  
  1049.  
  1050. <h3><a id="section-4.4" name="section-4.4">4.4. Filespecs</a></h3>
  1051.  
  1052. <p> (Filespecs belong to the <a href="#feature-filespecs">filespecs</a>
  1053. feature.) </p>
  1054.  
  1055. <p> The associated filespecs relation has these fields: </p>
  1056.  
  1057. <table border="1" cellspacing="0" cellpadding="5">
  1058.  
  1059. <tr valign="top" align="left">
  1060.  
  1061.   <th>Field contents</th>
  1062.  
  1063.   <th>Field type</th>
  1064.  
  1065. </tr>
  1066.  
  1067. <tr valign="top">
  1068.  
  1069.   <td>Replicator identifier.</td>
  1070.  
  1071.   <td><code class="source">char(32)</code></td>
  1072.  
  1073. </tr>
  1074.  
  1075. <tr valign="top">
  1076.  
  1077.   <td>Perforce server identifier.</td>
  1078.  
  1079.   <td><code class="source">char(32)</code></td>
  1080.  
  1081. </tr>
  1082.  
  1083. <tr valign="top">
  1084.  
  1085.   <td>Issue.</td>
  1086.  
  1087.   <td>A foreign key reference to the defect tracker's issue relation,
  1088.   giving the issue which is fixed by the change.</td>
  1089.  
  1090. </tr>
  1091.  
  1092. <tr valign="top">
  1093.  
  1094.   <td>Filespec.</td>
  1095.  
  1096.   <td>Text, unlimited in length.</td>
  1097.  
  1098. </tr>
  1099.  
  1100. </table>
  1101.  
  1102.  
  1103. <h3><a id="section-4.5" name="section-4.5">4.5. Replicator configuration and state</a></h3>
  1104.  
  1105. <p> By design, the replicator has no internal state.  This is to make
  1106. the replicator robust against losing a network connection, or the
  1107. machine it's running on crashing in the middle of a replication: when
  1108. the network comes back up or it starts again, it tries the replication
  1109. again [<a
  1110. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/#section-2.10">GDR
  1111. 2000-09-13, 2.9</a>].  This design principle helps to meet <a
  1112. href="http://www.ravenbrook.com/project/p4dti/req/#req-1">requirement 1</a> (consistency between
  1113. databases). </p>
  1114.  
  1115. <p> This means that if you need to store information, such as a record
  1116. of which changes have been replicated (see <a
  1117. href="#section-4.6">section 4.6</a>) you must store it in the defect
  1118. tracker's database. </p>
  1119.  
  1120. <p> The replicator also needs to pass information to the defect tracker,
  1121. to support an interface from the defect tracker to Perforce (see <a
  1122. href="#section-10">section 10</a>).  There are three configuration
  1123. parameters which should be communicated to the defect tracker by storing
  1124. them in a configuration table: <a
  1125. href="../ag/index.html#config-changelist_url"><code
  1126. class="source">changelist_url</code></a>, <a
  1127. href="../ag/index.html#config-job_url"><code
  1128. class="source">job_url</code></a>, and <a
  1129. href="../ag/index.html#config-p4_server_description"><code
  1130. class="source">p4_server_description</code></a>. </p>
  1131.  
  1132.  
  1133. <h3><a id="section-4.6" name="section-4.6">4.6. Discovering what's changed</a></h3>
  1134.  
  1135. <p> The replicator works by repeatedly polling the databases, so you
  1136. must provide a way to tell it which issues have changed since the last
  1137. time it polled.  Here are some strategies: </p>
  1138.  
  1139. <ul>
  1140.  
  1141. <li>
  1142.  
  1143.   <p> If the defect tracker has a changes table which records the
  1144.   history of changes to issues, then store a record number in the
  1145.   replicator state that gives the last record in the changes table that
  1146.   has been replicated.</p>
  1147.  
  1148.   <blockquote><p> <i>Example.</i> The TeamTrack integration used this
  1149.   approach [<a
  1150.   href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/#section-3.5">GDR
  1151.   2000-09-04, 3.5</a>]. </p></blockquote>
  1152.  
  1153. </li>
  1154.  
  1155. <li><p> If the defect tracker has a last modified date field in the
  1156. issue table, store the value of this field at the point when the
  1157. replicator was last replicated.  Then you can fetch the changed issues
  1158. by looking for issues whose last modified date is greater than the last
  1159. replicated date.  This is likely to be less efficient than solution
  1160. 1. </p></li>
  1161.  
  1162. <li><p> Modify the defect tracker so that it supports solution 1 or
  1163. 2. </p></li>
  1164.  
  1165. <li><p> If all else fails, store a "shadow" table of issues, containing
  1166. copies of the issue records as they were when last modified.  Then you
  1167. can find changed issues by finding differing corresponding records.
  1168. This is likely to be very inefficient. </p></li>
  1169.  
  1170. </ul>
  1171.  
  1172.  
  1173. <h3><a id="section-4.7" name="section-4.7">4.7. Distinguishing replicated changes from other changes</a></h3>
  1174.  
  1175. <p> The replicator needs to distinguish the changes it made from changes
  1176. made by other users of the defect tracker.  Otherwise it attempts to
  1177. replicate its own changes back to Perforce.  This won't actually end up
  1178. in an infinite loop of replication, since when it replicates back it
  1179. discovers that there are no changes to be made, and so not actually do
  1180. anything.  However, this double replication gives twice the opportunity
  1181. for conflicts, and hence annoying e-mail messages for the users of the
  1182. <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> (see <a
  1183. href="http://www.ravenbrook.com/project/p4dti/issue/job000016/">Ravenbrook
  1184. issue job000016</a>). </p>
  1185.  
  1186. <p> Here are some strategies: </p>
  1187.  
  1188. <ul>
  1189.  
  1190. <li>
  1191.   <p> Suppose that the defect tracker has separate concepts of "logged
  1192.   in user" and "user who is making the change".  In this case, make a
  1193.   special user to represent the replicator and have the replicator log
  1194.   in as that user.  The replicator's changes show up with logged in user
  1195.   being the replicator user; all other changes need to be
  1196.   replicated. </p>
  1197.  
  1198.   <blockquote><p> <i>Example.</i> The TeamTrack integration used this
  1199.   approach [<a
  1200.   href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/#section-5">GDR
  1201.   2000-09-04, 5</a>]. </p></blockquote>
  1202. </li>
  1203.  
  1204. <li>
  1205.   <p> Store a table listing the changes that were made by the
  1206.   replicator.  Any other changes need to be replicated. </p>
  1207. </li>
  1208.  
  1209. <li><p> If the defect tracker has a last modified date field in the issue
  1210. table, store the value of this field at the point when the replicator
  1211. was last replicated.  Then an issue has been changed by someone else if
  1212. its last modified date differs from the last replicated date. </p></li>
  1213.  
  1214. </ul>
  1215.  
  1216.  
  1217. <h3><a id="section-4.8" name="section-4.8">4.8. Perforce users who don't have licenses in the defect tracker</a></h3>
  1218.  
  1219. <p> The replicator replicates user fields in issues, changelists and
  1220. fixes (for example, the owner of an issue or the user who submitted a
  1221. changelist) by applying a user translation function (see <a
  1222. href="#section-7.5.4">section 7.5.4</a>).  When a defect tracker user
  1223. has no license in Perforce, the translation function can simply use that
  1224. user's defect tracker login name, since Perforce doesn't validate user
  1225. fields in jobs.  But if a Perforce user has no license in the defect
  1226. tracker, the translator needs to do something with them.  For issues
  1227. your defect tracker interface should simply refuse to replicate when a
  1228. Perforce user has no license in the defect tracker.  But you should be
  1229. less strict when replicating fixes and changelists: while it is a
  1230. sensible policy (and required by some defect tracker vendors) to require
  1231. the current owner of a job in Perforce to have a license, it is not
  1232. sensible to require every user in Perforce who ever submitted a
  1233. changelist to have a license in the defect tracker. </p>
  1234.  
  1235. <blockquote><p> <i>Example.</i> The TeamTrack integration mapped unknown
  1236. users in changelists and fixes to the special TeamTrack user 0
  1237. (representing "no user").  When there's an unknown user in an issue, the
  1238. integration rejects the attempt to replicate it by raising an error.
  1239. </p></blockquote>
  1240.  
  1241.  
  1242. <h2><a id="section-5" name="section-5">5. Coding conventions</a></h2>
  1243.  
  1244. <p> This section covers coding conventions followed in the <abbr
  1245. title="Perforce Defect Tracking Integration">P4DTI</abbr>.  You should
  1246. follow these conventions in your adaptions and extensions.  They make
  1247. your code more reliable and easier to debug, and make it easier for
  1248. users to diagnose problems and fix them.  If you contribute your code
  1249. for inclusion in the <abbr title="Perforce Defect Tracking
  1250. Integration">P4DTI</abbr> (see <a href="#section-12.2">section 12.2</a>)
  1251. then it is easier for us to integrate your contribution. </p>
  1252.  
  1253. <blockquote><p> <i>Example.</i> Look at the Bugzilla module, <a
  1254. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  1255. class="filename">dt_bugzilla.py</code></a> for uses of all conventions
  1256. and features covered in this section. </p></blockquote>
  1257.  
  1258.  
  1259. <h3><a id="section-5.1" name="section-5.1">5.1. Messages</a></h3>
  1260.  
  1261. <p> The <a href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/message.py"><code
  1262. class="filename">message.py</code></a> module defines a class of
  1263. messages.  You must use this class when writing messages to the
  1264. replicator's log (see <a href="#section-5.3">section 5.3</a>).  You
  1265. should use this class when raising errors (see <a
  1266. href="#section-5.4">section 5.4</a>). </p>
  1267.  
  1268. <p> You create a message like this: </p>
  1269.  
  1270. <blockquote><pre class="source">
  1271. import message
  1272. id = 123
  1273. text = "Constructed a test message."
  1274. priority = message.DEBUG
  1275. product = "Test"
  1276. msg = message.message(id, text, priority, product)
  1277. </pre></blockquote>
  1278.  
  1279. <p> The four arguments to the constructor are as follows: </p>
  1280.  
  1281. <dl>
  1282.  
  1283.   <dt><code class="source">id</code></dt>
  1284.  
  1285.   <dd><p> A message identifier (an integer).  This is unique among all
  1286.   messages generated by the product. </p></dd>
  1287.  
  1288.   <dt><code class="source">text</code></dt>
  1289.  
  1290.   <dd><p> The text of the message (a string). </p></dd>
  1291.  
  1292.   <dt><code class="source">priority</code></dt>
  1293.  
  1294.   <dd><p> The level of importance of the message.  This must be one of
  1295.   the constants in the following table: </p>
  1296.  
  1297.   <table border="1" cellspacing="0" cellpadding="5">
  1298.  
  1299.     <tr valign="top">
  1300.  
  1301.       <td> <code class="source">message.CRIT</code> </td>
  1302.  
  1303.       <td> A critical error: the replicator stops immediately.  Use this
  1304.       priority for errors in configuration discovered by your
  1305.       configuration generator or by the <a
  1306.       href="#defect_tracker.__init__"><code
  1307.       class="source">__init__</code></a> and <a
  1308.       href="#defect_tracker.init"><code class="source">init</code></a>
  1309.       methods of your defect tracker interface. </td>
  1310.  
  1311.     </tr>
  1312.  
  1313.     <tr valign="top">
  1314.  
  1315.       <td> <code class="source">message.ERR</code> </td>
  1316.  
  1317.       <td> An error.  The replicator can't complete some operation.  Use
  1318.       this priority for errors discovered during replication, such as
  1319.       untranslatable fields or permission failures. </td>
  1320.  
  1321.     </tr>
  1322.  
  1323.     <tr valign="top">
  1324.  
  1325.       <td> <code class="source">message.WARNING</code> </td>
  1326.  
  1327.       <td>
  1328.  
  1329.       <p> A warning.  The replicator can continue, but the administrator
  1330.       may want to take some action. </p>
  1331.  
  1332.       <blockquote><p> <i>Example.</i> The Bugzilla integration issues
  1333.       a warning when it fails to find the Bugzilla configuration
  1334.       parameters in the MySQL database.  The integration can continue
  1335.       (it just can't use the 'emailsuffix' parameter to assist in
  1336.       translating user identities), but it may not do what users
  1337.       expect. </p></blockquote>
  1338.  
  1339.       </td>
  1340.  
  1341.     </tr>
  1342.  
  1343.     <tr valign="top">
  1344.  
  1345.       <td> <code class="source">message.NOTICE</code> </td>
  1346.  
  1347.       <td>
  1348.  
  1349.       <p> A significant but expected condition. </p>
  1350.  
  1351.       <blockquote><p> <i>Example.</i> The replicator uses this priority
  1352.       when it has to overwrite a Perforce job with a defect tracker
  1353.       issue.  This is the correct thing to do, and is the documented
  1354.       behaviour [<a
  1355.       href="../ug/index.html#section-2.2">UG, 2.2</a>]
  1356.       but it is still a significant event.  </p></blockquote>
  1357.  
  1358.       </td>
  1359.  
  1360.     </tr>
  1361.  
  1362.     <tr valign="top">
  1363.  
  1364.       <td> <code class="source">message.INFO</code> </td>
  1365.  
  1366.       <td> For information only. </td>
  1367.  
  1368.     </tr>
  1369.  
  1370.     <tr valign="top">
  1371.  
  1372.       <td> <code class="source">message.DEBUG</code> </td>
  1373.  
  1374.       <td> Unlikely to be useful except for debugging. </td>
  1375.  
  1376.     </tr>
  1377.  
  1378.   </table>
  1379.  
  1380.   </dd>
  1381.  
  1382.   <dt><code class="source">product</code></dt>
  1383.  
  1384.   <dd><p> The name of software product which generated the message.  For
  1385.   the supported <abbr title="Perforce Defect Tracking
  1386.   Integration">P4DTI</abbr>, this must be <code
  1387.   class="source">"P4DTI"</code>. </p></dd>
  1388.  
  1389. </dl>
  1390.  
  1391. <p> You can format a message as text by converting the message object to
  1392. a string: </p>
  1393.  
  1394. <blockquote><samp class="source">
  1395. &gt;&gt;&gt; str(msg) <br />
  1396. "(Test-123X)  Constructed a test message."
  1397. </samp></blockquote>
  1398.  
  1399. <p> Note that a check digit has been appended to the message identifier.
  1400. (The check digit uses a mod-11 algorithm similar to that used in <abbr
  1401. title="International Standard Book Number">ISBNs</abbr> [<a title="ISO
  1402. 2108: International standard book number (ISBN)"
  1403. href="#ref-ISO-2108">ISO 2108</a>], so the check digit can be 0-9 or X.)
  1404. The idea of the check digit is so that <a
  1405. href="http://www.perforce.com/perforce/support.html">Perforce
  1406. support</a> can ask users for the message identifier of the error that
  1407. they are reporting.  The check digit makes it very likely that if the
  1408. error is misreported or misheard the mistake is detected. </p>
  1409.  
  1410. <p> You can wrap a message to some number of columns by calling its
  1411. <code class="source">wrap</code> method: </p>
  1412.  
  1413. <blockquote><samp class="source">
  1414. &gt;&gt;&gt; print msg.wrap(25) <br />
  1415. (Test-123X)  Constructed <br />
  1416. a test message.
  1417. </samp></blockquote>
  1418.  
  1419.  
  1420. <h3><a id="section-5.2" name="section-5.2">5.2. Message catalogs</a></h3>
  1421.  
  1422. <p> You may create each message when you need it, but you should use a
  1423. message catalog.  A catalog helps you keep message identifiers distinct
  1424. and internationalizes your code. </p>
  1425.  
  1426. <p> A message catalog is a dictionary that maps message identifier to a
  1427. tuple of two elements: the message priority, and a format string that
  1428. can be used to build the message text.  For example: </p>
  1429.  
  1430. <blockquote><pre class="source">
  1431. # Test catalog in English
  1432. test_en_catalog = {
  1433.     123: (message.DEBUG, "Constructed a test message."),
  1434.     124: (message.CRIT, "Couldn't connect to defect tracker on host '%s'."),
  1435.     125: (message.ERR, "User '%s' has no permission to edit issue '%s'."),
  1436.     126: (message.INFO, "Replicated issue %d."),
  1437.     # ...
  1438. }
  1439. </pre></blockquote>
  1440.  
  1441. <p> Note that a message catalog must not have an entry for message id 0.
  1442. That's reserved for errors from the catalog implementation. </p>
  1443.  
  1444. <p> Once you have a message catalog for a product, you should build a
  1445. message factory that dispenses messages from that catalog, like this:
  1446. </p>
  1447.  
  1448. <blockquote><pre class="source">
  1449. import message
  1450. product = "Test"
  1451. factory = message.catalog_factory(test_en_catalog, product)
  1452. </pre></blockquote>
  1453.  
  1454. <p> Now you can construct a message by calling the factory's <code
  1455. class="source">new</code> method and passing the message identifier,
  1456. and the arguments for the format string: </p>
  1457.  
  1458. <blockquote><pre class="source">
  1459. msg1 = factory.new(124, 'dt.ravenbrook.com')
  1460. msg2 = factory.new(125, ('gdr', 'BUG00123'))
  1461. </pre></blockquote>
  1462.  
  1463. <p> See the <a
  1464. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/catalog.py"><code
  1465. class="filename">catalog.py</code></a> module for the <abbr
  1466. title="Perforce Defect Tracking Integration">P4DTI</abbr> catalog and
  1467. message factory. </p>
  1468.  
  1469.  
  1470. <h3><a id="section-5.3" name="section-5.3">5.3. Logging</a></h3>
  1471.  
  1472. <p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
  1473. logs its progress and errors by creating messages (see <a
  1474. href="#section-5.1">section 5.1</a>) and sending them to a "logger":
  1475. that is, an instance of the logger class defined by the <a
  1476. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/logger.py"><code
  1477. class="filename">logger.py</code></a> module. </p>
  1478.  
  1479. <p> The logger module defines classes for logging to files, to standard
  1480. output, and to the system log on Unix.  The <code
  1481. class="source">multi_logger</code> class directs a single message to
  1482. several loggers. Each logger class takes a priority argument on
  1483. instantiation: only messages with this priority, or a higher priority,
  1484. appear in the log. </p>
  1485.  
  1486. <p> You should log as many debugging messages as you like (by default
  1487. the <a
  1488. href="../ag/index.html#config-log_level"><code
  1489. class="source">log_level</code></a> configuration parameter is <code
  1490. class="source">message.INFO</code> so these messages won't appear).  You
  1491. should log informational messages sparingly, and only when you actually
  1492. make a change in a database.  You should not log error messages, but
  1493. should raise them as exceptions instead (see <a
  1494. href="#section-5.4">section 5.4</a>); the replicator logs them for you
  1495. when it catches them. </p>
  1496.  
  1497. <p> To add a message to a log, create a message object (see <a
  1498. href="#section-5.1">section 5.1</a>) and pass it to the logger's
  1499. <code class="source">log</code> message: </p>
  1500.  
  1501. <blockquote><pre class="source">
  1502. import logger
  1503. # Log messages of priority INFO and higher to test.log:
  1504. logger_object = logger.file_logger("test.log", message.INFO)
  1505. msg = factory.new(126, issue_id)
  1506. logger_object.log(msg)
  1507. </pre></blockquote>
  1508.  
  1509. <p> The configuration generator (see <a href="#section-8">section 8</a>)
  1510. must construct a logger object for use by the replicator.  The same
  1511. logger object should be used by the defect tracker module (see <a
  1512. href="#section-7">section 7</a>) as well, so that all messages are
  1513. collected in the same place.  You must allow the <abbr title="Perforce
  1514. Defect Tracking Integration">P4DTI</abbr> administrator to control the
  1515. volume of log messages by setting the <a
  1516. href="../ag/index.html#config-log_level"><code
  1517. class="source">log_level</code></a> configuration parameter. </p>
  1518.  
  1519.  
  1520. <h3><a id="section-5.4" name="section-5.4">5.4. Errors</a></h3>
  1521.  
  1522. <p> In the <abbr title="Perforce Defect Tracking
  1523. Integration">P4DTI</abbr>, errors are indicated by raising a Python
  1524. exception, not by returning an exceptional value. </p>
  1525.  
  1526. <p> Raise an error using a string as the exception object, and a message
  1527. object (see <a href="#section-5.1">section 5.1</a>) as the message.  For
  1528. example: </p>
  1529.  
  1530. <blockquote><pre class="source">
  1531. error = "Example error"
  1532. # ...
  1533. raise error, factory.new(124, 'dt.ravenbrook.com')
  1534. </pre></blockquote>
  1535.  
  1536. <p> It doesn't make any difference what priority you give to the
  1537. message, but it is conventional to use <code
  1538. class="source">message.CRIT</code> when the replicator stops (for
  1539. example, configuration errors), and <code
  1540. class="source">message.ERR</code> when the replicator continues (for
  1541. example, untranslatable fields or permission failures). </p>
  1542.  
  1543.  
  1544.  
  1545. <h3><a id="section-5.5" name="section-5.5">5.5. Source code layout</a></h3>
  1546.  
  1547. <p> You should include in each file of source code: </p>
  1548.  
  1549. <ol>
  1550.  
  1551.   <li><p> The author. </p></li>
  1552.  
  1553.   <li><p> An introduction explaining what the file is intended to
  1554.   achieve: for example, which requirements does it help to meet?
  1555.   </p></li>
  1556.  
  1557.   <li><p> A references section listing the sources you've used in
  1558.   preparing the code and which other people need to read in order to
  1559.   understand it.  You should certainly refer to the appropriate sections
  1560.   in this manual. </p></li>
  1561.  
  1562.   <li><p> A history section listing the changes made to the code, with
  1563.   the date and the person who changed it. </p></li>
  1564.  
  1565.   <li><p> A statement of copyright. </p></li>
  1566.  
  1567.   <li><p> A license giving people permission to copy the file under
  1568.   certain conditions (or denying them permission if that's what you
  1569.   intend). </p></li>
  1570.  
  1571. </ol>
  1572.  
  1573. <blockquote><p> <i>Example.</i> The <a
  1574. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/logger.py"><code
  1575. class="filename">logger.py</code></a> module displays all these
  1576. features. </p></blockquote>
  1577.  
  1578.  
  1579. <h3><a id="section-5.6" name="section-5.6">5.6. Making changes</a></h3>
  1580.  
  1581. <p> If you make a change to the <abbr title="Perforce Defect Tracking
  1582. Interface">P4DTI</abbr> that you want to contribute to the project (see
  1583. <a href="#section-12.2">section 12.2</a>), you should follow the rules
  1584. in this section.  The reason for this is that if we accept your
  1585. contribution, we'll merge it into our product sources.  It must be
  1586. possible to carry out this merge reliably and without introducing
  1587. errors.  That means being able to consider each change separately,
  1588. evaluate it and make a decision about how to merge it. </p>
  1589.  
  1590. <p> To enable us to do so, follow the following rules: </p>
  1591.  
  1592. <ol>
  1593.  
  1594.   <li><p> Don't delete stuff.  Comment it out or skip it. </p></li>
  1595.  
  1596.   <li><p> Don't fiddle with the formatting of code or comments.  It
  1597.   creates bogus conflicts that create extra work when merging. </p></li>
  1598.  
  1599.   <li><p> Add comments explaining why a change was made.  Sign the
  1600.   comments with your name and the date.  Explain why you had to make the
  1601.   change.  Refer to defect reports when fixing them. </p></li>
  1602.  
  1603. </ol>
  1604.  
  1605.  
  1606. <h2><a id="section-6" name="section-6">6. The Python interface to the defect tracker</a></h2>
  1607.  
  1608. <p> You'll need a way for Python to read and write defect tracking
  1609. records.  If the defect tracker has an <abbr title="Application
  1610. Programmer Interface">API</abbr> of some sort, you'll need to use that;
  1611. if not, you'll have to read and write the database directly, using one
  1612. of the Python database interfaces.  Your defect tracker interface needs
  1613. to support these kinds of operations: </p>
  1614.  
  1615. <ul>
  1616.  
  1617.   <li><p> Get an issue record. </p></li>
  1618.  
  1619.   <li><p> Update an issue record. </p></li>
  1620.  
  1621.   <li><p> Create a new issue record (if you support the <a
  1622.   href="#feature-migrate_issues">migrate_issues</a> or <a
  1623.   href="#feature-new_issues">new_issues</a> features). </p></li>
  1624.  
  1625.   <li><p> Get all the issues needing replication. </p></li>
  1626.  
  1627.   <li><p> Get all the fixes for an issue (if you support the <a
  1628.   href="#feature-fixes">fixes</a> feature). </p></li>
  1629.  
  1630.   <li><p> Add/update/delete a fix (if you support the <a
  1631.   href="#feature-fixes">fixes</a> feature). </p></li>
  1632.  
  1633.   <li><p> Create a table. </p></li>
  1634.  
  1635.   <li><p> Add a field to a table. </p></li>
  1636.  
  1637.   <li><p> Get a list of the fields that make up the issue relation,
  1638.   together with the field types, lengths, legal values, etc. </p></li>
  1639.  
  1640.   <li><p> Get a list of users, with names, userids, e-mail
  1641.   addresses. </p></li>
  1642.  
  1643.   <li><p> Add a new user (if you support the <a
  1644.   href="#feature-new_users">new_users</a> feature). </p></li>
  1645.  
  1646. </ul>
  1647.  
  1648. <p> I can't give you a complete or precise list of operations here;
  1649. you'll have to see what's required as you implement your schema
  1650. extensions (see <a href="#section-4">section 4</a>) and defect tracker
  1651. module (see <a href="#section-7">section 7</a>). </p>
  1652.  
  1653. <blockquote><p> <i>Example.</i> The TeamTrack integration used the
  1654. TeamShare <abbr title="Application Programmer Interface">API</abbr> to
  1655. connect to the defect tracker, because the <abbr title="Application
  1656. Programmer Interface">API</abbr> provides methods that apply
  1657. TeamTrack's privilege system and database validation.  The integration
  1658. used a Python extension module that provided an interface to the parts
  1659. of the TeamShare <abbr title="Application Programmer
  1660. Interface">API</abbr> that it needed (only a small part of the whole
  1661. <abbr title="Application Programmer Interface">API</abbr>, as it
  1662. happened).  See the design of the interface to Teamtrack [<a
  1663. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/python-teamtrack-interface/">GDR
  1664. 2000-08-08</a>].  </p></blockquote>
  1665.  
  1666. <blockquote><p> <i>Example.</i> Bugzilla has no <abbr title="Application
  1667. Programmer Interface">API</abbr>: you have to understand the Bugzilla
  1668. database schema [<a
  1669. href="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">NB 2000-11-14a</a>]
  1670. and connect directly to the MySQL database.  The Bugzilla integration
  1671. uses a wrapper module that encapsulates the direct database operations
  1672. as defect tracker oriented functions like <code
  1673. class="source">update_bug</code>.  See <a
  1674. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/bugzilla.py"><code
  1675. class="filename">bugzilla.py</code></a> and its design [<a
  1676. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/python-bugzilla-interface/">NB
  1677. 2000-11-14c</a>]. </p></blockquote>
  1678.  
  1679.  
  1680. <h2><a id="section-7" name="section-7">7. The defect tracker module</a></h2>
  1681.  
  1682. <p> You must create a module called <code
  1683. class="filename">dt_<i>defect_tracker</i>.py</code> (where <code
  1684. class="filename"><i>defect_tracker</i></code> is the lower-case form of
  1685. the name your chose for your defect tracker (see <a
  1686. href="#section-3">section 3</a>)) that implements these classes: </p>
  1687.  
  1688. <ol>
  1689.  
  1690.   <li><p> The defect tracker interface itself: a subclass of <code
  1691.   class="source">dt_interface.defect_tracker</code> (see <a
  1692.   href="#section-7.1">section 7.1</a>). </p></li>
  1693.  
  1694.   <li><p> Defect tracker issue: a subclass of <code
  1695.   class="source">dt_interface.defect_tracker_issue</code> (see <a
  1696.   href="#section-7.2">section 7.2</a>). </p></li>
  1697.  
  1698.   <li><p> If you support the <a href="#feature-fixes">fixes</a> feature,
  1699.   defect tracker fix: a subclass of <code
  1700.   class="source">dt_interface.defect_tracker_fix</code> (see <a
  1701.   href="#section-7.3">section 7.3</a>). </p></li>
  1702.  
  1703.   <li><p> If you support the <a href="#feature-filespecs">filespecs</a>
  1704.   feature, defect tracker filespec: a subclass of <code
  1705.   class="source">dt_interface.defect_tracker_filespec</code> (see <a
  1706.   href="#section-7.4">section 7.4</a>). </p></li>
  1707.  
  1708.   <li><p> A translator between dates in the defect tracker and Perforce:
  1709.   a subclass of <code class="source">translator.translator</code> (see
  1710.   <a href="#section-7.5.1">section 7.5.1</a>). </p></li>
  1711.  
  1712.   <li><p> A translator between multi-line text fields in the defect
  1713.   tracker and Perforce: a subclass of <code
  1714.   class="source">translator.translator</code> (see <a
  1715.   href="#section-7.5.3">section 7.5.3</a>). </p></li>
  1716.  
  1717.   <li><p> A translator between users in the defect tracker and Perforce:
  1718.   a subclass of <code class="source">translator.user_translator</code>
  1719.   (see <a href="#section-7.5.4">section 7.5.4</a>). </p></li>
  1720.  
  1721.   <li><p> Any other translator classes that are needed to translate
  1722.   fields in the issue relation (see <a href="#section-7.5">section
  1723.   7.5</a>). </p></li>
  1724.  
  1725. </ol>
  1726.  
  1727. <blockquote><p> <i>Example.</i> The Bugzilla module, <a
  1728. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  1729. class="filename">dt_bugzilla.py</code></a>. </p></blockquote>
  1730.  
  1731.  
  1732. <h3><a id="section-7.1" name="section-7.1">7.1. The <code class="source">dt_interface.defect_tracker</code> class</a></h3>
  1733.  
  1734. <p> A subclass of <code
  1735. class="source">dt_interface.defect_tracker</code> implements the
  1736. replicator's interface to a defect tracker. </p>
  1737.  
  1738. <blockquote><p> <i>Example.</i> The <a
  1739. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  1740. class="source">dt_bugzilla.py</code></a> module defines a class <code
  1741. class="source">dt_bugzilla</code>. </p></blockquote>
  1742.  
  1743. <p> A subclass of <code
  1744. class="source">dt_interface.defect_tracker</code> must define the
  1745. following methods: </p>
  1746.  
  1747.  
  1748. <h4> <a id="defect_tracker.__init__" name="defect_tracker.__init__"><code class="source">__init__(self, config)</code></a> </h4>
  1749.  
  1750. <p> This is called when the defect tracker object is created.  The <code
  1751. class="source">config</code> argument is an object whose attributes are
  1752. the configuration parameters for the defect tracker.  See <a
  1753. href="#section-8">section 8</a> for the details of how configuration
  1754. parameters end up in this object. </p>
  1755.  
  1756. <p> This method should check that all configuration parameters are
  1757. supplied and have valid values.  Use the methods in <code
  1758. class="filename"><a
  1759. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/check_config.py">check_config.py</a></code>
  1760. for basic checks. </p>
  1761.  
  1762. <p> The required parameters should certainly include <a
  1763. href="../ag/index.html#config-changelist_url"><code
  1764. class="source">changelist_url</code></a>, <a
  1765. href="../ag/index.html#config-job_url"><code
  1766. class="source">job_url</code></a>, <a
  1767. href="../ag/index.html#config-p4_server_description"><code
  1768. class="source">p4_server_description</code></a>, <a
  1769. href="../ag/index.html#config-rid"><code
  1770. class="source">rid</code></a>, <a
  1771. href="../ag/index.html#config-sid"><code
  1772. class="source">sid</code></a>, and <a
  1773. href="../ag/index.html#config-start_date"><code
  1774. class="source">start_date</code></a>, but may include others, either
  1775. supplied by the <abbr title="Perforce Defect Tracking
  1776. Integration">P4DTI</abbr> administrator in <a
  1777. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/config.py"><code
  1778. class="filename">config.py</code></a> or generated by the configuration
  1779. generator. </p>
  1780.  
  1781.  
  1782. <h4> <a id="defect_tracker.add_replicator_user" name="defect_tracker.add_replicator_user"><code class="source">add_replicator_user(self)</code></a> </h4>
  1783.  
  1784. <p> (The <code class="source">add_replicator_user</code> method
  1785. belongs to the <a href="#feature-new_users">new_users</a> feature.)
  1786. </p>
  1787.  
  1788. <p> This method is called during migration from Perforce to request
  1789. that the distinguished replicator user be added to the defect tracker.
  1790. The e-mail address of this user is defined by the <a
  1791. href="../ag/index.html#config-replicator_address"><code
  1792. class="source">replicator_address</code></a> configuration
  1793. parameter). </p>
  1794.  
  1795. <p> If there is already a user in the defect tracker with this e-mail
  1796. address, then do nothing.  Return the userid of that user. </p>
  1797.  
  1798. <p> If there is no such user, then if possible add a user to the
  1799. defect tracker who will in future be mapped to the replicator's
  1800. Perforce user (<a href="../ag/index.html#config-p4_user"><code
  1801. class="source">p4_user</code></a>) by your user translator (<a
  1802. href="#section-7.5.4">section 7.5.4</a>).  Return the userid of the
  1803. new user. </p>
  1804.  
  1805. <p> If it's not possible to add such a user, return <code
  1806. class="source">None</code>. </p>
  1807.  
  1808. <p> This method is optional.  You need not provide it if you don't
  1809. support migration of users from Perforce. </p>
  1810.  
  1811.  
  1812. <h4> <a id="defect_tracker.add_user" name="defect_tracker.add_user"><code class="source">add_user(self, p4_user, email, fullname)</code></a> </h4>
  1813.  
  1814. <p> (The <code class="source">add_user</code> method belongs to the <a
  1815. href="#feature-new_users">new_users</a> feature.) </p>
  1816.  
  1817. <p> This method is called during migration from Perforce to request that
  1818. a user be added to the defect tracker.  The <code
  1819. class="source">p4_user</code> argument is the userid in Perforce; the
  1820. <code class="source">email</code> argument is the user's e-mail address,
  1821. and the <code class="source">fullname</code> argument is the user's full
  1822. name. </p>
  1823.  
  1824. <p> If there is already a user in the defect tracker who is mapped to
  1825. this Perforce user by your user translator (<a
  1826. href="#section-7.5.4">section 7.5.4</a>), then do nothing.  Return the
  1827. userid of that user. </p>
  1828.  
  1829. <p> If there is no such user, then if possible add a user to the defect
  1830. tracker who will in future be mapped to the this Perforce user by your
  1831. user translator (<a href="#section-7.5.4">section 7.5.4</a>).  Return
  1832. the userid of the new user. </p>
  1833.  
  1834. <p> If it's not possible to add such a user, return <code
  1835. class="source">None</code>. </p>
  1836.  
  1837. <p> This method is optional.  You need not provide it if you don't
  1838. support migration of users from Perforce. </p>
  1839.  
  1840.  
  1841. <h4> <a id="defect_tracker.all_issues" name="defect_tracker.all_issues"><code class="source">all_issues(self)</code></a> </h4>
  1842.  
  1843. <p> Return a cursor (see <a href="#section-7.6">section 7.6</a>) that
  1844. fetches all defect tracking issues that either (a) are replicated by this
  1845. replicator or (b) are not replicated and have been modified since the
  1846. starting point for replication (that is, the date given by the <abbr
  1847. title="Perforce Defect Tracking Integration">P4DTI</abbr>
  1848. administrator in the <a
  1849. href="../ag/index.html#config-start_date"><code
  1850. class="source">start_date</code></a> parameter). </p>
  1851.  
  1852. <p> Include in the cursor: </p>
  1853.  
  1854. <ul>
  1855.  
  1856.   <li><p> Issues replicated by this replicator (that is, the replicator
  1857.   identifier for those issues matches the <a
  1858.   href="../ag/index.html#config-rid"><code
  1859.   class="source">rid</code></a> configuration parameter); </p></li>
  1860.  
  1861.   <li><p> Issues not replicated by any replicator (that is, the
  1862.   replicator identifier for those issues is blank) and changed since the
  1863.   start date. </p></li>
  1864.  
  1865. </ul>
  1866.  
  1867. <p> Omit from the cursor: </p>
  1868.  
  1869. <ul>
  1870.  
  1871.   <li><p> Issues replicated by a different replicator (that is, the
  1872.   replicator identifier for those issues differs from the <a
  1873.   href="../ag/index.html#config-rid"><code
  1874.   class="source">rid</code></a> configuration parameter); </p></li>
  1875.  
  1876.   <li><p> Issues not replicated by any replicator and unchanged since
  1877.   the start date. </p></li>
  1878.  
  1879. </ul>
  1880.  
  1881. <p> Each element fetched by the returned cursor must belong to your
  1882. subclass of the <code
  1883. class="source">dt_interface.defect_tracker_issue</code> class (see <a
  1884. href="#section-7.2">section 7.2</a>). </p>
  1885.  
  1886.  
  1887. <h4> <a id="defect_tracker.changed_entities" name="defect_tracker.changed_entities"><code class="source">changed_entities(self)</code></a> </h4>
  1888.  
  1889. <p> This method is called at the start of each replication cycle to
  1890. determine what work there is to do.  The method <a
  1891. href="#defect_tracker.poll_start"><code
  1892. class="source">poll_start</code></a> is called just before this.</p>
  1893.  
  1894. <p> It must return a tuple of three elements: </p>
  1895.  
  1896. <ol>
  1897.  
  1898.   <li><p> A cursor (see <a href="#section-7.6">section 7.6</a>) that
  1899.   fetches the defect tracking issues that require replication. </p>
  1900.  
  1901.   <p> Each element fetched by the returned cursor must belong to your
  1902.   subclass of the <code
  1903.   class="source">dt_interface.defect_tracker_issue</code> class (see <a
  1904.   href="#section-7.2">section 7.2</a>). </p>
  1905.  
  1906.   <p> Include in the cursor: </p>
  1907.  
  1908.   <ul>
  1909.  
  1910.     <li><p> Issues replicated by this replicator (that is, the
  1911.     replicator identifier for those issues matches the <a
  1912.     href="../ag/index.html#config-rid"><code
  1913.     class="source">rid</code></a> configuration parameter); </p></li>
  1914.  
  1915.     <li><p> Issues not replicated by any replicator (that is, the
  1916.     replicator identifier for those issues is blank).  The replicator
  1917.     considers these issues as candidates for replication. </p></li>
  1918.  
  1919.   </ul>
  1920.  
  1921.   <p> Omit from the cursor: </p>
  1922.  
  1923.   <ul>
  1924.  
  1925.     <li><p> Issues replicated by a different replicator (that is, the
  1926.     replicator identifier for those issues differs from the <a
  1927.     href="../ag/index.html#config-rid"><code
  1928.     class="source">rid</code></a> configuration parameter). </p></li>
  1929.  
  1930.     <li><p> Issues known to be up to date with Perforce; either because
  1931.     they are unchanged since they were last replicated, or because they
  1932.     have only been changed by the replicator (see <a
  1933.     href="#section-4.6">section 4.6</a> and <a
  1934.     href="#section-4.7">section 4.7</a>). </p></li>
  1935.  
  1936.   </ul></li>
  1937.  
  1938.   <li><p> The empty list <code class="source">[ ]</code>.  (This is for
  1939.   symmetry with the Perforce interface, which returns a list of
  1940.   changelists.  Since changelists are not editable in the defect
  1941.   tracker, there's nothing that can be returned here, hence the empty
  1942.   list.) </p></li>
  1943.  
  1944.   <li><p> A marker.  This must be some token that identifies what has
  1945.   been done on this poll.  At the end of the replication cycle it is
  1946.   passed to <a href="#defect_tracker.mark_changes_done"><code
  1947.   class="source">mark_changes_done</code></a>. </p>
  1948.  
  1949.   <blockquote><p> <i>Example.</i> The TeamTrack integration used the
  1950.   record number of the last record in the <code
  1951.   class="source">TS_CHANGES</code> table that the replicator looked at
  1952.   as the marker indicating what it's done.  See the design [<a
  1953.   href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/#section-3.5">GDR
  1954.   2000-09-04, 3.5</a>]. </p></blockquote></li>
  1955.  
  1956. </ol>
  1957.  
  1958. <p> This method must not record that the issues it returns have been
  1959. considered for replication or replicated.  The replicator can encounter
  1960. an error during the course of replication that prevents it from making
  1961. any progress (Perforce can go down, the defect tracker can go down, the
  1962. replicator can crash).  When the system comes back up, the replicator
  1963. must re-consider these issues and possibly replicate them again.  This
  1964. helps keep the databases consistent (<a
  1965. href="http://www.ravenbrook.com/project/p4dti/req/#req-1">requirement
  1966. 1</a>) and is consistent with the design principle that the replicator
  1967. must have no internal state (see <a href="#section-4.5">section
  1968. 4.5</a>). </p>
  1969.  
  1970. <p> Recording that issues have been replicated must be left for the end
  1971. of each replication cycle, when the marker (the third item in the tuple)
  1972. is passed to <a href="#defect_tracker.mark_changes_done"><code
  1973. class="source">mark_changes_done</code></a>.</p>
  1974.  
  1975.  
  1976. <h4> <a id="defect_tracker.init" name="defect_tracker.init"><code class="source">init(self)</code></a> </h4>
  1977.  
  1978. <p> This method is called each time the replicator starts. </p>
  1979.  
  1980. <p> The method must initialize the defect tracking database so that it
  1981. is ready to start replication.  The tables and fields in your schema
  1982. extensions (see <a href="#section-4">section 4</a>) must be added if they
  1983. are not yet present. </p>
  1984.  
  1985.  
  1986. <h4> <a id="defect_tracker.issue" name="defect_tracker.issue"><code class="source">issue(self, issue_id)</code></a> </h4>
  1987.  
  1988. <p> Return the defect tracking issue identified by the <code
  1989. class="source">issue_id</code> argument, or None if there is no such
  1990. issue.  The returned issue (if any) must belong to your subclass of the
  1991. <code class="source">dt_interface.defect_tracker_issue</code> class (see <a
  1992. href="#section-7.2">section 7.2</a>). </p>
  1993.  
  1994. <p> The <code class="source">issue_id</code> argument is a string
  1995. identifying the issue (see <a href="#section-7.2.1">section 7.2.1</a>). </p>
  1996.  
  1997.  
  1998. <h4> <a id="defect_tracker.mark_changes_done" name="defect_tracker.mark_changes_done"><code class="source">mark_changes_done(self, marker)</code></a> </h4>
  1999.  
  2000. <p> This method is called at the end of each replication cycle, when all
  2001. issues have been replicated. </p>
  2002.  
  2003. <p> The <code class="source">marker</code> argument is the third item in
  2004. the tuple returned by the <a
  2005. href="#defect_tracker.changed_entities"><code
  2006. class="source">changed_entities</code></a> method at the start of the
  2007. replication cycle. </p>
  2008.  
  2009. <p> This method must now record that it has considered all changes up to
  2010. the start of this replication cycle and replicated them successfully, so
  2011. that at the next replication cycle it can ignore these changes and
  2012. consider a new set of changes (see <a href="#section-4.6">section
  2013. 4.6</a>). </p>
  2014.  
  2015.  
  2016. <h4> <a id="defect_tracker.new_issue" name="defect_tracker.new_issue"><code class="source">new_issue(self, dict, jobname)</code></a> </h4>
  2017.  
  2018. <p> (The <code class="source">new_issue</code> method belongs to the <a
  2019. href="#feature-migrate_issues">migrate_issues</a> and <a
  2020. href="#feature-new_issues">new_issues</a> features.) </p>
  2021.  
  2022. <p> Create a new issue in the defect tracker and set it up for
  2023. replication (this is called both during migration from Perforce jobs,
  2024. and when a new job has been created in Perforce).  The <code
  2025. class="source">dict</code> argument is a dictionary mapping defect
  2026. tracker field name to a value for that field (the values have been
  2027. translated from Perforce), and the <code class="source">jobname</code>
  2028. argument is the name of the corresponding job in Perforce. </p>
  2029.  
  2030. <p> You should do your best to supply default values for required fields
  2031. if they are not present in <code class="source">dict</code>, and you
  2032. should try to avoid defect tracker workflow constraints (such as
  2033. insisting that an issue start out in a particular state).  If all else
  2034. fails, raise an error. </p>
  2035.  
  2036. <p> Return the newly-created issue as an object belonging to the <a
  2037. href="#section-7.2"><code class="source">defect_tracker_issue</code></a>
  2038. class. </p>
  2039.  
  2040. <p> The newly-created issue should respond in future as if its <a
  2041. href="#defect_tracker_issue.setup_for_replication"><code
  2042. class="source">setup_for_replication</code></a> method had been called
  2043. with <code class="source">jobspec</code> as the argument.  It is up to
  2044. you whether to call that method or implement the effect in some other
  2045. way. </p>
  2046.  
  2047. <p> This method is optional.  You need not provide it if you don't
  2048. support migration from Perforce. </p>
  2049.  
  2050.  
  2051. <h4> <a id="defect_tracker.new_issues_start" name="defect_tracker.new_issues_start"><code class="source">new_issues_start(self)</code></a> </h4>
  2052.  
  2053. <p> (The <code class="source">new_issues_start</code> method belongs to
  2054. the <a href="#feature-migrate_issues">migrate_issues</a> and <a
  2055. href="#feature-new_issues">new_issues</a> features.) </p>
  2056.  
  2057. <p> This method is called by the <abbr title="Perforce Defect Tracking
  2058. Integration">P4DTI</abbr> just before it starts migrating jobs from
  2059. Perforce to the defect tracker. </p>
  2060.  
  2061. <p> If you need to take a lock in the defect tracker database, take it
  2062. here and release it in <a href="#defect_tracker.new_issues_end"><code
  2063. class="source">new_issues_end</code></a>. </p>
  2064.  
  2065. <p> This method is optional.  You need not provide it if you don't
  2066. support migration from Perforce. </p>
  2067.  
  2068.  
  2069. <h4> <a id="defect_tracker.new_issues_end" name="defect_tracker.new_issues_end"><code class="source">new_issues_end(self)</code></a> </h4>
  2070.  
  2071. <p> (The <code class="source">new_issues_end</code> method belongs to
  2072. the <a href="#feature-migrate_issues">migrate_issues</a> and <a
  2073. href="#feature-new_issues">new_issues</a> features.) </p>
  2074.  
  2075. <p> This method is called by the <abbr title="Perforce Defect Tracking
  2076. Integration">P4DTI</abbr> just after it finishes migrating jobs from
  2077. Perforce to the defect tracker. </p>
  2078.  
  2079. <p> If you needed to take a lock in the defect tracker database, in <a
  2080. href="#defect_tracker.new_issues_start"><code
  2081. class="source">new_issues_start</code></a>, release it here. </p>
  2082.  
  2083. <p> This method is optional.  You need not provide it if you don't
  2084. support migration from Perforce. </p>
  2085.  
  2086.  
  2087.  
  2088. <h4> <a id="defect_tracker.poll_start" name="defect_tracker.poll_start"><code class="source">poll_start(self)</code></a> </h4>
  2089.  
  2090. <p> This method is called by the <abbr title="Perforce Defect Tracking
  2091. Integration">P4DTI</abbr> just before it polls the defect tracker with
  2092. the <a href="#defect_tracker.changed_entities"><code
  2093. class="source">changed_entities</code></a> method to discover changed
  2094. entities. </p>
  2095.  
  2096. <p> If you need to take a lock in the defect tracker database, take it
  2097. here and release it in <a href="#defect_tracker.poll_end"><code
  2098. class="source">poll_end</code></a>. </p>
  2099.  
  2100. <p> This method is optional.  You need not provide it. </p>
  2101.  
  2102.  
  2103. <h4> <a id="defect_tracker.poll_end" name="defect_tracker.poll_end"><code class="source">poll_end(self)</code></a> </h4>
  2104.  
  2105. <p> This method is called by the <abbr title="Perforce Defect Tracking
  2106. Integration">P4DTI</abbr> at the end of each replication cycle.  It is
  2107. called whether or not the replication succeeded.</p>
  2108.  
  2109. <p> If you needed to take a lock in the defect tracker database, in <a
  2110. href="#defect_tracker.poll_start"><code
  2111. class="source">poll_start</code></a>, release it here. </p>
  2112.  
  2113. <p> This method is optional.  You need not provide it. </p>
  2114.  
  2115.  
  2116. <h4> <a id="defect_tracker.replicate_changelist" name="defect_tracker.replicate_changelist"><code class="source">replicate_changelist(self, change, client, date, description, status, user)</code></a> </h4>
  2117.  
  2118. <p> (The <code class="source">replicate_changelist</code> method belongs
  2119. to the <a href="#feature-fixes">fixes</a> feature.) </p>
  2120.  
  2121. <p> Replicate a changelist to the defect tracker database (see <a
  2122. href="#section-4.2">section 4.2</a>). </p>
  2123.  
  2124. <p> The arguments specify the changelist; these arguments correspond to
  2125. a subset of the fields in the changelist relation in the Perforce
  2126. database (the names of the actual files changed, and their new revision
  2127. numbers, are not replicated). </p>
  2128.  
  2129. <dl>
  2130.  
  2131.   <dt><code class="source">change</code></dt>
  2132.  
  2133.   <dd><p> The change number (an integer). </p></dd>
  2134.  
  2135.   <dt><code class="source">client</code></dt>
  2136.  
  2137.   <dd><p> The client on which the change was last modified (a
  2138.   string). </p></dd>
  2139.  
  2140.   <dt><code class="source">date</code></dt>
  2141.  
  2142.   <dd><p> The date and time at which the change was last modified.  It
  2143.   has been converted by the date translator (see <a
  2144.   href="#section-7.5.1">section 7.5.1</a>). </p></dd>
  2145.  
  2146.   <dt><code class="source">description</code></dt>
  2147.  
  2148.   <dd><p> The change comment.  It has been converted by the text
  2149.   translator (see <a href="#section-7.5.3">section 7.5.3</a>). </p></dd>
  2150.  
  2151.   <dt><code class="source">status</code></dt>
  2152.  
  2153.   <dd><p> <code class="source">"pending"</code> if the changelist is
  2154.   pending, <code class="source">"submitted"</code> otherwise. </p></dd>
  2155.  
  2156.   <dt><code class="source">user</code></dt>
  2157.  
  2158.   <dd><p> The user who last modified the changelist.  It has been
  2159.   converted by the user translator (see <a href="#section-7.5.4">section
  2160.   7.5.4</a>). </p></dd>
  2161.  
  2162. </dl>
  2163.  
  2164. <p> This method must return 1 if the changelist was new or changed, or
  2165. 0 if it was unchanged. </p>
  2166.  
  2167.  
  2168. <h4> <a id="defect_tracker.supports" name="defect_tracker.supports"><code class="source">supports(self, feature)</code></a> </h4>
  2169.  
  2170. <p> Return 1 if your integration supports the feature named by the
  2171. <code class="source">feature</code> argument (a string); return 0 if you
  2172. don't support the feature.  See <a href="#section-3.5">section 3.5</a>
  2173. for the list of optional features.  If you don't recognize the feature,
  2174. return 0. </p>
  2175.  
  2176.  
  2177. <h3><a id="section-7.2" name="section-7.2">7.2. The <code class="source">dt_interface.defect_tracker_issue</code> class</a></h3>
  2178.  
  2179. <p> A subclass of <code
  2180. class="source">dt_interface.defect_tracker_issue</code> implements the
  2181. replicator's interface to the issues in a defect tracker. </p>
  2182.  
  2183. <blockquote><p> <i>Example.</i> The <a
  2184. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  2185. class="source">dt_bugzilla.py</code></a> module defines a class <code
  2186. class="source">bugzilla_bug</code> (issues are called "bugs" in
  2187. Bugzilla). </p></blockquote>
  2188.  
  2189.  
  2190. <h4><a id="section-7.2.1" name="section-7.2.1">7.2.1. Issue identifiers</a></h4>
  2191.  
  2192. <p> The replicator needs a unique identifier for each issue in the
  2193. defect tracker.  This must be a string, so that it can be stored in the
  2194. <code class="source">P4DTI-issue-id</code> field in the Perforce jobspec
  2195. [<a href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/#section-4.2">GDR
  2196. 2000-09-13, 4.2</a>].  The replicator gets the identifier from an
  2197. issue's <a href="#defect_tracker_issue.id"><code
  2198. class="source">id</code></a> method.  Later, it may pass the
  2199. identifier to the defect tracker's <a href="#defect_tracker.issue"><code
  2200. class="source">issue</code></a> method. </p>
  2201.  
  2202. <blockquote><p> <i>Example.</i> Bugzilla uniquely identifies bugs by
  2203. their bug number.  So in the <code class="source">dt_bugzilla</code>
  2204. module, the issue identifier is the string conversion of the bug
  2205. number. </p></blockquote>
  2206.  
  2207.  
  2208. <h4><a id="section-7.2.2" name="section-7.2.2">7.2.2. Issues are dictionaries</a></h4>
  2209.  
  2210. <p> The replicator considers an issue to consist of a collection of
  2211. named fields, with a value for each field.  Instances of the <code
  2212. class="source">defect_tracker_issue</code> subclass must support at
  2213. least the <a href="#defect_tracker_issue.__getitem__"><code
  2214. class="source">__getitem__</code></a> method, so that the replicator
  2215. can get the value for a field in an issue using the expression <code
  2216. class="source">issue["fieldname"]</code>. </p>
  2217.  
  2218. <p> You may want to implement the whole of the Python dictionary
  2219. interface for your own use, but the replicator only uses
  2220. <code class="source">__getitem__</code>.</p>
  2221.  
  2222.  
  2223. <p> A subclass of <code
  2224. class="source">dt_interface.defect_tracker_issue</code> must define the
  2225. following methods: </p>
  2226.  
  2227.  
  2228. <h4> <a id="defect_tracker_issue.__getitem__" name="defect_tracker_issue.__getitem__"><code class="source">__getitem__(self, field)</code></a> </h4>
  2229.  
  2230. <p> Return the value of the field named by the <code
  2231. class="source">field</code> argument.  Raise <code
  2232. class="source">KeyError</code> if the issue has no such field. </p>
  2233.  
  2234.  
  2235. <h4> <a id="defect_tracker_issue.__str__" name="defect_tracker_issue.__str__"><code class="source">__str__(self)</code></a> </h4>
  2236.  
  2237. <p> Return a string describing the issue, suitable for presentation to a
  2238. user or administrator in a report.  Having several lines of the form
  2239. "field name: value" is fine. </p>
  2240.  
  2241.  
  2242. <h4> <a id="defect_tracker_issue.add_filespec" name="defect_tracker_issue.add_filespec"><code class="source">add_filespec(self, filespec)</code></a> </h4>
  2243.  
  2244. <p> (The <code class="source">add_filespec</code> method belongs to the <a
  2245. href="#feature-filespecs">filespecs</a> feature.) </p>
  2246.  
  2247. <p> Add a filespec to the issue (see <a href="#section-4.4">section 4.4</a>). </p>
  2248.  
  2249. <p> The argument is the filespec to add (a string). </p>
  2250.  
  2251.  
  2252. <h4> <a id="defect_tracker_issue.add_fix" name="defect_tracker_issue.add_fix"><code class="source">add_fix(self, change, client, date, status, user)</code></a> </h4>
  2253.  
  2254. <p> (The <code class="source">add_fix</code> method belongs to the <a
  2255. href="#feature-fixes">fixes</a> feature.) </p>
  2256.  
  2257. <p> Add a fix to the issue (see <a href="#section-4.3">section 4.3</a>). </p>
  2258.  
  2259. <p> The arguments specify the fix; these arguments correspond to the
  2260. fields in the fix relation in the Perforce database. </p>
  2261.  
  2262. <dl>
  2263.  
  2264.   <dt><code class="source">change</code></dt>
  2265.  
  2266.   <dd><p> The Perforce change number (an integer). </p></dd>
  2267.  
  2268.   <dt><code class="source">client</code></dt>
  2269.  
  2270.   <dd><p> The Perforce client name from which the fix was made (a
  2271.   string). </p></dd>
  2272.  
  2273.   <dt><code class="source">date</code></dt>
  2274.  
  2275.   <dd><p> The date the fix was made.  It has been converted by the date
  2276.   translator (see <a href="#section-7.5.1">section 7.5.1</a>). </p></dd>
  2277.  
  2278.   <dt><code class="source">status</code></dt>
  2279.  
  2280.   <dd><p> The effect of the fix.  It is the status the job was changed
  2281.   to when the fix was made (or if the fix is to a pending changelist,
  2282.   then this is the status the job is changed to when the changelist is
  2283.   submitted). </p>
  2284.  
  2285.   <p> The status is also known as the "effect" (for example, in the
  2286.   defect tracker's interface to fixes (see <a href="#section-9">section
  2287.   9</a>)) because it gives the effect on the job when the fix is
  2288.   submitted. </p></dd>
  2289.  
  2290.   <dt><code class="source">user</code></dt>
  2291.  
  2292.   <dd><p> The user who made the fix.  It has been converted by the user
  2293.   translator (see <a href="#section-7.5.4">section 7.5.4</a>). </p></dd>
  2294.  
  2295. </dl>
  2296.  
  2297.  
  2298. <h4> <a id="defect_tracker_issue.corresponding_id" name="defect_tracker_issue.corresponding_id"><code class="source">corresponding_id(self)</code></a> </h4>
  2299.  
  2300. <p> If this issue has been replicated, return the name of the Perforce
  2301. job to which this issue is replicated. </p>
  2302.  
  2303. <p> If this issue has not yet been replicated, return the name for the
  2304. Perforce job to which this issue is replicated.  The returned value must
  2305. be legal as the name of a Perforce job.  You may want to use the result
  2306. of the <a href="#defect_tracker_issue.corresponding_id"><code
  2307. class="source">readable_name</code></a> method if that is
  2308. suitable. </p>
  2309.  
  2310.  
  2311. <h4> <a id="defect_tracker_issue.delete" name="defect_tracker_issue.delete"><code class="source">delete(self)</code></a> </h4>
  2312.  
  2313. <p> (The <code class="source">delete</code> method belongs to the <a
  2314. href="#feature-migrate_issues">migrate_issues</a> and <a
  2315. href="#feature-new_issues">new_issues</a> features.) </p>
  2316.  
  2317. <p> Delete the issue from the defect tracker (or flag the issue so that
  2318. it is not returned by the <a href="#defect_tracker.all_issues"><code
  2319. class="source">all_issues</code></a> and <a
  2320. href="#defect_tracker.changed_entities"><code
  2321. class="source">changed_entities</code></a> methods in future, if
  2322. deletion is impossible). </p>
  2323.  
  2324. <p> This method is only ever called of an issue that has just been
  2325. created by the <a href="#defect_tracker.new_issue"><code
  2326. class="source">new_issue</code></a> method, if an error occurred while
  2327. setting up the new issue. </p>
  2328.  
  2329.  
  2330. <h4> <a id="defect_tracker_issue.filespecs" name="defect_tracker_issue.filespecs"><code class="source">filespecs(self)</code></a> </h4>
  2331.  
  2332. <p> (The <code class="source">filespecs</code> method belongs to the <a
  2333. href="#feature-filespecs">filespecs</a> feature.) </p>
  2334.  
  2335. <p> Return a list of the filespecs associated with this issue.  Each
  2336. item in the list belongs to your subclass of the <code
  2337. class="source">defect_tracker_filespec</code> class (see <a
  2338. href="#section-7.4">section 7.4</a>). </p>
  2339.  
  2340.  
  2341. <h4> <a id="defect_tracker_issue.fixes" name="defect_tracker_issue.fixes"><code class="source">fixes(self)</code></a> </h4>
  2342.  
  2343. <p> (The <code class="source">fixes</code> method belongs to the <a
  2344. href="#feature-fixes">fixes</a> feature.) </p>
  2345.  
  2346. <p> Return a list of the fixes for this issue.  Each item in the list
  2347. belongs to your subclass of the <code
  2348. class="source">defect_tracker_fix</code> class (see <a
  2349. href="#section-7.3">section 7.3</a>). </p>
  2350.  
  2351.  
  2352. <h4> <a id="defect_tracker_issue.id" name="defect_tracker_issue.id"><code class="source">id(self)</code></a> </h4>
  2353.  
  2354. <p> Return a string that can be used to uniquely identify this issue
  2355. among all the issues in the defect tracker and to fetch it in future (see <a
  2356. href="#section-7.2.1">section 7.2.1</a>). </p>
  2357.  
  2358.  
  2359. <h4> <a id="defect_tracker_issue.readable_name" name="defect_tracker_issue.readable_name"><code class="source">readable_name(self)</code></a> </h4>
  2360.  
  2361. <p> Return a string giving a human-readable name for the issue.  This
  2362. name is only used in logs and e-mail messages. </p>
  2363.  
  2364.  
  2365. <h4> <a id="defect_tracker_issue.rid" name="defect_tracker_issue.rid"><code class="source">rid(self)</code></a> </h4>
  2366.  
  2367. <p> Return the replicator identifier of the replicator that is in charge
  2368. of replicating this issue, or the empty string if the issue is not being
  2369. replicated. </p>
  2370.  
  2371.  
  2372. <h4> <a id="defect_tracker_issue.setup_for_replication" name="defect_tracker_issue.setup_for_replication"><code class="source">setup_for_replication(self, jobname)</code></a> </h4>
  2373.  
  2374. <p> Set up the issue for replication.  That is, record that the issue is
  2375. replicated by this replicator and record any other information in the
  2376. database that is needed to replicate this issue. </p>
  2377.  
  2378. <p> You must do at least these three steps: </p>
  2379.  
  2380. <ol>
  2381.  
  2382.   <li><p> Record that the issue is replicated by this replicator, so
  2383.   that in the future its <a href="#defect_tracker_issue.rid"><code
  2384.   class="source">rid</code></a> method returns the correct replicator
  2385.   identifier (this is the <code class="source">rid</code> parameter in
  2386.   the configuration passed to the defect tracker class when it was
  2387.   instantiated). </p></li>
  2388.  
  2389.   <li><p> Record the Perforce server identifier of the Perforce server
  2390.   it is replicated to (this is the <code class="source">sid</code>
  2391.   parameter in the configuration passed to the defect tracker class when
  2392.   it was instantiated). </p></li>
  2393.  
  2394.   <li><p> Record that the issue is replicated to the Perforce job named
  2395.   by the <code class="source">jobname</code> argument, so that in future
  2396.   its <a href="#defect_tracker_issue.corresponding_id"><code
  2397.   class="source">corresponding_id</code></a> method returns <code
  2398.   class="source">jobname</code>. </p></li>
  2399.  
  2400. </ol>
  2401.  
  2402. <p> See <a href="#section-4.1">section 4.1</a>. </p>
  2403.  
  2404.  
  2405. <h4> <a id="defect_tracker_issue.update" name="defect_tracker_issue.update"><code class="source">update(self, user, changes)</code></a> </h4>
  2406.  
  2407. <p> Update the issue in the defect tracker's database. </p>
  2408.  
  2409. <p> The <code class="source">user</code> argument is the user who made
  2410. the change.  It has been converted by the user translator (see <a
  2411. href="#section-7.5.4">section 7.5.4</a>). </p>
  2412.  
  2413. <p> The <code class="source">changes</code> argument is a dictionary of
  2414. the changes that must be applied to the issue.  The keys of the
  2415. dictionary are the names of the fields that have changed; the values are
  2416. the new values for those fields.  Each value in the dictionary has been
  2417. converted by the appropriate translator.  If <code
  2418. class="source">changes</code> is the empty dictionary, then do
  2419. nothing. </p>
  2420.  
  2421. <p> If the defect tracker supports transitions in a workflow, then this
  2422. method should deduce the transition to apply (if any) based on the old
  2423. and new values for the issue fields. </p>
  2424.  
  2425. <blockquote><p> <i>Example.</i> The TeamTrack integration attempted to
  2426. find and apply a transition when the <code class="source">STATE</code>
  2427. field changes.  It looked at all the available transitions for the
  2428. issue and selected the transition resulting in the correct new
  2429. state. </p></blockquote>
  2430.  
  2431. <blockquote><p> <i>Example.</i> Bugzilla doesn't have transitions as
  2432. distinguished workflow objects, so there's no need for the Bugzilla
  2433. integration to deduce one.</p></blockquote>
  2434.  
  2435. <p> This method must check that the proposed change to the issue is
  2436. legal in the defect tracker.  (The changed fields have been converted by
  2437. their translators, so each is legal individually, but the defect tracker
  2438. may be more stringent, for example it may require a field not to have a
  2439. value when the issue is in a particular state.)  It must also check that
  2440. the user has permission to make the proposed change.  It's best if you
  2441. can call a function in the defect tracker's <abbr title="Application
  2442. Programmer Interface">API</abbr> to apply the defect tracker's own rules
  2443. (this is likely to be robust and maintainable), but if there's no such
  2444. function, then you must do your best to emulate the defect tracker's
  2445. checks. </p>
  2446.  
  2447. <p> If the issue can't be updated (for example, because the user doesn't
  2448. have permission to make the change, or because no workflow transition
  2449. can be discovered, or because the proposed change is illegal in some
  2450. way) then this method must raise an error. </p>
  2451.  
  2452. <blockquote><p> <i>Example.</i> The TeamTrack integration called the
  2453. <code class="source">TSServer::Transition</code> method in the
  2454. TeamShare <abbr title="Application Programmer Interface">API</abbr>,
  2455. which checked the issue for correctness and checked that the user has
  2456. the correct privilege.  All the integration needed to do is raise an
  2457. error if the function rejected the transition. </p></blockquote>
  2458.  
  2459. <blockquote><p> <i>Example.</i> Bugzilla has no <abbr title="Application
  2460. Programmer Interface">API</abbr>, so the Bugzilla integration must
  2461. emulate Bugzilla's checking.  The <a
  2462. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  2463. class="filename">dt_bugzilla.py</code></a> module defines three checking
  2464. methods: <code class="source">restrict_fields</code>, <code
  2465. class="source">enforce_invariants</code>, and <code
  2466. class="source">check_permissions</code>. </p></blockquote>
  2467.  
  2468.  
  2469. <h3><a id="section-7.3" name="section-7.3">7.3. The <code class="source">dt_interface.defect_tracker_fix</code> class</a></h3>
  2470.  
  2471. <p> (The <code class="source">defect_tracker_fix</code> class belongs to
  2472. the <a href="#feature-fixes">fixes</a> feature.) </p>
  2473.  
  2474. <p> A subclass of <code
  2475. class="source">dt_interface.defect_tracker_fix</code> implements the
  2476. replicator's interface to a fix record in a defect tracker (see <a
  2477. href="#section-4.3">section 4.3</a>). </p>
  2478.  
  2479. <blockquote><p> <i>Example.</i> The <a
  2480. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  2481. class="source">dt_bugzilla.py</code></a> module defines a class <code
  2482. class="source">bugzilla_fix</code>. </p></blockquote>
  2483.  
  2484. <p> A subclass of <code
  2485. class="source">dt_interface.defect_tracker_fix</code> must define the
  2486. following methods: </p>
  2487.  
  2488.  
  2489. <h4> <a id="defect_tracker_fix.change" name="defect_tracker_fix.change"><code class="source">change(self)</code></a> </h4>
  2490.  
  2491. <p> Return the change number for the fix, an integer. </p>
  2492.  
  2493.  
  2494. <h4> <a id="defect_tracker_fix.delete" name="defect_tracker_fix.delete"><code class="source">delete(self)</code></a> </h4>
  2495.  
  2496. <p> Delete the fix in the defect tracker so that the change is no longer
  2497. linked to the issue. </p>
  2498.  
  2499.  
  2500. <h4> <a id="defect_tracker_fix.status" name="defect_tracker_fix.status"><code class="source">status(self)</code></a> </h4>
  2501.  
  2502. <p> Return the status of the fix, a string. </p>
  2503.  
  2504.  
  2505. <h4> <a id="defect_tracker_fix.update" name="defect_tracker_fix.update"><code class="source">update(self, change, client, date, status, user)</code></a> </h4>
  2506.  
  2507. <p> Update this fix in the defect tracker so that has the given
  2508. fields.  If the fields are unchanged, do nothing. </p>
  2509.  
  2510. <p> This method is called when someone makes a new fix between the
  2511. change and issue of an existing fix (for example, the status used to be
  2512. "open", but now is "closed").  Since there can be only one fix for a
  2513. given change and issue, the replicator updates the fix rather than
  2514. creating a new fix. </p>
  2515.  
  2516. <p> The arguments specify the fix; these arguments correspond to the
  2517. fields in the fix relation in the Perforce database. </p>
  2518.  
  2519. <dl>
  2520.  
  2521.   <dt><code class="source">change</code></dt>
  2522.  
  2523.   <dd><p> The Perforce change number (an integer). </p></dd>
  2524.  
  2525.   <dt><code class="source">client</code></dt>
  2526.  
  2527.   <dd><p> The Perforce client name from which the fix was made (a
  2528.   string). </p></dd>
  2529.  
  2530.   <dt><code class="source">date</code></dt>
  2531.  
  2532.   <dd><p> The date the fix was made.  It has been converted by the date
  2533.   translator (see <a href="#section-7.5.1">section 7.5.1</a>). </p></dd>
  2534.  
  2535.   <dt><code class="source">status</code></dt>
  2536.  
  2537.   <dd><p> The effect of the fix.  It is the status the job was changed
  2538.   to when the fix was made (or if the fix is to a pending changelist,
  2539.   then this is the status the job is changed to when the changelist is
  2540.   submitted). </p>
  2541.  
  2542.   <p> The status is also known as the "effect" (for example, in the
  2543.   defect tracker's interface to fixes (see <a href="#section-9">section
  2544.   9</a>)) because it gives the effect on the job when the fix is
  2545.   submitted. </p></dd>
  2546.  
  2547.   <dt><code class="source">user</code></dt>
  2548.  
  2549.   <dd><p> The user who made the fix.  It has been converted by the user
  2550.   translator (see <a href="#section-7.5.4">section 7.5.4</a>). </p></dd>
  2551.  
  2552. </dl>
  2553.  
  2554.  
  2555. <h3><a id="section-7.4" name="section-7.4">7.4. The <code class="source">dt_interface.defect_tracker_filespec</code> class</a></h3>
  2556.  
  2557. <p> (The <code class="source">defect_tracker_filespec</code> class
  2558. belongs to the <a href="#feature-filespecs">filespecs</a> feature.) </p>
  2559.  
  2560. <p> A subclass of <code
  2561. class="source">dt_interface.defect_tracker_filespec</code> implements the
  2562. replicator's interface to a filespec record in a defect tracker (see <a
  2563. href="#section-4.4">section 4.4</a>). </p>
  2564.  
  2565. <blockquote><p> <i>Example.</i> The <a
  2566. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/dt_bugzilla.py"><code
  2567. class="source">dt_bugzilla.py</code></a> module defines a class <code
  2568. class="source">bugzilla_filespec</code>. </p></blockquote>
  2569.  
  2570. <p> A subclass of <code
  2571. class="source">dt_interface.defect_tracker_filespec</code> must define the
  2572. following methods: </p>
  2573.  
  2574.  
  2575. <h4> <a id="defect_tracker_filespec.delete" name="defect_tracker_filespec.delete"><code class="source">delete(self)</code></a> </h4>
  2576.  
  2577. <p> Delete the filespec record so that the issue is no longer associated
  2578. with the filespec. </p>
  2579.  
  2580.  
  2581. <h4> <a id="defect_tracker_filespec.name" name="defect_tracker_filespec.name"><code class="source">name(self)</code></a> </h4>
  2582.  
  2583. <p> Return the filespec, a string. </p>
  2584.  
  2585.  
  2586. <h3><a id="section-7.5" name="section-7.5">7.5. The <code class="source">translator.translator</code> class</a></h3>
  2587.  
  2588. <p> A subclass of <code class="source">translator.translator</code>
  2589. translates values of a particular type between the defect tracker and
  2590. Perforce.  You should define a translator for each field type in the
  2591. defect tracker that you want the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> administrator to be
  2592. able to replicate.  You must define translators for dates (see <a
  2593. href="#section-7.5.1">section 7.5.1</a>), multi-line text fields (see <a
  2594. href="#section-7.5.3">section 7.5.3</a>), and users (see <a
  2595. href="#section-7.5.4">section 7.5.4</a>).  If your defect tracker has any
  2596. concept of the state of an issue, then you must define a translator for
  2597. states (see <a href="#section-7.5.2">section 7.5.2</a>). </p>
  2598.  
  2599. <blockquote><p> <i>Example.</i> The TeamTrack integration defined, in
  2600. addition to the three required translators, translators for: fields that
  2601. cross-referenced an auxiliary table like <code
  2602. class="source">TS_PROJECTS</code>; elapsed time fields; selection
  2603. fields; and the <code class="source">STATE</code> field.
  2604. </p></blockquote>
  2605.  
  2606. <p> The translator base class doesn't know anything about Perforce; all
  2607. it knows is that it is translating between two defect trackers, called 0
  2608. and 1.  In the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, defect tracker 1 is always Perforce,
  2609. but we haven't limited the design of the translator class by requiring
  2610. that it is. </p>
  2611.  
  2612. <p> Each subclass of <code class="source">translator.translator</code>
  2613. must define the following methods: </p>
  2614.  
  2615.  
  2616. <h4> <a id="translator.translate_0_to_1" name="translator.translate_0_to_1"><code class="source">translate_0_to_1(self, value, dt0, dt1, issue0=None, issue1=None)</code></a> </h4>
  2617.  
  2618. <p> Return <code class="source">value</code>, suitably translated from
  2619. defect tracker 0 to defect tracker 1.  If translation is not possible,
  2620. raise an error. </p>
  2621.  
  2622. <dl>
  2623.  
  2624.   <dt><code class="source">value</code></dt>
  2625.  
  2626.   <dd><p> The value for a field in a defect tracker issue that is to be
  2627.   translated. </p></dd>
  2628.  
  2629.   <dt><code class="source">dt0</code></dt>
  2630.  
  2631.   <dd><p> Your defect tracker: an instance of your subclass of <a
  2632.   href="#section-7.1"><code
  2633.   class="source">dt_interface.defect_tracker</code></a>.  </p></dd>
  2634.  
  2635.   <dt><code class="source">dt1</code></dt>
  2636.  
  2637.   <dd><p> Perforce (represented by an instance of a subclass of <a
  2638.   href="#section-7.1"><code
  2639.   class="source">dt_interface.defect_tracker</code></a>).  </p></dd>
  2640.  
  2641.   <dt><code class="source">issue0</code></dt>
  2642.  
  2643.   <dd><p> The issue in your defect tracker from which the value comes,
  2644.   or <code class="source">None</code> if the value doesn't come from an
  2645.   issue.  An instance of your subclass of <a href="#section-7.2"><code
  2646.   class="source">dt_interface.defect_tracker_issue</code></a>. </p></dd>
  2647.  
  2648.   <dt><code class="source">issue1</code></dt>
  2649.  
  2650.   <dd><p> The job in Perforce to which the value is going, or <code
  2651.   class="source">None</code> if the value isn't going to a job
  2652.   (represented by an instance of a subclass of <a
  2653.   href="#section-7.2"><code
  2654.   class="source">dt_interface.defect_tracker_issue</code></a>).
  2655.   </p></dd>
  2656.  
  2657. </dl>
  2658.  
  2659. <p> This method takes defect trackers as arguments because it may need
  2660. to query the defect tracker to carry out the translation. </p>
  2661.  
  2662. <blockquote><p> <i>Example.</i> In the TeamTrack integration, the single
  2663. select translator needed to read the <code
  2664. class="source">TS_SELECTIONS</code> table to discover the available
  2665. selections.  To do this it called the private method <code
  2666. class="source">read_selections</code> in <code
  2667. class="source">dt0</code>.  </p></blockquote>
  2668.  
  2669. <p> This method takes issues as arguments because some translators need
  2670. to know about the whole issue in order to carry out the translation. </p>
  2671.  
  2672. <blockquote><p> <i>Example.</i> In the TeamTrack integration the state
  2673. translator needed to know the project to which the issue belonged (because
  2674. different projects may have different states with the same name which
  2675. correspond to the same Perforce state). </p></blockquote>
  2676.  
  2677. <p> Many translators can ignore the <code class="source">dt0</code> and
  2678. <code class="source">dt1</code> arguments; most can ignore the <code
  2679. class="source">issue0</code> and <code class="source">issue1</code>
  2680. arguments. </p>
  2681.  
  2682.  
  2683. <h4> <a id="translator.translate_1_to_0" name="translator.translate_1_to_0"><code class="source">translate_1_to_0(self, value, dt0, dt1, issue0=None, issue1=None)</code></a> </h4>
  2684.  
  2685. <p> Return <code class="source">value</code>, suitably translated from
  2686. defect tracker 1 to defect tracker 0.  If translation is not possible,
  2687. raise an error. </p>
  2688.  
  2689. <dl>
  2690.  
  2691.   <dt><code class="source">value</code></dt>
  2692.  
  2693.   <dd><p> The value in a job in Perforce that is to be translated. </p>
  2694.  
  2695.   <p> <strong>Warning.</strong> Be careful not to assume that a value in
  2696.   field in Perforce is valid for that field.  Perforce's checks on field
  2697.   values can be bypassed (for example, by the <code
  2698.   class="command">-f</code> option to the <code class="command">p4
  2699.   job</code> command, or by editing a job and changing the jobspec to
  2700.   make the job invalid).  So you should do something appropriate with
  2701.   invalid values, such as raising an error, or substituting a default
  2702.   value.  It's particularly important to be able to do something
  2703.   sensible with the empty string, which is what you'll get when there's
  2704.   no value for that field in Perforce. </p></dd>
  2705.  
  2706.   <dt><code class="source">dt0</code></dt>
  2707.  
  2708.   <dd><p> Your defect tracker: an instance of your subclass of <a
  2709.   href="#section-7.1"><code
  2710.   class="source">dt_interface.defect_tracker</code></a>.  </p></dd>
  2711.  
  2712.   <dt><code class="source">dt1</code></dt>
  2713.  
  2714.   <dd><p> Perforce (represented by an instance of a subclass of <a
  2715.   href="#section-7.1"><code
  2716.   class="source">dt_interface.defect_tracker</code></a>).  </p></dd>
  2717.  
  2718.   <dt><code class="source">issue0</code></dt>
  2719.  
  2720.   <dd><p> The issue in your defect tracker to which the value is going,
  2721.   or <code class="source">None</code> if the value isn't going to an
  2722.   issue.  An instance of your subclass of <a href="#section-7.2"><code
  2723.   class="source">dt_interface.defect_tracker_issue</code></a>.  </p></dd>
  2724.  
  2725.   <dt><code class="source">issue1</code></dt>
  2726.  
  2727.   <dd><p> The job in Perforce from which the value comes, or <code
  2728.   class="source">None</code> if the value doesn't come from a job
  2729.   (represented by an instance of a subclass of <a
  2730.   href="#section-7.2"><code
  2731.   class="source">dt_interface.defect_tracker_issue</code></a>).
  2732.   </p>
  2733.  
  2734.   <p> <strong>Warning.</strong> Be careful not to assume that the
  2735.   dictionary representing the job has all fields present.  It's possible
  2736.   that it has only a subset of fields.  So don't write <code
  2737.   class="source">issue1['Spong']</code>, write <code class="source">if
  2738.   issue1.has_key('Spong'):</code> or <code
  2739.   class="source">issue1.get('Spong',
  2740.   <i>default_value</i>)</code>. </p></dd>
  2741.  
  2742. </dl>
  2743.  
  2744.  
  2745. <h4><a id="section-7.5.1" name="section-7.5.1">7.5.1. Date translator</a></h4>
  2746.  
  2747. <p> You must define a date translator class, a subclass of <a
  2748. href="#section-7.5"><code
  2749. class="source">translator.translator</code></a>, to translate dates
  2750. between your defect tracker and Perforce. </p>
  2751.  
  2752. <p> When translating to Perforce: </p>
  2753.  
  2754. <ol>
  2755.  
  2756.   <li><p> An empty or null date field must be translated to the empty
  2757.   string. </p></li>
  2758.  
  2759.   <li><p> Any other date must be translated to a string looking like
  2760.   <code class="source">"2000/12/31 23:59:59"</code> (you can do this by
  2761.   calling <code class="source">time.strftime</code> with <code
  2762.   class="source">"%Y/%m/%d %H:%M:%S"</code> as the first
  2763.   argument). </p></li>
  2764.  
  2765. </ol>
  2766.  
  2767. <p> When translating from Perforce: </p>
  2768.  
  2769. <ol>
  2770.  
  2771.   <li><p> The empty string must be translated to an empty or null date
  2772.   field. </p></li>
  2773.  
  2774.   <li><p> A string in the format <code class="source">"2000/12/31
  2775.   23:59:59"</code> specifies the calendar date.  (This form is used by
  2776.   changelists and jobs.)  </p></li>
  2777.  
  2778.   <li><p> A string consisting only of digits specifies the number of
  2779.   seconds since 1970-01-01 00:00:00 UTC.  (This form is used by fixes.)
  2780.   </p></li>
  2781.  
  2782. </ol>
  2783.  
  2784. <p> <strong>Timezones.</strong> When Perforce creates a timestamp for a
  2785. changelist or for a field in job with a preset of <code
  2786. class="source">$now</code>, it uses local time on the Perforce server.
  2787. For other date fields in jobs, Perforce just stores the date the user
  2788. entered, without conversion.  Your date translator must make sure that
  2789. its translations in the two directions are inverses of each other.  The
  2790. simplest way to do this is to follow the same principle as the Perforce
  2791. server: just treat the date as you get it, without conversion. </p>
  2792.  
  2793. <blockquote><p> <i>Example.</i> TeamTrack specifies all dates as seconds
  2794. since 1970-01-01 00:00:00, so the TeamTrack integration used <code
  2795. class="source">time.strftime</code> to convert from TeamTrack to
  2796. Perforce, and either <code class="source">time.mktime</code> or simply
  2797. <code class="source">int</code> to convert from Perforce to
  2798. TeamTrack.</p></blockquote>
  2799.  
  2800.  
  2801. <h4><a id="section-7.5.2" name="section-7.5.2">7.5.2. State translator</a></h4>
  2802.  
  2803. <p> If your defect tracker has a concept of states for issues, then you
  2804. must define a state translator class, a subclass of <a
  2805. href="#section-7.5"><code
  2806. class="source">translator.translator</code></a>. </p>
  2807.  
  2808. <p> The state field in Perforce should be a "select" field (see <a
  2809. href="#section-8.4">section 8.4</a>) so the values for this field should
  2810. be legal selections in Perforce.  This means no whitespace, hashes,
  2811. double quotes, semicolons or slashes.  Since the defect tracker probably
  2812. allows these character to appear in state names, you must convert them
  2813. somehow. </p>
  2814.  
  2815. <p> We have provided a translator to do this conversion: it is the
  2816. <code class="source">keyword_translator</code> class in the <a
  2817. href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/translator.py"><code
  2818. class="filename">translator.py</code></a> module. </p>
  2819.  
  2820. <p> You shouldn't just use the keyword translator as your state
  2821. translator, since all it does is to convert strings.  You should develop
  2822. a translator that checks that applies the keyword translator, checks
  2823. that the converted state is legal and raises an error if it is
  2824. not. </p>
  2825.  
  2826.  
  2827. <h4><a id="section-7.5.3" name="section-7.5.3">7.5.3. Text translator</a></h4>
  2828.  
  2829. <p> You must define a text translator class, a subclass of <a
  2830. href="#section-7.5"><code
  2831. class="source">translator.translator</code></a>, to translate multi-line
  2832. text fields between your defect tracker and Perforce. </p>
  2833.  
  2834. <p> This translator must translate line endings (if needed).  Perforce
  2835. uses newline (<code class="source">"\n"</code>) as the line ending;
  2836. values always end in a newline (unless the field is empty); values never
  2837. end in more than one newline. </p>
  2838.  
  2839. <blockquote><p> <i>Example.</i> TeamTrack uses a carriage return plus a
  2840. newline (<code class="source">\r\n</code>) as its line ending, and there
  2841. need not be a final newline. </p></blockquote>
  2842.  
  2843. <blockquote><p> <i>Example.</i> The MySQL database interface converts
  2844. newlines if necessary, so the Bugzilla integration uses <code
  2845. class="source">translator.translator</code> (a translator which does
  2846. nothing) for its text translator. </p></blockquote>
  2847.  
  2848.  
  2849. <h4><a id="section-7.5.4" name="section-7.5.4">7.5.4. User translator</a></h4>
  2850.  
  2851. <p> You must define a user translator class, a subclass of <code
  2852. class="source">translator.user_translator</code>, to translate users
  2853. between your defect tracker and Perforce. </p>
  2854.  
  2855. <p> It is important not to assume that userids are the same in Perforce
  2856. and the defect tracker, because an organization may have different
  2857. policies for assigning userids in the two systems, or there may be
  2858. legacy users from a previous policy.  The TeamTrack and Bugzilla
  2859. integrations translate between users based on their e-mail addresses.
  2860. Your integration should do the same if possible and appropriate. </p>
  2861.  
  2862. <p> When translating from the defect tracker to Perforce: </p>
  2863.  
  2864. <ol>
  2865.  
  2866.   <li><p> Map the defect tracker user to a Perforce user with the same
  2867.   e-mail address, if there is one. </p></li>
  2868.  
  2869.   <li><p> Otherwise, map the defect tracker user to the Perforce user
  2870.   with the same userid, if there is one. </p></li>
  2871.  
  2872.   <li><p> Otherwise, return the defect tracker userid unchanged
  2873.   (assuming it is valid syntactically as a Perforce userid; if it isn't,
  2874.   apply the keyword translator (see <a href="#section-7.5.2">section
  2875.   7.5.2</a>) to it). </p></li>
  2876.  
  2877. </ol>
  2878.  
  2879. <p> When translating from Perforce to the defect tracker: </p>
  2880.  
  2881. <ol>
  2882.  
  2883.   <li><p> Map the Perforce user to a defect tracker user with the same
  2884.   e-mail address, if there is one. </p></li>
  2885.  
  2886.   <li><p> Otherwise, map the Perforce user to the defect tracker user
  2887.   with the same userid, if there is one. </p></li>
  2888.  
  2889.   <li><p> Otherwise, if translating the user in a changelist or fix, map
  2890.   the Perforce user to some dummy defect tracker user (see <a
  2891.   href="#section-4.8">section 4.8</a>).  You can tell that you're translating a
  2892.   changelist or fix rather than an issue because the <code
  2893.   class="source">issue0</code> argument to the <a
  2894.   href="#translator.translate_1_to_0"><code
  2895.   class="source">translate_1_to_0</code></a> method is <code
  2896.   class="source">None</code>. </p></li>
  2897.  
  2898.   <li><p> Otherwise, you're translating a user field in an issue and you
  2899.   can't find a match either by e-mail address or by name.  Raise an
  2900.   error. </p></li>
  2901.  
  2902. </ol>
  2903.  
  2904. <p> Each subclass of <code
  2905. class="source">translator.user_translator</code> must define the
  2906. following method: </p>
  2907.  
  2908.  
  2909. <h4> <a id="user_translator.unmatched_users" name="user_translator.unmatched_users"><code class="source">unmatched_users(self)</code></a> </h4>
  2910.  
  2911. <p> This method should examine all the users in the defect tracker and
  2912. Perforce and return a report on the users in each system that have no
  2913. corresponding userid in the other. </p>
  2914.  
  2915. <p> It must return a tuple.  The first four elements of the tuple must
  2916. be as follows: </p>
  2917.  
  2918. <ol>
  2919.  
  2920.   <li><p> A dictionary of users in the defect tracker that have no
  2921.   corresponding userid in Perforce.  The keys of the dictionary are
  2922.   strings naming the defect tracker userids; the values of the
  2923.   dictionary are the e-mail addresses of the defect tracker
  2924.   users. </p></li>
  2925.  
  2926.   <li><p> A dictionary of users in Perforce that have no corresponding
  2927.   userid in the defect tracker.  The keys of the dictionary are the
  2928.   Perforce userids; the values of the dictionary are the e-mail
  2929.   addresses of the Perforce users. </p></li>
  2930.  
  2931.   <li>
  2932.  
  2933.   <p> A comment (a string or message) about the users in the first
  2934.   dictionary explaining how they are treated by this user
  2935.   translator. </p>
  2936.  
  2937.   <blockquote><p> <i>Example.</i> The Bugzilla integration says, "A
  2938.   user field containing one of these users will be translated to the
  2939.   user's e-mail address in the corresponding Perforce job
  2940.   field."</p></blockquote>
  2941.  
  2942.   </li>
  2943.  
  2944.   <li>
  2945.  
  2946.   <p> A comment (a string or message) about the users in the second
  2947.   dictionary explaining how they are treated by this user
  2948.   translator. </p>
  2949.  
  2950.   <blockquote><p> <i>Example.</i> The Bugzilla integration says "It
  2951.   will not be possible to use Perforce to assign bugs to these users.
  2952.   Changes to jobs made by these users will be ascribed in Bugzilla to
  2953.   the replicator user." </p></blockquote>
  2954.  
  2955.   </li>
  2956.  
  2957. </ol>
  2958.  
  2959. <p> Optionally, the returned tuple may have four additional elements:
  2960. </p>
  2961.  
  2962. <ol start="5">
  2963.  
  2964.   <li><p> A dictionary of users in the defect tracker that have
  2965.   duplicate e-mail addresses, and which therefore may have been matched
  2966.   to the wrong user in Perforce.  The keys of the dictionary are strings
  2967.   naming the defect tracker userids; the values of the dictionary are
  2968.   the e-mail addresses of the defect tracker users. </p></li>
  2969.  
  2970.   <li><p> A dictionary of users in Perforce that have duplicate e-mail
  2971.   addresses, and which therefore may have been matched to the wrong user
  2972.   in the defect tracker.  The keys of the dictionary are the Perforce
  2973.   userids; the values of the dictionary are the e-mail addresses of the
  2974.   Perforce users. </p></li>
  2975.  
  2976.   <li><p> A comment (a string or message) about the defect tracker users
  2977.   with duplicate e-mail addresses, explaining what the problem is.  If
  2978.   there are no such users, then you may specify <code
  2979.   class="source">None</code> here. </p>
  2980.  
  2981.   <blockquote><p> <i>Example.</i> The Bugzilla integration says,
  2982.   "These Bugzilla users have duplicate e-mail addresses (when
  2983.   converted to lower case).  They may have been matched with the wrong
  2984.   Perforce user."</p></blockquote></li>
  2985.  
  2986.   <li><p> A comment (a string or message) about the Perforce users with
  2987.   duplicate e-mail addresses, explaining what the problem is.  If there
  2988.   are no such users, then you may specify <code
  2989.   class="source">None</code> here. </p>
  2990.  
  2991.   <blockquote><p> <i>Example.</i> The Bugzilla integration says,
  2992.   "These Perforce users have duplicate e-mail addresses.  They may
  2993.   have been matched with the wrong Bugzilla user."
  2994.   </p></blockquote></li>
  2995.  
  2996. </ol>
  2997.  
  2998. <p> This method is called each time the replicator is started.  The
  2999. results are used to compose an e-mail to the <abbr title="Perforce
  3000. Defect Tracking Integration">P4DTI</abbr> administrator reporting on
  3001. unmatched users. </p>
  3002.  
  3003.  
  3004. <h3><a id="section-7.6" name="section-7.6">7.6. Cursors</a></h3>
  3005.  
  3006. <p> The <a href="#defect_tracker.all_issues"><code
  3007. class="source">all_issues</code></a> and <a
  3008. href="#defect_tracker.changed_entities"><code
  3009. class="source">changed_entities</code></a> methods return cursors.  A
  3010. cursor is a representation of the result set of a query into a database.
  3011. It has the following method: </p>
  3012.  
  3013.  
  3014. <h4> <a id="cursor.fetchone" name="cursor.fetchone"><code class="source">fetchone(self)</code></a> </h4>
  3015.  
  3016. <p> Return the next item in the result set, or <code
  3017. class="source">None</code> if there are no more items. </p>
  3018.  
  3019.  
  3020. <h2><a id="section-8" name="section-8">8. Configuration</a></h2>
  3021.  
  3022. <p> This section describes how to configure the <abbr title="Perforce
  3023. Defect Tracking Integration">P4DTI</abbr> to work with your extension.
  3024. To understand how the configuration works, see [<a
  3025. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/#section-5">GDR
  3026. 2000-09-13, 5</a>]. </p>
  3027.  
  3028.  
  3029. <h3><a id="section-8.1" name="section-8.1">8.1. The configuration generator</a></h3>
  3030.  
  3031. <p> You must write a configuration generator for your defect tracker.
  3032. This must be a module called <code
  3033. class="filename">config_<i>defect_tracker</i>.py</code>, where
  3034. <i>defect_tracker</i> is the name you chose for your defect tracker (see
  3035. <a href="#section-3">section 3</a>), converted to lower case. </p>
  3036.  
  3037. <p> It must provide the following function: </p>
  3038.  
  3039.  
  3040. <h4><a id="configure_dt.configuration" name="configure_dt.configuration"><code class="source">configuration(config)</code></a></h4>
  3041.  
  3042. <p> The <code class="source">config</code> argument is a module whose
  3043. members are the configuration parameters specified by the <abbr
  3044. title="Perforce Defect Tracking Integration">P4DTI</abbr> administrator
  3045. in <a href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/config.py"><code
  3046. class="filename">config.py</code></a>. </p>
  3047.  
  3048. <p> It must check all the user configuration parameters that are
  3049. specific to your defect tracker. </p>
  3050.  
  3051. <p> It must return a revised configuration module, which should include
  3052. all the configuration parameters in the <code
  3053. class="source">config</code> argument, plus the configuration parameters
  3054. required by your defect tracker module, by the replicator (see <a
  3055. href="#section-8.3">section 8.3</a>), and by the Perforce interface (see
  3056. <a href="#section-8.2">section 8.2</a>).  It's OK to modify the
  3057. configuration module that you were passed and return that. </p>
  3058.  
  3059.  
  3060. <h3><a id="section-8.2" name="section-8.2">8.2. Perforce interface configuration</a></h3>
  3061.  
  3062. <p> The revised configuration module must include the following
  3063. parameter for the Perforce interface.  (This is in addition to the
  3064. parameters <a
  3065. href="../ag/index.html#config-p4_client_executable"><code
  3066. class="source">p4_client_executable</code></a>, <a
  3067. href="../ag/index.html#config-p4_password"><code
  3068. class="source">p4_password</code></a>, <a
  3069. href="../ag/index.html#config-p4_port"><code
  3070. class="source">p4_port</code></a>, and <a
  3071. href="../ag/index.html#config-p4_user"><code
  3072. class="source">p4_user</code></a> which came from the user
  3073. configuration.) </p>
  3074.  
  3075.  
  3076. <h4><a id="config-logger" name="config-logger"><code class="source">logger</code></a></h4>
  3077.  
  3078. <p> This is a logger object (see <a href="#section-5.3">section 5.3</a>)
  3079. to which log messages are written.  It must log to <a
  3080. href="../ag/index.html#config-log_file"><code
  3081. class="source">log_file</code></a> if that is specified, to standard
  3082. output, and to any appropriate system logging facility.  It must respect
  3083. the <a
  3084. href="../ag/index.html#config-log_level"><code
  3085. class="source">log_level</code></a>. </p>
  3086.  
  3087.  
  3088. <h3><a id="section-8.3" name="section-8.3">8.3. Replicator configuration</a></h3>
  3089.  
  3090. <p> The revised configuration module must include the following
  3091. parameters for the replicator.  (These are in addition to the <a
  3092. href="../ag/index.html#config-administrator_address"><code
  3093. class="source">administrator_address</code></a>, <a
  3094. href="../ag/index.html#config-p4_user"><code
  3095. class="source">p4_user</code></a>, <a
  3096. href="../ag/index.html#config-poll_period"><code
  3097. class="source">poll_period</code></a>, <a
  3098. href="../ag/index.html#config-replicate_p"><code
  3099. class="source">replicate_p</code></a>, <a
  3100. href="../ag/index.html#config-replicator_address"><code
  3101. class="source">replicator_address</code></a>, <a
  3102. href="../ag/index.html#config-rid"><code
  3103. class="source">rid</code></a>, and <a
  3104. href="../ag/index.html#config-smtp_server"><code
  3105. class="source">smtp_server</code></a> parameters which came from the
  3106. user configuration.) </p>
  3107.  
  3108.  
  3109. <h4><a id="config-date_translator" name="config-date_translator"><code class="source">date_translator</code></a></h4>
  3110.  
  3111. <p> A date translator instance (see <a href="#section-7.5.1">section
  3112. 7.5.1</a>). </p>
  3113.  
  3114.  
  3115. <h4><a id="config-field_map" name="config-field_map"><code class="source">field_map</code></a></h4>
  3116.  
  3117. <p> A description of how fields map from the defect tracker to Perforce
  3118. and back again.  It is a list of tuples, one for each field to be
  3119. replicated.  Each tuple has three elements: </p>
  3120.  
  3121. <ol>
  3122.  
  3123.   <li><p> The name of the field in the defect tracker. </p></li>
  3124.  
  3125.   <li><p> The name of the field in Perforce. </p></li>
  3126.  
  3127.   <li><p> A translator instance (see <a href="#section-7.5">section
  3128.   7.5</a>) that can be used to translate between values in the two
  3129.   fields. </p></li>
  3130.  
  3131. </ol>
  3132.  
  3133. <p> The field map must match the defect tracker database and the <a
  3134. href="#config-jobspec"><code class="source">jobspec</code></a>
  3135. configuration parameter. </p>
  3136.  
  3137.  
  3138. <h4><a id="config-job_owner_field" name="config-job_owner_field"><code class="source">job_owner_field</code></a></h4>
  3139.  
  3140. <p> The name of the field in the Perforce jobspec which contains the
  3141. owner of the job. </p>
  3142.  
  3143. <blockquote><p> <i>Example.</i> In the TeamTrack integration, this was
  3144. <code class="source">"Owner"</code>.  In the Bugzilla integration, this is
  3145. <code class="source">"Assigned_To"</code>. </p></blockquote>
  3146.  
  3147.  
  3148. <h4><a id="config-job_status_field" name="config-job_status_field"><code class="source">job_status_field</code></a></h4>
  3149.  
  3150. <p> The name of the field in the Perforce jobspec which contains the
  3151. status of the job. </p>
  3152.  
  3153. <blockquote><p> <i>Example.</i> In the TeamTrack integration, this was
  3154. <code class="source">"State"</code>.  In the Bugzilla integration, this
  3155. is <code class="source">"Status"</code>. </p></blockquote>
  3156.  
  3157.  
  3158. <h4><a id="config-jobspec" name="config-jobspec"><code class="source">jobspec</code></a></h4>
  3159.  
  3160. <p> The Perforce jobspec which the replicator is going to use, or
  3161. <code class="source">None</code> if the Perforce jobspec is left
  3162. unchanged. See also <a
  3163. href="../ag/index.html#config-keep_jobspec"><code
  3164. class="source">keep_jopspec</code></a>.</p>
  3165.  
  3166. <p> The jobspec must be in the format described in <a
  3167. href="#section-8.4">section 8.4</a> and must match the <a
  3168. href="#config-field_map"><code class="source">field_map</code></a>
  3169. configuration parameter. </p>
  3170.  
  3171.  
  3172. <h4><a id="config-replicator.logger" name="config-replicator.logger"><code class="source">logger</code></a></h4>
  3173.  
  3174. <p> This must be the same as the <a href="#config-logger">logger object
  3175. for the Perforce interface</a>. </p>
  3176.  
  3177.  
  3178. <h4><a id="config-prepare_issue_advanced" name="config-prepare_issue_advanced"><code class="source">prepare_issue_advanced(config, dt, p4, issue, job)</code></a></h4>
  3179.  
  3180. <p> (The <code class="source">prepare_issue_advanced</code> function
  3181. belongs to the <a href="#feature-new_issues">new_issues</a> feature.)
  3182. </p>
  3183.  
  3184. <p> A function to complete the transformation of a new job in Perforce
  3185. to an issue in the defect tracker.  The function takes 5 arguments:
  3186. </p>
  3187.  
  3188. <dl>
  3189.  
  3190.   <dt><code class="source">config</code></dt>
  3191.  
  3192.   <dd><p> A Python module containing the replicator
  3193.   configuration. </p></dd>
  3194.  
  3195.   <dt><code class="source">dt</code></dt>
  3196.  
  3197.   <dd><p> Your defect tracker: an instance of your subclass of <a
  3198.   href="#section-7.1"><code
  3199.   class="source">dt_interface.defect_tracker</code></a>. </p></dd>
  3200.  
  3201.   <dt><code class="source">p4</code></dt>
  3202.  
  3203.   <dd><p> Perforce (represented by an instance of a subclass of <a
  3204.   href="#section-7.1"><code
  3205.   class="source">dt_interface.defect_tracker</code></a>). </p></dd>
  3206.  
  3207.   <dt><code class="source">issue</code></dt>
  3208.  
  3209.   <dd><p> The partly-constructed issue, in the form of a Python
  3210.   dictionary mapping field name (string) to field value.  (The values in
  3211.   the dictionary are the result of applying the translators in the <a
  3212.   href="#config-field_map"><code class="source">field_map</code></a> to
  3213.   the fields in the <code class="source">job</code>.) </p></dd>
  3214.  
  3215.   <dt><code class="source">job</code></dt>
  3216.  
  3217.   <dd><p> The newly-created job, in the form of a Python dictionary
  3218.   mapping field name (string) to field value (string). </p></dd>
  3219.  
  3220. </dl>
  3221.  
  3222. <p> The function must modify <code class="source">issue</code> so that
  3223. it is a valid issue for creation in the defect tracker, by supplying
  3224. values for the defect tracker's required fields.  The function should do
  3225. so by modifying <code class="source">issue</code> as far as possible
  3226. automatically, then calling the function given by the <a
  3227. href="../ag/index.html#config-prepare_issue"><code
  3228. class="source">prepare_issue</code></a> configuration parameter, passing
  3229. the modified <code class="source">issue</code> and <code
  3230. class="source">job</code> arguments. </p>
  3231.  
  3232. <p> You need not supply this function in the replicator configuration if
  3233. you don't support replication of jobs from Perforce to the defect
  3234. tracker. </p>
  3235.  
  3236.  
  3237. <h4><a id="config-text_translator" name="config-text_translator"><code class="source">text_translator</code></a></h4>
  3238.  
  3239. <p> A text translator instance (see <a href="#section-7.5.3">section 7.5.3</a>). </p>
  3240.  
  3241.  
  3242. <h4><a id="config-translate_jobspec_advanced" name="config-translate_jobspec_advanced"><code class="source">translate_jobspec_advanced(config, dt, p4, job)</code></a></h4>
  3243.  
  3244. <p> (The <code class="source">translate_jobspec_advanced</code> function
  3245. belongs to the <a href="#feature-migrate_issues">migrate_issues</a>
  3246. feature.) </p>
  3247.  
  3248. <p> A function to translate a job from the old jobspec (before
  3249. migration) to the new jobspec (after migration, suitable for
  3250. replication).  The function takes 4 arguments; the <code
  3251. class="source">config</code>, <code class="source">dt</code> and <code
  3252. class="source">p4</code> arguments are the same as for <a
  3253. href="#config-prepare_issue_advanced"><code
  3254. class="source">prepare_issue_advanced</code></a>.  The <code
  3255. class="source">job</code> argument is the old job, in the form of a
  3256. dictionary mapping field name to field value.  The new job must be
  3257. returned in the same form (it's OK to update the argument and return
  3258. that). </p>
  3259.  
  3260. <p> You need not supply this function in the replicator configuration if
  3261. you don't support migration of jobs from Perforce to the defect
  3262. tracker. </p>
  3263.  
  3264.  
  3265. <h4><a id="config-user_translator" name="config-user_translator"><code class="source">user_translator</code></a></h4>
  3266.  
  3267. <p> A user translator instance (see <a href="#section-7.5.4">section 7.5.4</a>). </p>
  3268.  
  3269.  
  3270. <h3><a id="section-8.4" name="section-8.4">8.4. Perforce jobspecs</a></h3>
  3271.  
  3272. <p> The configuration generator must build a Perforce jobspec that
  3273. matches the <a href="#config-field_map"><code
  3274. class="source">field_map</code></a> configuration parameter that it
  3275. generates.  This must be communicated to the replicator as the <a
  3276. href="#config-jobspec"><code class="source">jobspec</code></a>
  3277. configuration parameter. </p>
  3278.  
  3279. <p> The jobspec must be represented by a tuple with two elements: </p>
  3280.  
  3281. <ol>
  3282.  
  3283.   <li><p> An introductory comment, in the form of a string starting with
  3284.   <code class="source">"#"</code>. </p></li>
  3285.  
  3286.   <li><p> A list of field definitions.  Each field definition must be a
  3287.   tuple of eight elements.  See [<a title="Perforce 2001.1 System
  3288.   Administrator's Guide"
  3289.   href="http://www.perforce.com/perforce/doc.031/manuals/p4sag/05_jobspec.html">Perforce
  3290.   2003-07-15b, 5</a>] for the full details of job specifications. </p>
  3291.  
  3292.   <ol type="a">
  3293.  
  3294.     <li><p> A unique integer identifier by which this field is indexed.
  3295.     Must be between 101 and 199. </p></li>
  3296.  
  3297.     <li><p> The name of the field as it appears in the job
  3298.     form. </p></li>
  3299.  
  3300.     <li><p> The field datatype (<code class="source">"word"</code>, <code
  3301.     class="source">"text"</code>, <code class="source">"line"</code>,
  3302.     <code class="source">"select"</code>, or <code
  3303.     class="source">"date"</code>). </p></li>
  3304.  
  3305.     <li><p> The recommended size of the field's text box as displayed in
  3306.     P4Win. </p></li>
  3307.  
  3308.     <li><p> The field disposition: </p>
  3309.  
  3310.     <ul>
  3311.  
  3312.       <li><p><code class="source">"optional"</code>: field can take any
  3313.       value or can be deleted. </p></li>
  3314.  
  3315.       <li><p><code class="source">"default"</code>: a default value is
  3316.       provided, but it can be changed or erased. </p></li>
  3317.  
  3318.       <li><p><code class="source">"required"</code>: a default is given;
  3319.       it can be changed but the field can't be left empty. </p></li>
  3320.  
  3321.       <li><p><code class="source">"once"</code>: read-only; the field is
  3322.       set once to a default value and is never changed. </p></li>
  3323.  
  3324.       <li><p><code class="source">"always"</code>: read-only; the field
  3325.       value is reset to the default value when the job is saved. </p></li>
  3326.  
  3327.     </ul></li>
  3328.  
  3329.     <li><p> The default value for the field, if any, or <code
  3330.     class="source">None</code> if there is no default value (this is
  3331.     called "Preset" in the Perforce jobspec). </p></li>
  3332.  
  3333.     <li><p> The legal values for the field, if type is <code
  3334.     class="source">"select"</code>, or <code class="source">None</code>
  3335.     for other types.  Join the values into a string, separating them with
  3336.     slashes.  For example, <code
  3337.     class="source">"open/closed/suspended"</code>. </p></li>
  3338.  
  3339.     <li><p> A string describing the field, or <code
  3340.     class="source">None</code> if you have nothing to say about the field.
  3341.     Don't start it with a <code class="source">"#"</code>. </p></li>
  3342.  
  3343.   </ol></li>
  3344.  
  3345. </ol>
  3346.  
  3347. <p> Perforce requires that five fields be present in the jobspec: </p>
  3348.  
  3349. <ol>
  3350.  
  3351.   <li><p> The jobname <code class="source">(101, "Job", "word", 32,
  3352.   "required", None, None, "The job name.")</code>.  This must not be
  3353.   replicated. </p></li>
  3354.  
  3355.   <li><p> The status of the job (field 102).  This should be replicated
  3356.   from the defect tracker.  It should have type <code
  3357.   class="source">"select"</code>.  Its values should include all the
  3358.   statuses for issues in the defect tracker, converted using the state
  3359.   translator (see <a href="#section-7.5.2">section 7.5.2</a>). </p></li>
  3360.  
  3361.   <li><p> The owner of the job (field 103).  This should be replicated
  3362.   from the defect tracker.  It should have type <code
  3363.   class="source">"word"</code>. </p></li>
  3364.  
  3365.   <li><p> The date the job was last modified <code class="source">(104,
  3366.   "Date", "date", 20, "always", "$now", None, "The date this job was
  3367.   last modified.")</code>.  This must not be replicated. </p></li>
  3368.  
  3369.   <li><p> The title (field 105).  This should be replicated from the
  3370.   defect tracker.  It should have type <code
  3371.   class="source">"line"</code> or <code
  3372.   class="source">"text"</code>. </p></li>
  3373.  
  3374. </ol>
  3375.  
  3376. <blockquote><p> <i>Example.</i> In the Bugzilla integration, Perforce's
  3377. five required fields are specified in the jobspec like this:
  3378. </p></blockquote>
  3379.  
  3380. <blockquote><pre class="source">
  3381. (101, "Job", "word", 32, "required", None, None, "The job name."),
  3382. (102, "Status", "select", 11, "required", "unconfirmed", "unconfirmed/bugzilla_new/assigned/reopened/closed/verified/bugzilla_closed", " The bug's status."),
  3383. (103, "Assigned_To", "word", 255, "required", "$user", None, "User to which the bug is assigned."),
  3384. (104, "Date", "date", 20, "always", "$now", None, "The date this job was last modified."),
  3385. (105, "Summary", "text", 0, "required", "$blank", None, "The bug's summary"),
  3386. </pre></blockquote>
  3387.  
  3388. <p> The replicator requires that four fields be present [<a
  3389. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/#section-4">GDR
  3390. 2000-09-13, 4</a>].  These should appear in the jobspec as follows: </p>
  3391.  
  3392. <blockquote><pre class="source">
  3393. (191, "P4DTI-filespecs", "text", 0, "optional", None, None, "Associated filespecs."),
  3394. (192, "P4DTI-rid", "word", 32, "required", "None", None, "P4DTI replicator identifier. Do not edit!"),
  3395. (193, "P4DTI-issue-id", "word", 32, "required", "None", None, "Bugzilla issue database identifier. Do not edit!"),
  3396. (194, "P4DTI-user", "word", 32, "always", "$user", None, "Last user to edit this job. You can't edit this!"),
  3397. </pre></blockquote>
  3398.  
  3399. <p> These fields have high numbers so that they appear at the bottom of
  3400. the jobspec where people don't have to look at them. </p>
  3401.  
  3402. <p> The remainder of the jobspec should be filled in with the fields
  3403. that the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
  3404. administrator has specified for replication in the <a
  3405. href="../ag/index.html#config-replicated_fields-Bugzilla"><code
  3406. class="source">replicated_fields</code></a> configuration parameter.
  3407. Make sure that the values for "select" fields are legal in Perforce (see
  3408. <a href="#section-7.5.2">section 7.5.2</a>). </p>
  3409.  
  3410. <p> For more information about jobspecs, see Chapter 5, "Customizing
  3411. Perforce: Job Specifications", in the <cite>Perforce System
  3412. Administrator's Guide</cite> [<a
  3413. href="http://www.perforce.com/perforce/doc.031/manuals/p4sag/05_jobspec.html">Perforce
  3414. 2003-07-15b, 5</a>]. </p>
  3415.  
  3416.  
  3417. <h3><a id="section-8.5" name="section-8.5">8.5. Adapting the configuration module</a></h3>
  3418.  
  3419. <p> If your defect tracker module (see <a href="#section-7">section
  3420. 7</a>) requires the <abbr title="Perforce Defect Tracking
  3421. Integration">P4DTI</abbr> administrator to specify any configuration
  3422. parameters (such as the name of the host on which the defect tracker
  3423. runs, or the user to connect to the database as), then you must adapt
  3424. the <a href="http://www.ravenbrook.com/project/p4dti/version/2.2/code/replicator/config.py"><code
  3425. class="filename">config.py</code></a> module, as follows. </p>
  3426.  
  3427. <ol>
  3428.  
  3429.   <li><p> Add a new <code class="source"># dt_name =
  3430.   "<i>Defect_Tracker</i>"</code> line near the start of section 2, to
  3431.   indicate that your defect tracker integration is available. </p></li>
  3432.  
  3433.   <li><p> Add a new subsection to section 3, starting <code
  3434.   class="source">elif dt_name == "<i>Defect_Tracker</i>":</code>.  This
  3435.   should contain default values for the configuration parameters
  3436.   required only by your integration. </p></li>
  3437.  
  3438.   <li><p> Add a history entry to Appendix B explaining what you've
  3439.   done. </p></li>
  3440.  
  3441. </ol>
  3442.  
  3443.  
  3444. <h3><a id="section-8.6" name="section-8.6">8.6. Making your own configurations</a></h3>
  3445.  
  3446. <p><strong>Warning: The configuration methods in this section are not
  3447. supported by Perforce or TeamShare.</strong></p>
  3448.  
  3449. <p> This section describes techniques you can use if you want to adapt a
  3450. supported integration to do something that's not supported.  Here are
  3451. some of the things that are possible by making your own
  3452. configuration. </p>
  3453.  
  3454. <ul>
  3455.  
  3456. <li> Connecting a defect tracker to multiple Perforce servers. </li>
  3457.  
  3458. <li> Fine control over which defect tracker issues are replicated to
  3459. Perforce. </li>
  3460.  
  3461. <li> Arbitrary translation of issue data between the defect tracker and
  3462. Perforce (see <a href="#section-8.6.2">section 8.6.2</a>). </li>
  3463.  
  3464. <li> Queries based on combined defect tracker and Perforce data. </li>
  3465.  
  3466. <li> Working with locally customized versions of Bugzilla. </li>
  3467.  
  3468. <li> Redirection or fine control of logging. </li>
  3469.  
  3470. <li> Arbitrary mappings between Perforce and defect tracker user
  3471. names. </li>
  3472.  
  3473. <li> Alternative policies for handling conflicts between defect tracker
  3474. and Perforce changes to issues. </li>
  3475.  
  3476. </ul>
  3477.  
  3478.  
  3479. <h4><a id="section-8.6.1" name="section-8.6.1">8.6.1. Steps to making your own configuration</a></h4>
  3480.  
  3481. <p> Here's are the steps you need to follow to make your own
  3482. configuration: </p>
  3483.  
  3484. <ol>
  3485.  
  3486.   <li><p> Choose a name for your configuration: <i>my_configuration</i>,
  3487.   say. </p></li>
  3488.  
  3489.   <li><p> Edit <code class="filename">config.py</code>, adding the
  3490.   line</p>
  3491.  
  3492.   <blockquote><code
  3493.   class="source">configure_name='<i>my_configuration</i>'</code></blockquote></li>
  3494.  
  3495.   <li><p> Make a new module <code
  3496.   class="filename">configure_<i>my_configuration</i>.py</code>.
  3497.   </p></li>
  3498.  
  3499.   <li><p> Make your new module into a configuration generator (see <a
  3500.   href="#section-8.1">section 8.1</a>).  See below for some
  3501.   examples. </p></li>
  3502.  
  3503. </ol>
  3504.  
  3505. <p> The best approach to making a configuration generator is to use an
  3506. existing one and modify its output.  That way, you benefit from
  3507. improvements and corrections to the configuration generator in future
  3508. releases of the <abbr title="Perforce Defect Tracking
  3509. Integration">P4DTI</abbr>. </p>
  3510.  
  3511.  
  3512. <h4><a id="section-8.6.2" name="section-8.6.2">8.6.2. Example: custom
  3513. jobspec and translators</a></h4>
  3514.  
  3515. <p> Suppose that you want to use the Bugzilla integration, but you
  3516. have many existing tools and documents that refer to your current
  3517. Perforce jobspec, so don't want the <abbr title="Perforce Defect
  3518. Tracking Integration">P4DTI</abbr> to change your Perforce
  3519. jobspec, or the meaning of values in the job fields. </p>
  3520.  
  3521. <p> First, you must add the fields required by the <abbr title="Perforce
  3522. Defect Tracking Integration">P4DTI</abbr> [<a
  3523. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/#section-4">GDR
  3524. 2000-09-13, 4</a>] to your Perforce jobspec by hand.  The following
  3525. configuration generator achieves this: </p>
  3526.  
  3527. <blockquote><pre class="source">
  3528. import configure_bugzilla
  3529. import message
  3530. import translator
  3531.  
  3532. product = "My configuration"
  3533. error = "My configuration error."
  3534. catalog = {
  3535.     1: (message.ERR, "Unknown Bugzilla status '%s'."),
  3536.     2: (message.ERR, "Unknown Perforce status '%s'."),
  3537. }
  3538. factory = <a href="#section-5.2">message.catalog_factory</a>(catalog, product)
  3539.  
  3540. # A map from state in Bugzilla to status in Perforce.
  3541. state_pairs = [
  3542.     ('NEW', 'new'),
  3543.     ('ASSIGNED', 'open'),
  3544.     ('RESOLVED', 'resolved'),
  3545.     ('CLOSED', 'closed'),
  3546. ] # No support for UNCONFIRMED, REOPENED, or VERIFIED.
  3547.  
  3548. class my_state_translator(<a href="#section-7.5">translator.translator</a>):
  3549.     def translate_0_to_1(self, value, dt0, dt1, issue0 = None, issue1 = None):
  3550.         assert isinstance(value, types.StringType)
  3551.         for (t,p) in state_pairs:
  3552.             if value == t:
  3553.                 return p
  3554.         raise error, factory.new(1, value)
  3555.  
  3556.     def translate_1_to_0(self, value, dt0, dt1, issue0 = None, issue1 = None):
  3557.         assert isinstance(value, types.StringType)
  3558.         for (t,p) in state_pairs:
  3559.             if value == p:
  3560.                 return t
  3561.         raise error, factory.new(2, value)
  3562.  
  3563. def <a href="#configure_dt.configuration">configuration</a>(config):
  3564.     config = configure_bugzilla.<a href="#configure_dt.configuration">configuration</a>(config)
  3565.  
  3566.     # Tell the replicator not to update the jobspec.
  3567.     config.jobspec = None
  3568.  
  3569.     # Make a field_map that works with my existing jobspec.
  3570.     config.field_map = [
  3571.         ('bug_status, 'Status', my_state_translator()),
  3572.         ('assigned_to'', 'User', config.<a href="#config-user_translator">user_translator</a>),
  3573.         ('summary', 'Description', <a href="#section-7.5">translator.translator</a>()),
  3574.         ('longdesc', 'User_Impact', config.<a href="#config-text_translator">text_translator</a>),
  3575.     ]
  3576.  
  3577.     return config
  3578. </pre></blockquote>
  3579.  
  3580. <p> Note the use of coding conventions in this example: message catalogs
  3581. (see <a href="#section-5.2">section 5.2</a>) and raising exceptions when
  3582. a value can't be translated (see <a href="#section-5.4">section
  3583. 5.4</a>). </p>
  3584.  
  3585. <p> <b>Warning.</b> If you leave your Perforce jobspec unchanged, you
  3586. must check that it is compatible with the <abbr title="Perforce Defect
  3587. Tracking Integration">P4DTI</abbr>.  See <a
  3588. href="../ag/index.html#section-5.2.3">section 5.2.3,
  3589. "Handle Perforce jobs and jobspec"</a>, of the <cite><a
  3590. href="../ag/index.html">Perforce Defect Tracking
  3591. Integration Administrator's Guide</a></cite>.</p>
  3592.  
  3593. <p> Check that the "Presets" for each select field is valid for that
  3594. field (that is, it appears as one of the "Values" for that field). </p>
  3595.  
  3596. <p> Some organizations set up a jobspec with a field like this: </p>
  3597.  
  3598. <blockquote><code class="source">
  3599. Fields: 120 Severity select 20 required <br />
  3600. Values: Severity critical/essential/optional <br />
  3601. Presets: Severity setme
  3602. </code></blockquote>
  3603.  
  3604. <p> Their intention is that since "setme" is not a legal value for the
  3605. Severity field, the person submitting the job must give it a value; they
  3606. can't just ignore it and leave it with the default value. </p>
  3607.  
  3608. <p> However, this won't work with the <abbr title="Perforce Defect
  3609. Tracking Integration">P4DTI</abbr>, because the command <code
  3610. class="command">p4 -G job -o</code> won't even give you a blank job
  3611. form; instead it gives you an error message. </p>
  3612.  
  3613. <h2><a id="section-9" name="section-9">9. Building and testing</a></h2>
  3614.  
  3615. <p> To build the <abbr title="Perforce Defect Tracking
  3616. Integration">P4DTI</abbr>, follow the release build procedure [<a
  3617. title="Perforce Defect Tracking Integration Release Build Procedure"
  3618. href="http://www.ravenbrook.com/project/p4dti/version/2.2/procedure/release-build/">GDR
  3619. 2000-10-17</a>].  This procedure uses automated support from the <a
  3620. href="http://www.ravenbrook.com/project/p4dti/version/2.2/tool/build.py"><code
  3621. class="filename">build.py</code></a> tool; this is documented in [<a
  3622. title="Build automation design"
  3623. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/build/">GDR 2001-07-13</a>]. </p>
  3624.  
  3625. <p> You may adapt these three documents so that your new integration
  3626. built by the same procedure as the other integrations in the <abbr
  3627. title="Perforce Defect Tracking Integration">P4DTI</abbr>. </p>
  3628.  
  3629. <p> To test the <abbr title="Perforce Defect Tracking
  3630. Integration">P4DTI</abbr>, follow the release test procedure [<a
  3631. title="Release test procedure"
  3632. href="http://www.ravenbrook.com/project/p4dti/version/2.2/procedure/release-test/">RB
  3633. 2001-03-21</a>].  This uses the sample data and automated tests in the
  3634. <a href="http://www.ravenbrook.com/project/p4dti/version/2.2/test/"><code
  3635. class="filename">test/</code></a> directory of the integration kit.  See
  3636. [<a title="Test design"
  3637. href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/test/">GDR 2001-07-02</a>] for
  3638. the test design. </p>
  3639.  
  3640. <p> You may adapt the existing tests so that they test your
  3641. integration. </p>
  3642.  
  3643.  
  3644. <h2><a id="section-10" name="section-10">10. Providing a defect tracker interface to Perforce relations</a></h2>
  3645.  
  3646. <p> The defect tracker should display, for each issue that is
  3647. replicated, a description of the Perforce server to which the issue is
  3648. replicated.  Use the configuration parameter <a
  3649. href="../ag/index.html#config-p4_server_description"><code
  3650. class="source">p4_server_description</code></a> which you should have
  3651. stored in a table in the defect tracker (see <a
  3652. href="#section-4.5">section 4.5</a>). </p>
  3653.  
  3654. <p> The defect tracker should display the jobname of the job to which
  3655. the issue is replicated.  The jobname should be a link to the <abbr
  3656. title="Universal Resource Locator">URL</abbr> given by the <a
  3657. href="../ag/index.html#config-job_url"><code
  3658. class="source">job_url</code></a> configuration parameter, with the
  3659. jobname inserted.  This configuration parameter is defined in the
  3660. <cite>Administrator's Guide</cite> as being suitable for passing to
  3661. <code class="source">sprintf</code> as the format string: it must have
  3662. one <code class="source">%s</code> format specified (for which the
  3663. jobname is substituted) and it may have any number of doubled percent
  3664. signs <code class="source">%%</code> (which must become single percent
  3665. signs in the resulting <abbr title="Universal Resource
  3666. Locator">URL</abbr>) [<a
  3667. href="../ag/index.html#section-5.1">RB 2000-08-10a,
  3668. 5.1</a>]. </p>
  3669.  
  3670. <p> The defect tracker should display on each issue description page a
  3671. table of fixes for that issue (if there are any).  The table should look
  3672. like the table below. </p>
  3673.  
  3674. <table border="1" cellspacing="0" cellpadding="5">
  3675.  
  3676. <tr valign="top" align="left">
  3677.  
  3678.   <th>Change</th>
  3679.  
  3680.   <th>Effect</th>
  3681.  
  3682.   <th>Date</th>
  3683.  
  3684.   <th>User</th>
  3685.  
  3686.   <th>Description</th>
  3687.  
  3688. </tr>
  3689.  
  3690. <tr valign="top">
  3691.  
  3692.   <td><a href="http://info.ravenbrook.com/infosys/cgi/perfbrowse.cgi?@describe+5493">5493</a></td>
  3693.  
  3694.   <td>open</td>
  3695.  
  3696.   <td>2000-12-05</td>
  3697.  
  3698.   <td>GDR</td>
  3699.  
  3700.   <td>Added replicator method mail_concerning_job for e-mailing people about a job.</td>
  3701.  
  3702. </tr>
  3703.  
  3704. <tr valign="top">
  3705.  
  3706.   <td><a href="http://info.ravenbrook.com/infosys/cgi/perfbrowse.cgi?@describe+5524">5524</a></td>
  3707.  
  3708.   <td>open</td>
  3709.  
  3710.   <td>2000-12-06</td>
  3711.  
  3712.   <td>GDR</td>
  3713.  
  3714.   <td>Fixed the replicator's user_email_address method so that it really returns None when there is no such user.</td>
  3715.  
  3716. </tr>
  3717.  
  3718. <tr valign="top">
  3719.  
  3720.   <td><a href="http://info.ravenbrook.com/infosys/cgi/perfbrowse.cgi?@describe+5541">5541</a></td>
  3721.  
  3722.   <td>open</td>
  3723.  
  3724.   <td>2000-12-06</td>
  3725.  
  3726.   <td>GDR</td>
  3727.  
  3728.   <td>If the owner of a job and the person who last changed it are the same, include them only once in any e-mail sent by the replicator about that job.</td>
  3729.  
  3730. </tr>
  3731.  
  3732. <tr valign="top">
  3733.  
  3734.   <td><a href="http://info.ravenbrook.com/infosys/cgi/perfbrowse.cgi?@describe+5634">5634</a> (pending)</td>
  3735.  
  3736.   <td>closed</td>
  3737.  
  3738.   <td>2000-12-07</td>
  3739.  
  3740.   <td>GDR</td>
  3741.  
  3742.   <td>Merging back to master sources.</td>
  3743.  
  3744. </tr>
  3745.  
  3746. </table>
  3747.  
  3748.  
  3749. <p> Points to note about this table: </p>
  3750.  
  3751. <ol>
  3752.  
  3753.   <li><p> Pending changelists are distinguished from submitted
  3754.   changelists.  This is important because the effect of a pending
  3755.   changelist does not happen until the changelist is submitted.  So in
  3756.   the above table the status of the job is still "open" but it is
  3757.   understood that when changelist 5634 is submitted it becomes
  3758.   "closed". </p></li>
  3759.  
  3760.   <li><p> The user and date are for the change (not for the fix).
  3761.   Knowing when the change was made and by whom is much more important
  3762.   than knowing when the change was linked with the job. </p></li>
  3763.  
  3764.   <li><p> The user is the defect tracker user who corresponds to the
  3765.   Perforce user who made the change. </p></li>
  3766.  
  3767.   <li><p> The change number is a link to the <abbr title="Universal
  3768.   Resource Locator">URL</abbr> given by the <a
  3769.   href="../ag/index.html#config-changelist_url"><code
  3770.   class="source">changelist_url</code></a> configuration parameter, with
  3771.   the change number inserted.  This configuration parameter is defined
  3772.   in the <cite>Administrator's Guide</cite> as being suitable for
  3773.   passing to <code class="source">sprintf</code> as the format string:
  3774.   it must have one <code class="source">%d</code> format specified (for
  3775.   which the change number is substituted) and it may have any number of
  3776.   doubled percent signs <code class="source">%%</code> (which must
  3777.   become single percent signs in the resulting <abbr title="Universal
  3778.   Resource Locator">URL</abbr>) [<a
  3779.   href="../ag/index.html#section-5.1">RB
  3780.   2000-08-10a, 5.1</a>]. </p></li>
  3781.  
  3782.   <li><p> All the fixes for an issue are replicated by the same
  3783.   replicator and from the same Perforce server as the issue itself.  So
  3784.   when building this table you only need to select records with the same
  3785.   replicator identifier and Perforce server identifier as the
  3786.   issue. </p></li>
  3787.  
  3788.   <li><p> A single defect tracker may replicate issues to several
  3789.   Perforce servers (see <a href="#section-4">section 4</a>).  Each
  3790.   Perforce server has a different changelist URL.  So it is important to
  3791.   select the URL for the correct Perforce server (namely the one to
  3792.   which the issue is replicated) when making this table. </p></li>
  3793.  
  3794. </ol>
  3795.  
  3796.  
  3797. <h2><a id="section-11" name="section-11">11. Adapting the manuals</a></h2>
  3798.  
  3799. <p> When adding material relating to your defect tracker to the manuals,
  3800. surround each section with the <abbr title="Hypertext Markup Language">HTML</abbr> tags <code class="source">&lt;div
  3801. class="<i>defect_tracker</i>"&gt;</code> and <code
  3802. class="source">&lt;/div&gt;</code>.  This makes the material for a
  3803. particular defect tracker easy to find, extract and check, to meet <a
  3804. href="http://www.ravenbrook.com/project/p4dti/req/#req-32">requirement 32</a>. </p>
  3805.  
  3806. <p> You must adapt the <cite>Perforce Defect Tracking Integration
  3807. Administrator's Guide</cite> [<a href="../ag/index.html">RB 2000-08-10a</a>] to
  3808. describe your integration, as described in the list below. </p>
  3809.  
  3810. <ol>
  3811.  
  3812.   <li><p> Add a new subsection to section 3, specifying the software and
  3813.   procedural prerequisites for using your defect tracker with the <abbr
  3814.   title="Perforce Defect Tracking Integration">P4DTI</abbr>. </p></li>
  3815.  
  3816.   <li><p> If your integration requires a new installation procedure, or
  3817.   installs on a new platform, update section 4. </p></li>
  3818.  
  3819.   <li><p> Add your new configuration parameters to section
  3820.   5.1. </p></li>
  3821.  
  3822.   <li><p> Add a new subsection to section 5, explaining how to configure
  3823.   your defect tracker for the <abbr title="Perforce Defect Tracking
  3824.   Integration">P4DTI</abbr>. </p></li>
  3825.  
  3826.   <li><p> Add a new item to the list in section 10, explaining how to
  3827.   uninstall your integration and return your defect tracker to its
  3828.   original state. </p></li>
  3829.  
  3830.   <li><p> Add the error messages that your code can produce to section
  3831.   11.2 (include the product, message identifier and check digit just
  3832.   like the other errors messages in that section). </p></li>
  3833.  
  3834.   <li><p> Add likely error messages from systems with which your code
  3835.   interacts to section 11.3 (for example, errors from the defect
  3836.   tracker, or from your database interface). </p></li>
  3837.  
  3838.   <li><p> Add references to documentation for your defect tracker, and
  3839.   any other supporting materials that you referred to, to appendix
  3840.   A. </p></li>
  3841.  
  3842.   <li><p> Add a history entry to appendix B explaining what you've
  3843.   done. </p></li>
  3844.  
  3845. </ol>
  3846.  
  3847. <p> If you provided an interface from your defect tracker to the
  3848. Perforce fixes relation (see <a href="#section-10">section 10</a>), then you must
  3849. adapt the <cite>Perforce Defect Tracking Integration User's Guide</cite>
  3850. [<a href="../ug/index.html">RB 2000-08-10b</a>] to describe your integration, as
  3851. follows: </p>
  3852.  
  3853. <ol start="10">
  3854.  
  3855.   <li><p> Add a paragraph to section 10.3 explaining how to access
  3856.   Perforce fixes from the defect tracker. </p></li>
  3857.  
  3858. </ol>
  3859.  
  3860.  
  3861. <h2><a id="section-12" name="section-12">12. Making your work available to the community</a></h2>
  3862.  
  3863.  
  3864. <h3><a id="section-12.1" name="section-12.1">12.1. Reporting defects</a></h3>
  3865.  
  3866. <p> Defects in the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> Kit include (but aren't limited
  3867. to): </p>
  3868.  
  3869. <ul>
  3870.  
  3871.   <li><p> An essential piece of information can't be found in this
  3872.   manual or in the design documents it refers to. </p></li>
  3873.  
  3874.   <li><p> Inconsistencies between this manual, the design documents it
  3875.   refers to, and the sources they document. </p></li>
  3876.  
  3877.   <li><p> Defects in the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> sources or in the test
  3878.   cases. </p></li>
  3879.  
  3880. </ul>
  3881.  
  3882. <p> Please report any defects you find to <a
  3883. href="http://www.perforce.com/perforce/support.html">Perforce support</a>, so
  3884. that they can be fixed and the product improved. </p>
  3885.  
  3886. <p> Please provide the following information with your defect report:
  3887. </p>
  3888.  
  3889. <ol>
  3890.  
  3891.   <li><p> The release of the <abbr title="Perforce Defect Tracking
  3892.   Integration">P4DTI</abbr> Kit you are using (look in the <code
  3893.   class="filename">readme.txt</code> that came with the <abbr
  3894.   title="Perforce Defect Tracking Integration">P4DTI</abbr> Kit to
  3895.   identify the release). </p></li>
  3896.  
  3897.   <li><p> The name and release of the defect tracker you are integrating
  3898.   with. </p></li>
  3899.  
  3900.   <li><p> If you're reporting a defect in documentation: </p>
  3901.  
  3902.   <ol type="a">
  3903.  
  3904.     <li><p> What you're trying to do. </p></li>
  3905.  
  3906.     <li><p> The information you need. </p></li>
  3907.  
  3908.     <li><p> Where you expected to find it. </p></li>
  3909.  
  3910.     <li><p> Where else you looked for it. </p></li>
  3911.  
  3912.   </ol></li>
  3913.  
  3914.   <li><p> If you're reporting a defect in the code: </p>
  3915.  
  3916.   <ol type="a">
  3917.  
  3918.     <li><p> What you did immediately prior to the defect's
  3919.     occurrence. </p></li>
  3920.  
  3921.     <li><p> What you think should have happened. </p></li>
  3922.  
  3923.     <li><p> What actually happened. </p></li>
  3924.  
  3925.     <li><p> The Perforce release you are using. </p></li>
  3926.  
  3927.     <li><p> Any source code you've added or modified, including your
  3928.     <code class="filename">config.py</code> file. </p></li>
  3929.  
  3930.     <li><p> A section of the <abbr title="Perforce Defect Tracking
  3931.     Integration">P4DTI</abbr> log that includes the error that you're
  3932.     reporting and some context around that error. </p></li>
  3933.  
  3934.     <li><p> Copies of any related e-mail messages generated by the <abbr
  3935.     title="Perforce Defect Tracking Integration">P4DTI</abbr>. </p></li>
  3936.  
  3937.   </ol></li>
  3938.  
  3939. </ol>
  3940.  
  3941.  
  3942. <h3><a id="section-12.2" name="section-12.2">12.2. Making a contribution</a></h3>
  3943.  
  3944. <p> Please send your contributions (fixes, adaptions and extensions) to
  3945. <a href="http://www.perforce.com/perforce/support.html">Perforce
  3946. support</a>.  Please include the following: </p>
  3947.  
  3948. <ol>
  3949.  
  3950.   <li><p> A description of your contribution: what it is designed to
  3951.   achieve; which files you've changed; which files you've
  3952.   added. </p></li>
  3953.  
  3954.   <li><p> The release of the <abbr title="Perforce Defect Tracking
  3955.   Integration">P4DTI</abbr> Kit you have been developing against (look
  3956.   in the <code class="filename">readme.txt</code> that came with the
  3957.   <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> Kit to
  3958.   identify the release). </p></li>
  3959.  
  3960.   <li><p> The complete <abbr title="Perforce Defect Tracking
  3961.   Integration">P4DTI</abbr> Kit, including your modifications and
  3962.   additions.  Make a tarball or a ZIP archive of the whole <abbr
  3963.   title="Perforce Defect Tracking Integration">P4DTI</abbr> Kit
  3964.   directory.  (Please do this even if you've only changed a couple of
  3965.   files.  This allows us to add your contribution to Perforce and use
  3966.   <code class="command">p4 diff2</code> to see exactly what changes
  3967.   you've made.) </p></li>
  3968.  
  3969.   <li><p> What you are prepared for us to do with your contribution.
  3970.   Are you willing for us to make it available for distribution from
  3971.   Perforce or Ravenbrook's web site?  Are you willing for us to
  3972.   incorporate it into the <abbr title="Perforce Defect Tracking
  3973.   Integration">P4DTI</abbr> and maintain and support it?  Have you made
  3974.   it available under an open source license? </p></li>
  3975.  
  3976. </ol>
  3977.  
  3978.  
  3979. <h2><a id="section-13" name="section-13">13. Changes since previous releases</a></h2>
  3980.  
  3981. <p> This section lists significant changes in the specification that a
  3982. defect tracker has to meet.  Changes are upwards compatible (in the
  3983. sense that a defect tracker module that worked with the previous release
  3984. of the integration kit will work with the new release) unless stated
  3985. otherwise. </p>
  3986.  
  3987.  
  3988. <h3><a id="section-13.1" name="section-13.1">13.1. Changes since release 1.1.1</a></h3>
  3989.  
  3990. <ul>
  3991.  
  3992.   <li><p> The <a href="#defect_tracker.all_issues"><code
  3993.   class="source">all_issues</code></a> and <a
  3994.   href="#defect_tracker.changed_entities"><code
  3995.   class="source">changed_entities</code></a> methods of the <code
  3996.   class="source">defect_tracker</code> class (see <a
  3997.   href="#section-7.1">section 7.1</a>) must now return cursors (see <a
  3998.   href="#section-7.6">section 7.6</a>), not lists of issues. </p>
  3999.  
  4000.   <p> The purpose of this change is to allow the replicator to work if
  4001.   there are more issues in the defect tracker than fit into memory, thus
  4002.   fixing <a
  4003.   href="http://www.ravenbrook.com/project/p4dti/issue/job000277/">job000277</a>. </p>
  4004.  
  4005.   <p> The release 1.1.1 specification for these two methods (returning
  4006.   lists of issues) is still supported in version 1.4 of the <abbr
  4007.   title="Perforce Defect Tracking Integration">P4DTI</abbr>, but this
  4008.   support will be removed in later releases. </p></li>
  4009.  
  4010.   <li><p> The <a href="#defect_tracker.all_issues"><code
  4011.   class="source">all_issues</code></a> method of the <code
  4012.   class="source">defect_tracker</code> class (see <a
  4013.   href="#section-7.1">section 7.1</a>) must return all issues replicated
  4014.   by this replicator, regardless of when they were last modified. </p>
  4015.  
  4016.   <p>The purpose of this change is to fix <a
  4017.   href="http://www.ravenbrook.com/project/p4dti/issue/job000340/">job000340</a>.
  4018.   </p>
  4019.  
  4020.   <p> This is an incompatible change. </p></li>
  4021.  
  4022. </ul>
  4023.  
  4024.  
  4025. <h3><a id="section-13.2" name="section-13.2">13.2. Changes since release 1.1.6</a></h3>
  4026.  
  4027. <ul>
  4028.  
  4029.   <li><p> The <a href="#user_translator.unmatched_users"><code
  4030.   class="source">unmatched_users</code></a> method in the <a
  4031.   href="#section-7.5.4">user translator class</a> may return an 8-tuple
  4032.   instead of a 4-tuple.  The extra elements of the tuple allow the
  4033.   replicator to report duplicate e-mail addresses. </p>
  4034.  
  4035.   <p> The purpose of this change is to fix <a
  4036.   href="http://www.ravenbrook.com/project/p4dti/issue/job000308/">job000308</a>. </p></li>
  4037.  
  4038. </ul>
  4039.  
  4040.  
  4041. <h3><a id="section-13.3" name="section-13.3">13.3. Changes since release 1.2.1</a></h3>
  4042.  
  4043. <ul>
  4044.  
  4045.   <li><p> The <a href="#section-7.1"><code
  4046.   class="source">defect_tracker</code></a> class has six new methods:
  4047.   <a href="#defect_tracker.add_user"><code
  4048.   class="source">add_user</code></a>, <a
  4049.   href="#defect_tracker.new_issue"><code
  4050.   class="source">new_issue</code></a>, <a
  4051.   href="#defect_tracker.new_issues_start"><code
  4052.   class="source">new_issues_start</code></a>, <a
  4053.   href="#defect_tracker.new_issues_end"><code
  4054.   class="source">new_issues_end</code></a>, <a
  4055.   href="#defect_tracker.poll_start"><code
  4056.   class="source">poll_start</code></a>, and <a
  4057.   href="#defect_tracker.poll_end"><code
  4058.   class="source">poll_end</code></a>. </p>
  4059.  
  4060.   <p> The <a href="#section-7.2"><code
  4061.   class="source">defect_tracker_issue</code></a> class has the new
  4062.   methods: <a href="#defect_tracker_issue.delete"><code
  4063.   class="source">delete</code></a>. </p>
  4064.  
  4065.   <p> The purpose of this change is to support migration from Perforce
  4066.   jobs and users (<a
  4067.   href="http://www.ravenbrook.com/project/p4dti/issue/job000022/">job000022</a>), creation of new
  4068.   issues in Perforce (<a
  4069.   href="http://www.ravenbrook.com/project/p4dti/issue/job000036/">job000036</a>), and releasing
  4070.   of defect tracker locks (<a
  4071.   href="http://www.ravenbrook.com/project/p4dti/issue/job000306/">job000306</a>). </p>
  4072.  
  4073.   <p> These methods are optional: you may omit them if you don't support
  4074.   migration or creation of new issues in Perforce. </p></li>
  4075.  
  4076.   <li><p> The replicator configuration (<a href="#section-8.3">section
  4077.   8.3</a>) has two new parameters: <a
  4078.   href="#config-prepare_issue_advanced"><code
  4079.   class="source">prepare_issue_advanced</code></a> and <a
  4080.   href="#config-translate_jobspec_advanced"><code
  4081.   class="source">translate_jobspec_advanced</code></a>.
  4082.   </p>
  4083.  
  4084.   <p> The purpose of this change is to support migration from Perforce
  4085.   jobs (<a href="http://www.ravenbrook.com/project/p4dti/issue/job000022/">job000022</a>). </p>
  4086.  
  4087.   <p> These methods are optional: you may omit them if you don't support
  4088.   migration of jobs from Perforce to the defect tracker. </p></li>
  4089.  
  4090.   <li><p> The <a href="#configure_dt.configuration"><code
  4091.   class="source">configuration</code></a> function in the configuration
  4092.   generator must return the revised configuration module only (not a
  4093.   tuple of a jobspec description and the revised configuration).  The
  4094.   jobspec description must instead be added to the replicator
  4095.   configuration as the <a href="#config-jobspec"><code
  4096.   class="source">jobspec</code></a> parameter, in the format described
  4097.   in <a href="#section-8.4">section 8.4</a>.
  4098.   </p>
  4099.  
  4100.   <p> This is an incompatible change. </p></li>
  4101.  
  4102. </ul>
  4103.  
  4104.  
  4105. <h3><a id="section-13.4" name="section-13.4">13.4. Changes since release 1.3.3</a></h3>
  4106.  
  4107. <ul>
  4108.  
  4109.   <li><p> The <a href="#section-7.1"><code
  4110.   class="source">defect_tracker</code></a> class has the new method <a
  4111.   href="#defect_tracker.supports"><code
  4112.   class="source">supports</code></a>. </p>
  4113.  
  4114.   <p> In version 1.4 of the <abbr title="Perforce Defect Tracking
  4115.   Integration">P4DTI</abbr>, if you don't provide this method, then the
  4116.   <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> will
  4117.   assume that you support <a href="#feature-filespecs">filespecs</a> and
  4118.   <a href="#feature-fixes">fixes</a> (always), <a
  4119.   href="#feature-new_issues">new_issues</a> (if you implement the <a
  4120.   href="#defect_tracker.new_issue"><code
  4121.   class="source">new_issue</code></a>, <a
  4122.   href="#defect_tracker.new_issues_start"><code
  4123.   class="source">new_issues_start</code></a>, and <a
  4124.   href="#defect_tracker.new_issues_end"><code
  4125.   class="source">new_issues_end</code></a> methods and provide the <a
  4126.   href="#config-prepare_issue_advanced"><code
  4127.   class="source">prepare_issue_advanced</code></a> function in the
  4128.   replicator configuration), <a
  4129.   href="#feature-migrate_issues">migrate_issues</a> (if you support the
  4130.   new_issues feature and provide the <a
  4131.   href="#config-translate_jobspec_advanced"><code
  4132.   class="source">translate_jobspec_advanced</code></a> function in the
  4133.   replicator configuration), and <a
  4134.   href="#feature-new_users">new_users</a> (if you implement the <a
  4135.   href="#defect_tracker.add_user"><code
  4136.   class="source">add_user</code></a> method) features.  In later
  4137.   versions, the <abbr title="Perforce Defect Tracking
  4138.   Integration">P4DTI</abbr> will fail if you don't provide this
  4139.   method. </p></li>
  4140.  
  4141.   <li><p> The <a href="#section-7.2"><code
  4142.   class="source">defect_tracker_issue</code></a> class no longer needs a
  4143.   <code class="source">replicate_p</code> method (this comes from the user
  4144.   configuration and the replicator now calls it directly). </p></li>
  4145.  
  4146. </ul>
  4147.  
  4148.  
  4149. <h3><a id="section-13.5" name="section-13.5">13.5. Changes since release 1.5.3</a></h3>
  4150.  
  4151. <ul>
  4152.  
  4153.   <li><p> The <a href="#section-7.1"><code
  4154.   class="source">defect_tracker</code></a> class has the new method <a
  4155.   href="#defect_tracker.add_replicator_user"><code
  4156.   class="source">add_replicator_user</code></a>. </p></li>
  4157.  
  4158. </ul>
  4159.  
  4160.  
  4161. <h2><a id="section-A" name="section-A">A. References</a></h2>
  4162.  
  4163. <table>
  4164.  
  4165. <tr valign="top">
  4166.  
  4167.   <td>[<a id="ref-GDR-2000-05-03" name="ref-GDR-2000-05-03" href="http://www.ravenbrook.com/project/p4dti/doc/2000-05-03/reqs-and-use-cases/">GDR 2000-05-03</a>]</td>
  4168.  
  4169.   <td>
  4170.     "Requirements and Use Cases for Perforce/Defect Tracking Integration";
  4171.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4172.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4173.     2000-05-03.
  4174.   </td>
  4175.  
  4176. </tr>
  4177.  
  4178. <tr valign="top">
  4179.  
  4180.   <td>[<a id="ref-GDR-2000-05-24" name="ref-GDR-2000-05-24" href="http://www.ravenbrook.com/project/p4dti/req/">GDR 2000-05-24</a>]</td>
  4181.  
  4182.   <td>
  4183.     "Perforce Defect Tracking Integration Project Requirements";
  4184.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4185.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4186.     2000-05-24.
  4187.   </td>
  4188.  
  4189. </tr>
  4190.  
  4191. <tr valign="top">
  4192.  
  4193.   <td>[<a id="ref-GDR-2000-05-30" name="ref-GDR-2000-05-30" href="http://www.ravenbrook.com/project/p4dti/doc/2000-05-30/arch-analysis/">GDR 2000-05-30</a>]</td>
  4194.  
  4195.   <td>
  4196.     "Analysis of architectures for defect tracking integration";
  4197.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4198.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4199.     2000-05-30.
  4200.   </td>
  4201.  
  4202. </tr>
  4203.  
  4204. <tr valign="top">
  4205.  
  4206.   <td>[<a id="ref-GDR-2000-08-08" name="ref-GDR-2000-08-08" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/python-teamtrack-interface/">GDR 2000-08-08</a>]</td>
  4207.  
  4208.   <td>
  4209.     "Python interface to TeamTrack: design";
  4210.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4211.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4212.     2000-08-08.
  4213.   </td>
  4214.  
  4215. </tr>
  4216.  
  4217. <tr valign="top">
  4218.  
  4219.   <td>[<a id="ref-GDR-2000-09-04" name="ref-GDR-2000-09-04" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/teamtrack-p4dti-schema/">GDR 2000-09-04</a>]</td>
  4220.  
  4221.   <td>
  4222.     "TeamTrack database schema extensions for integration with Perforce";
  4223.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4224.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4225.     2000-09-04.
  4226.   </td>
  4227.  
  4228. </tr>
  4229.  
  4230. <tr valign="top">
  4231.  
  4232.   <td>[<a id="ref-GDR-2000-09-13" name="ref-GDR-2000-09-13" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/replicator/">GDR 2000-09-13</a>]</td>
  4233.  
  4234.   <td>
  4235.     "Replicator design";
  4236.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4237.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4238.     2000-09-13.
  4239.   </td>
  4240.  
  4241. </tr>
  4242.  
  4243. <tr valign="top">
  4244.  
  4245.   <td>[<a id="ref-GDR-2000-10-17" name="ref-GDR-2000-10-17" href="http://www.ravenbrook.com/project/p4dti/version/2.2/procedure/release-build/">GDR 2000-10-17</a>]</td>
  4246.  
  4247.   <td>
  4248.     "Perforce Defect Tracking Integration Release Build Procedure";
  4249.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4250.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4251.     2000-10-17.
  4252.   </td>
  4253.  
  4254. </tr>
  4255.  
  4256. <tr valign="top">
  4257.  
  4258.   <td>[<a id="ref-GDR-2001-07-02" name="ref-GDR-2001-07-02" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/test/">GDR 2001-07-02</a>]</td>
  4259.  
  4260.   <td>
  4261.     "Test design";
  4262.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4263.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4264.     2001-07-02.
  4265.   </td>
  4266.  
  4267. </tr>
  4268.  
  4269. <tr valign="top">
  4270.  
  4271.   <td>[<a id="ref-GDR-2001-07-13" name="ref-GDR-2001-07-13" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/build/">GDR 2001-07-13</a>]</td>
  4272.  
  4273.   <td>
  4274.     "Build automation design";
  4275.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4276.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4277.     2001-07-13.
  4278.   </td>
  4279.  
  4280. </tr>
  4281.  
  4282. <tr valign="top">
  4283.  
  4284.   <td>[<a id="ref-GDR-2001-11-14" name="ref-GDR-2001-11-14" href="../aag/index.html">GDR 2001-11-14</a>]</td>
  4285.  
  4286.   <td>
  4287.     "Perforce Defect Tracking Integration Advanced Administrator's Guide";
  4288.     <a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
  4289.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4290.     2001-11-14.
  4291.   </td>
  4292.  
  4293. </tr>
  4294.  
  4295. <tr valign="top">
  4296.  
  4297.   <td>[<a id="ref-ISO-2108" name="ref-ISO-2108">ISO 2108</a>]</td>
  4298.  
  4299.   <td>
  4300.     "ISO 2108: International standard book number (ISBN)";
  4301.     <a href="http://www.iso.ch/">ISO</a>.
  4302.   </td>
  4303.  
  4304. </tr>
  4305.  
  4306. <tr valign="top">
  4307.  
  4308.   <td>[<a id="ref-Lutz-1996" name="ref-Lutz-1996">Lutz 1996</a>]</td>
  4309.  
  4310.   <td>
  4311.     "Programming Python"; Mark Lutz; O'Reilly; 1996-10; ISBN 1-56592-197-6.
  4312.   </td>
  4313.  
  4314. </tr>
  4315.  
  4316. <tr valign="top">
  4317.  
  4318.   <td>[<a id="ref-NB-2000-11-14a" name="ref-NB-2000-11-14a" href="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">NB 2000-11-14a</a>]</td>
  4319.  
  4320.   <td>
  4321.     "Bugzilla database schema";
  4322.     <a href="mailto:nb@ravenbrook.com">Nick Barnes</a>;
  4323.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4324.     2000-11-14.
  4325.   </td>
  4326.  
  4327. </tr>
  4328.  
  4329. <tr valign="top">
  4330.  
  4331.   <td>[<a id="ref-NB-2000-11-14b" name="ref-NB-2000-11-14b" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/bugzilla-p4dti-schema/">NB 2000-11-14b</a>]</td>
  4332.  
  4333.   <td>
  4334.     "Bugzilla database schema extensions for integration with Perforce";
  4335.     <a href="mailto:nb@ravenbrook.com">Nicholas Barnes</a>;
  4336.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4337.     2000-11-14.
  4338.   </td>
  4339.  
  4340. </tr>
  4341.  
  4342. <tr valign="top">
  4343.  
  4344.   <td>[<a id="ref-NB-2000-11-14c" name="ref-NB-2000-11-14c" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/python-bugzilla-interface/">NB 2000-11-14c</a>]</td>
  4345.  
  4346.   <td>
  4347.     "Python interface to Bugzilla: design";
  4348.     <a href="mailto:nb@ravenbrook.com">Nicholas Barnes</a>;
  4349.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4350.     2000-11-14.
  4351.   </td>
  4352.  
  4353. </tr>
  4354.  
  4355. <tr valign="top">
  4356.  
  4357.   <td>[<a id="ref-Perforce-2003-07-15a" name="ref-Perforce-2003-07-15a" href="http://www.perforce.com/perforce/doc.031/manuals/p4guide/">Perforce 2003-07-15a</a>]</td>
  4358.  
  4359.   <td>
  4360.     "Perforce 2003.1 User's Guide";
  4361.     <a href="http://www.perforce.com/">Perforce Software</a>;
  4362.     2003-07-15;
  4363.     &lt;<a href="http://www.perforce.com/perforce/doc.031/manuals/p4guide/">http://www.perforce.com/perforce/doc.031/manuals/p4guide/</a>&gt;, &lt;<a href="http://www.perforce.com/perforce/doc.031/manuals/p4guide/p4guide.pdf">http://www.perforce.com/perforce/doc.031/manuals/p4guide/p4guide.pdf</a>&gt;.
  4364.   </td>
  4365.  
  4366. </tr>
  4367.  
  4368. <tr valign="top">
  4369.  
  4370.   <td>[<a id="ref-Perforce-2003-07-15b" name="ref-Perforce-2003-07-15b" href="http://www.perforce.com/perforce/doc.031/manuals/p4sag/">Perforce 2003-07-15b</a>]</td>
  4371.  
  4372.   <td>
  4373.     "Perforce 2003.1 System Administrator's Guide";
  4374.     <a href="http://www.perforce.com/">Perforce Software</a>;
  4375.     2003-07-15;
  4376.     &lt;<a
  4377.     href="http://www.perforce.com/perforce/doc.031/manuals/p4sag/">http://www.perforce.com/perforce/doc.031/manuals/p4sag/</a>&gt;,
  4378.     &lt;<a
  4379.     href="http://www.perforce.com/perforce/doc.031/manuals/p4sag/p4sag.pdf">http://www.perforce.com/perforce/doc.031
  4380.     /manuals/p4sag/p4sag.pdf</a>&gt;.
  4381.   </td>
  4382.  
  4383. </tr>
  4384.  
  4385. <tr valign="top">
  4386.  
  4387.   <td>[<a id="ref-Purcell-2001-02-12" name="ref-Purcell-2001-02-12" href="http://pyunit.sourceforge.net/">Purcell 2001-02-12</a>]</td>
  4388.  
  4389.   <td>
  4390.     "PyUnit &mdash; a unit testing framework for Python";
  4391.     <a href="mailto:stephen_purcell@yahoo.com">Steve Purcell</a>;
  4392.     2001-02-12.
  4393.   </td>
  4394.  
  4395. </tr>
  4396.  
  4397. <tr valign="top">
  4398.  
  4399.   <td>[<a id="ref-RB-2000-08-10a" name="ref-RB-2000-08-10a" href="../ag/index.html">RB 2000-08-10a</a>]</td>
  4400.  
  4401.   <td>
  4402.     "Perforce Defect Tracking Integration Administrator's Guide";
  4403.     <a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
  4404.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4405.     2000-08-10.
  4406.   </td>
  4407.  
  4408. </tr>
  4409.  
  4410. <tr valign="top">
  4411.  
  4412.   <td>[<a id="ref-RB-2000-08-10b" name="ref-RB-2000-08-10b" href="../ug/index.html">RB 2000-08-10b</a>]</td>
  4413.  
  4414.   <td>
  4415.     "Perforce Defect Tracking Integration User's Guide";
  4416.     <a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
  4417.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4418.     2000-08-10.
  4419.   </td>
  4420.  
  4421. </tr>
  4422.  
  4423. <tr valign="top">
  4424.  
  4425.   <td>[<a id="ref-RB-2000-08-10c" name="ref-RB-2000-08-10c" href="http://www.ravenbrook.com/project/p4dti/version/2.2/design/architecture/">RB 2000-08-10c</a>]</td>
  4426.  
  4427.   <td>
  4428.     "Perforce Defect Tracking Integration Architecture";
  4429.     <a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
  4430.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4431.     2000-08-10.
  4432.   </td>
  4433.  
  4434. </tr>
  4435.  
  4436. <tr valign="top">
  4437.  
  4438.   <td>[<a id="ref-RB-2001-03-07" name="ref-RB-2001-03-07" href="http://www.ravenbrook.com/project/p4dti/procedure/contribution/">RB 2001-03-07</a>]</td>
  4439.  
  4440.   <td>
  4441.     "P4DTI Project Contributions Procedure";
  4442.     <a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
  4443.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4444.     2001-03-07.
  4445.   </td>
  4446.  
  4447. </tr>
  4448.  
  4449. <tr valign="top">
  4450.  
  4451.   <td>[<a id="ref-RB-2001-03-21" name="ref-RB-2001-03-21" href="http://www.ravenbrook.com/project/p4dti/version/2.2/procedure/release-test/">RB 2001-03-21</a>]</td>
  4452.  
  4453.   <td>
  4454.     "Release test procedure";
  4455.     <a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
  4456.     <a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
  4457.     2001-03-21.
  4458.   </td>
  4459.  
  4460. </tr>
  4461.  
  4462. <tr valign="top">
  4463.  
  4464.   <td>[<a id="ref-van-Rossum-2000-10-16" name="ref-van-Rossum-2000-10-16" href="http://www.python.org/doc/current/tut/tut.html">van Rossum 2000-10-16</a>]</td>
  4465.  
  4466.   <td>
  4467.     "Python Tutorial";
  4468.     <a href="mailto:python-docs@python.org">Guido van Rossum</a>;
  4469.     2000-10-16.
  4470.   </td>
  4471.  
  4472. </tr>
  4473.  
  4474. </table>
  4475.  
  4476.  
  4477. <h2><a id="section-B" name="section-B">B. Document History</a></h2>
  4478.  
  4479. <table>
  4480.  
  4481. <tr valign="top">
  4482.  
  4483.   <td>2000-10-16</td>
  4484.  
  4485.   <td><a href="mailto:rb@ravenbrook.com">RB</a></td>
  4486.  
  4487.   <td>Created placeholder after meeting with <a href="mailto:lmb@ravenbrook.com">LMB</a>.</td>
  4488.  
  4489. </tr>
  4490.  
  4491. <tr valign="top">
  4492.  
  4493.   <td>2000-12-10</td>
  4494.  
  4495.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4496.  
  4497.   <td>Drafted sections 3 and 4.</td>
  4498.  
  4499. </tr>
  4500.  
  4501. <tr valign="top">
  4502.  
  4503.   <td>2000-12-11</td>
  4504.  
  4505.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4506.  
  4507.   <td>Drafted sections 2, 5, and 8 and outlined sections 6 and 7.</td>
  4508.  
  4509. </tr>
  4510.  
  4511. <tr valign="top">
  4512.  
  4513.   <td>2000-12-31</td>
  4514.  
  4515.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4516.  
  4517.   <td>The table of fixes in section 8 now distinguishes pending from submitted changes.</td>
  4518.  
  4519. </tr>
  4520.  
  4521. <tr valign="top">
  4522.  
  4523.   <td>2001-01-02</td>
  4524.  
  4525.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4526.  
  4527.   <td>Added section 7.1 (configuration architecture), figure 1, section 7.5 (customized configuration).  Moved text from appendix D of the Administrator's Guide to section 7.5.</td>
  4528.  
  4529. </tr>
  4530.  
  4531. <tr valign="top">
  4532.  
  4533.   <td>2001-02-04</td>
  4534.  
  4535.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4536.  
  4537.   <td>Updated definition of <code class="source">defect_tracker.all_issues</code> method.</td>
  4538.  
  4539. </tr>
  4540.  
  4541. <tr valign="top">
  4542.  
  4543.   <td>2001-02-23</td>
  4544.  
  4545.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4546.  
  4547.   <td>Added <code class="source">corresponding_id</code> method; revised definition of <code class="source">readable_name</code> method.</td>
  4548.  
  4549. </tr>
  4550.  
  4551. <tr valign="top">
  4552.  
  4553.   <td> 2001-03-02 </td>
  4554.  
  4555.   <td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
  4556.  
  4557.   <td> Transferred copyright to Perforce under their license. </td>
  4558.  
  4559. </tr>
  4560.  
  4561. <tr valign="top">
  4562.  
  4563.   <td>2001-03-13</td>
  4564.  
  4565.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4566.  
  4567.   <td>Deleted the recording of conflicts and the need for manual conflict resolution.  Conflict resolution is always immediate.</td>
  4568.  
  4569. </tr>
  4570.  
  4571. <tr valign="top">
  4572.  
  4573.   <td>2001-03-20</td>
  4574.  
  4575.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4576.  
  4577.   <td>Added overviews of requirements, architecture and design. Included replicator block diagram.  Improved links.</td>
  4578.  
  4579. </tr>
  4580.  
  4581. <tr valign="top">
  4582.  
  4583.   <td>2001-03-21</td>
  4584.  
  4585.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4586.  
  4587.   <td>Wrote specifications of the defect tracker and translator
  4588.   classes. Described messages, catalogs, logging and errors.  Moved
  4589.   logging and errors to new section 5 because it's important; renumbered
  4590.   remaining sections; moved configuration adaption to new section
  4591.   8.6.</td>
  4592.  
  4593. </tr>
  4594.  
  4595. <tr valign="top">
  4596.  
  4597.   <td>2001-03-22</td>
  4598.  
  4599.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4600.  
  4601.   <td>Specified the configuration generator; explained how to make your own configuration (with example code); explained how to adapt the manuals.  Gave warning about incompatible jobspecs.  Added prerequisites and where to get help.  Added section on testing.  Added section on code layout.  Explained how to report defects and submit contributions.</td>
  4602.  
  4603. </tr>
  4604.  
  4605. <tr valign="top">
  4606.  
  4607.   <td> 2001-03-29 </td>
  4608.  
  4609.   <td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
  4610.  
  4611.   <td> Changed internal and external cross-references to conform with our other documents.  Tidied up references to requirements.  Removed claims about assigning copyright.  Removed section promising to do particular things with contributions.  Updated references to Perforce manuals to (latest) release 2000.2.  Validated and fixed some broken links.  Sorted references section. </td>
  4612.  
  4613. </tr>
  4614.  
  4615. <tr valign="top">
  4616.  
  4617.   <td>2001-05-17</td>
  4618.  
  4619.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4620.  
  4621.   <td>Updated signatures of <code class="source">all_issues</code> and <code class="source">changed_entities</code>: these methods return cursors, not lists, to work around <a href="http://www.ravenbrook.com/project/p4dti/issue/job000277">job000277</a>.</td>
  4622.  
  4623. </tr>
  4624.  
  4625. <tr valign="top">
  4626.  
  4627.   <td>2001-05-19</td>
  4628.  
  4629.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4630.  
  4631.   <td>Added section on making changes.</td>
  4632.  
  4633. </tr>
  4634.  
  4635. <tr valign="top">
  4636.  
  4637.   <td>2001-05-22</td>
  4638.  
  4639.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4640.  
  4641.   <td>Noted that a message catalog must not have an entry for message id 0.</td>
  4642.  
  4643. </tr>
  4644.  
  4645. <tr valign="top">
  4646.  
  4647.   <td>2001-06-11</td>
  4648.  
  4649.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4650.  
  4651.   <td>Added warning about field values in Perforce.  Added section listing significant changes since previous releases.</td>
  4652.  
  4653. </tr>
  4654.  
  4655. <tr valign="top">
  4656.  
  4657.   <td>2001-06-27</td>
  4658.  
  4659.   <td><a href="mailto:nb@ravenbrook.com">NB</a></td>
  4660.  
  4661.   <td>Fix interface to <code class="source">all_issues</code> method to fix <a href="http://www.ravenbrook.com/project/p4dti/issue/job000340/">job000340</a>.</td>
  4662.  
  4663. </tr>
  4664.  
  4665. <tr valign="top">
  4666.  
  4667.   <td>2001-06-28</td>
  4668.  
  4669.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4670.  
  4671.   <td>Added note on timezones.</td>
  4672.  
  4673. </tr>
  4674.  
  4675. <tr valign="top">
  4676.  
  4677.   <td>2001-07-09</td>
  4678.  
  4679.   <td><a href="mailto:nb@ravenbrook.com">NB</a></td>
  4680.  
  4681.   <td>Added <code class="source">job_url</code> configuration parameter.</td>
  4682.  
  4683. </tr>
  4684.  
  4685. <tr valign="top">
  4686.  
  4687.   <td>2001-07-14</td>
  4688.  
  4689.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4690.  
  4691.   <td>Added image map to figure 1.  Updated references to Perforce manuals from 2000.2 to 2001.1, since we now support the later version.</td>
  4692.  
  4693. </tr>
  4694.  
  4695. <tr valign="top">
  4696.  
  4697.   <td>2001-10-02</td>
  4698.  
  4699.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4700.  
  4701.   <td>Extended the <a href="#user_translator.unmatched_users"><code
  4702.   class="source">unmatched_users</code></a> method so that the
  4703.   replicator can report users with duplicate e-mail addresses.</td>
  4704.  
  4705. </tr>
  4706.  
  4707. <tr valign="top">
  4708.  
  4709.   <td>2001-10-23</td>
  4710.  
  4711.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4712.  
  4713.   <td>Added migration methods to defect tracker class.</td>
  4714.  
  4715. </tr>
  4716.  
  4717. <tr valign="top">
  4718.  
  4719.   <td>2001-11-01</td>
  4720.  
  4721.   <td><a href="mailto:nb@ravenbrook.com">NB</a></td>
  4722.  
  4723.   <td>Added <a href="#defect_tracker.poll_start"><code class="source">poll_start</code></a> and <a href="#defect_tracker.poll_end"><code class="source">poll_end</code></a> methods to defect tracker class.</td>
  4724.  
  4725. </tr>
  4726.  
  4727. <tr valign="top">
  4728.  
  4729.   <td>2001-11-05</td>
  4730.  
  4731.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4732.  
  4733.   <td>Added <a href="#config-prepare_issue_advanced"><code class="source">prepare_issue_advanced</code></a> to replicator configuration.</td>
  4734.  
  4735. </tr>
  4736.  
  4737. <tr valign="top">
  4738.  
  4739.   <td>2001-11-20</td>
  4740.  
  4741.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4742.  
  4743.   <td>Added <a href="#config-translate_jobspec_advanced"><code
  4744.   class="source">translate_jobspec_advanced</code></a> and <a
  4745.   href="#config-jobspec"><code class="source">jobspec</code></a> to
  4746.   replicator configuration.  Defined representation of job
  4747.   specifications.</td>
  4748.  
  4749. </tr>
  4750.  
  4751. <tr valign="top">
  4752.  
  4753.   <td> 2001-11-22 </td>
  4754.  
  4755.   <td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
  4756.  
  4757.   <td> Cross-referenced section on <code class="source">replicate_p</code> to the <cite><a href="../aag/index.html">Perforce Defect Tracking Integration Advanced Administrator's Guide</a></cite>. </td>
  4758.  
  4759. </tr>
  4760.  
  4761. <tr valign="top">
  4762.  
  4763.   <td>2001-12-04</td>
  4764.  
  4765.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4766.  
  4767.   <td>Added missing <a href="#defect_tracker_issue.add_filespec"><code class="source">add_filespec</code></a> method.  Added optional features and the <a href="#defect_tracker.supports"><code class="source">supports</code></a> method.</td>
  4768.  
  4769. </tr>
  4770.  
  4771. <tr valign="top">
  4772.  
  4773.   <td>2002-01-31</td>
  4774.  
  4775.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4776.  
  4777.   <td>Include <a href="#defect_tracker.replicate_changelist"><code>replicate_changelist</code></a> method in the <a href="#feature-fixes">fixes</a> feature.</td>
  4778.  
  4779. </tr>
  4780.  
  4781. <tr valign="top">
  4782.  
  4783.   <td>2002-02-01</td>
  4784.  
  4785.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4786.  
  4787.   <td>Removed <code class="source">replicate_p</code> method from <a href="#section-7.2"><code class="source">defect_tracker_issue</code></a> class.</td>
  4788.  
  4789. </tr>
  4790.  
  4791. <tr valign="top">
  4792.  
  4793.   <td>2002-02-03</td>
  4794.  
  4795.   <td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
  4796.  
  4797.   <td>Added missing method <a href="#defect_tracker_issue.delete"><code class="source">delete</code></a> to the <a href="#section-7.2"><code class="source">defect_tracker_issue</code></a> class.</td>
  4798.  
  4799. </tr>
  4800.  
  4801. <tr valign="top">
  4802.  
  4803.   <td>2003-06-02</td>
  4804.  
  4805.   <td><a href="mailto:nb@ravenbrook.com">NB</a></td>
  4806.  
  4807.   <td>Updated for version 2.0: converted TeamTrack examples to
  4808.   Bugzilla examples, rewrote some TeamTrack references, added the <a
  4809.   href="#defect_tracker.add_replicator_user"><code class="source">add_replicator_user</code></a> method.</td>
  4810.  
  4811. </tr>
  4812.  
  4813. <tr valign="top">
  4814.  
  4815.   <td>2003-12-17</td>
  4816.  
  4817.   <td><a href="mailto:nb@ravenbrook.com">NB</a></td>
  4818.  
  4819.   <td>Updated Perforce manual references to 2003.1.</td>
  4820.  
  4821. </tr>
  4822.  
  4823. </table>
  4824.  
  4825. <hr />
  4826.  
  4827. <p> <small>This document is copyright &copy; 2001 Perforce Software, Inc.  All rights reserved.</small> </p>
  4828.  
  4829. <p> <small>Redistribution and use of this document in any form, with or without modification, is permitted provided that redistributions of this document retain the above copyright notice, this condition and the following disclaimer.</small> </p>
  4830.  
  4831. <p> <small> <strong> This document is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this document, even if advised of the possibility of such damage. </strong> </small> </p>
  4832.  
  4833. <div align="center">
  4834.  
  4835. <p><code class="perforce-keyword">$Id: //info.ravenbrook.com/project/p4dti/version/2.2/manual/ig/index.html#3 $</code></p>
  4836.  
  4837. </div>
  4838.  
  4839. </body>
  4840.  
  4841. </html>
# Change User Description Committed
#1 5093 Hari Krishna Dara Populating perforce branch.
I will be adding p4admin files to it. 		20 years ago
//guest/perforce_software/p4dti/release/2.2.2/ig/index.html
#1 4861 richard_brooksby Upload P4DTI 2.2.2 to the Perforce Public Depot. 20 years ago