Ravenbrook / Projects / Perforce Defect Tracking Integration / Master Product Sources / Procedures

Perforce Defect Tracking Integration Project


Perforce Defect Tracking Integration Release Build Procedure

Gareth Rees, Ravenbrook Limited, 2000-10-17

1. Introduction

This is the procedure for building a release of the Perforce Defect Tracking Integration from the version sources.

The readership of this document is anyone developing the integration.

This document is not confidential.

All relative paths are relative to //info.ravenbrook.com/project/p4dti/.

This procedure is expensive. Do not start it until you are sure that the product is ready for release. Always smoke-test the product before you start to build a release.

2. Procedure

2.1. Setting up for release

  1. Choose a release name of the form "VERSION.N" (for example, 0.3.0). VERSION is the number of the version you're releasing. N is the first unused release number (starting at zero). Look in the index of releases (release/index.html) for existing release numbers for your version.

  2. Ensure that version/VERSION/readme.txt contains an up-to-date description of the release you intend to build and the correct release name. Ensure that the upgrade instructions are correct.

    Ensure that version/VERSION/release-notes.txt has the correct release name and contains a summary of the issues fixed in this and previous releases.

    The summary of issues fixed should be generated using the issue CGI script. Use http://info.ravenbrook.com/project/p4dti/issue/?action=release_notes if you're making the second or subequent release for a version. Use http://info.ravenbrook.com/project/p4dti/issue/?action=release_notes&release=RELEASE if you're making the first release for a version.

    Don't include all the output of that script. Go back at least as far as the last Perforce-supported release, but no further than release 1.0.0. Include a link to an earlier set of release notes, to cover earlier fixes.

  3. Ensure that version/VERSION/packaging/linux/p4dti.spec has an up-to-date description of the software and the correct release number as its "Version" field. Re-use text from the readme.txt file if possible.

  4. Ensure that version/VERSION/packaging/pypi/setup.py has an up-to-date description of the software and the correct release number in the parameters to setup. Re-use text from the readme.txt file if possible.

  5. Submit readme.txt, release-notes.txt, p4dti.spec, and setup.py to Perforce before you continue.

  6. Determine the changelevel at which you're going to make the release. This will usually be the latest submitted changelevel on the version branch; to get it use

    p4 changes -m 1 version/VERSION/...

2.2. Windows integrations, Windows integration kit and online manuals

  1. Find a Windows NT machine on which you've intalled Cygwin, Python and WinZip (I suggest sandpiper.ravenbrook.com). Sync your client workspace. Make sure you have nothing open for edit in the default changelist. Open a shell and switch to the directory version/VERSION/tool/. Run the command

    python build.py -r RELEASE -c CHANGELEVEL -t bugzilla -t kit -t manuals

    Follow the instructions carefully. If all goes well, then you will be asked to do the following:

    1. Run Microsoft Visual Studio and build eventlog.dll.

    2. Run WinZip on p4dti-bugzilla-RELEASE.zip and make a self-extracting executable.

  2. You should now have the following files open in your default changelist:

    release/RELEASE/readme.txt
    release/RELEASE/release-notes.txt
    release/RELEASE/p4dti-bugzilla-RELEASE.zip
    release/RELEASE/p4dti-bugzilla-RELEASE.exe
    release/RELEASE/p4dti-kit-RELEASE.zip
    release/RELEASE/ag/...
    release/RELEASE/ug/...
    release/RELEASE/ig/...
    
  3. Check the build products against their descriptions in [GDR 2001-07-13]. Are all the files present? Do they unpack to the correct directories? Have the links been rewritten correctly?

  4. Submit the build products to Perforce with a description like "Added the Windows integrations, integration kit and online manuals for release RELEASE."

2.3. Unix integration and Unix integration kit

  1. Find a RedHat Linux machine with Python installed (I suggest swan.ravenbrook.com). Sync your client workspace. Make sure you have nothing open for edit in the default changelist. Open a shell and switch to the directory version/VERSION/tool/. Run the command

    python build.py -r RELEASE -c CHANGELEVEL -t bugzilla -t kit
  2. You should now have the following files open in your default changelist:

    release/RELEASE/p4dti-bugzilla-RELEASE.tar.gz
    release/RELEASE/p4dti-bugzilla-RELEASE-1.i386.rpm
    release/RELEASE/p4dti-kit-RELEASE.tar.gz
    
  3. Check the build products against their descriptions in [GDR 2001-07-13]. Are all the files present? Do they unpack to the correct directories? Have the links been rewritten correctly? Run the following command to test the RPM and inspect its output:

    rpm --upgrade --test -vv release/RELEASE/p4dti-RELEASE-1.i386.rpm
    
  4. Submit the build products to Perforce with a description like "Added the Bugzilla integration for release RELEASE."

2.4. Registering the release

  1. Edit the index of releases (release/index.html) and add the release to the table, in a manner consistent with previous releases.

  2. Edit the index of versions (version/index.html) and add the release to the list of releases for VERSION, in a manner consistent with previous releases.

  3. Edit the //info.ravenbrook.com/infosys/cgi/issue.cgi script to add the release changelevel to the releases table, so that the correct set of known and fixed issues can be derived.

  4. Submit these changes with the comment "Registered release RELEASE."

  5. Inform the project manager and staff by e-mail to p4dti-staff@ravenbrook.com.

  6. When the release is confirmed as stable and for public release, register it with the Python Packages Index by running the setup.py script like this:

    python packaging/pypi/setup.py register
    

    Use the PyPI username "p4dti-staff@ravenbrook.com". See this e-mail message for the password.

A. References

[GDR 2000-10-16] "Re: P4DTI release build and installation" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-16.
[GDR 2000-10-17b] "Build report for release 0.3.1"; Gareth Rees; Ravenbrook Limited; 2000-10-17.
[GDR 2001-07-13] "Build automation design"; Gareth Rees; Ravenbrook Limited; 2001-07-13.
[RB 2000-10-13] "P4DTI release build and installation" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-10-13.
[RB 2000-11-17] "Using Perforce labels for releases" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-11-17.

B. Document History

2000-10-17 RB Created based on e-mail procedure [RB 2000-10-13].
2000-10-17 GDR Added corrections from [GDR 2000-10-16] and [GDR 2000-10-17b].
2000-10-19 RB Added steps for handing the readme.txt. Changed bullets to numbers in the procedure. Corrected the order of the "label" and "sync" steps.
2000-11-17 RB Discontinued use of Perforce labels in favour of changelists. See [RB 2000-11-17].
2000-12-01 RB Updated references to the "SAG" to "AG" since it's now called the Administrator's Guide.
2000-12-05 GDR Reorganized into sections and added Bugzilla section. Updated for version 0.4: use release configuration for teamtrack.dll; don't include debugging or AppleWorks files. Explained how to get the lists of known defects, changes and new features. Listed the files that one would expect to have on submit so you can check that you've done everything.
2000-12-07 GDR Added reference to known_issues.py script.
2000-12-08 GDR Added more detail about Microsoft Visual C++. Added instruction to check in readme.txt before continuing.
2000-12-12 RB Converted from plain text to HTML.
2000-12-13 RB Updated reference to known_issues.py to refer to the tool for the specific version. Fixing "mailto" URLs in history.
2000-12-15 RB Changed install directory for Bugzilla from "p4dti" to "p4dti-bugzilla-RELEASE" to bring into line with Unix convention.
2001-02-13 GDR Include readme.txt in product sources. Don't check in the zip file (people download it needlessly).
2001-02-14 RB Added copying of startup script to tarball so that it can be installed by the Linux RPM. Added RPM creation procedure.
2001-02-15 RB Removed the Manager's Guide and the Integrator's Guide from the normal distribution. The Manager's Guide is empty, and the Integrator's Guide should only come with the integration kit.
2001-02-19 GDR The instructions for bulding the lists of known and fixed issues use the new known_issues.py command line format.
2001-02-21 GDR Added instructions to branch the manuals into release/RELEASE/....
2001-02-22 GDR Added instructions for handling the release-notes.txt file.
2001-02-23 GDR Include p4dti.reg in TeamTrack release.
2001-02-27 GDR Delete IG and MG directories so they don't appear in the zip archive.
2001-03-02 RB Transferred copyright to Perforce under their license. Added steps for copying the license.txt file to the distribution.
2001-03-06 GDR No longer put known issues in the release notes.
2001-03-20 GDR Put the changelevel in the issue CGI script so known issue reports can be made.
2001-03-26 RB Moved Linux RPM files from tool/rpm to packaging/linux.
2001-03-27 RB Added Integration Kit build instructions.
2001-03-29 RB Added Integrator's Guide to the set of manuals included in the release directory.
2001-04-10 RB Corrected procedure to submit at different stages, because the different integrations are built on different machines under different Perforce clients. Broke out manual branching into its own section. Moved editing of issue.cgi script to the same point as registering the release in the other indexes. Added precondition that the code must be smoke-tested.
2001-04-11 RB Added warning about known_issues.py script generating wrong results between version branches.
2001-05-04 GDR Use the issue CGI script to get a list of issues newly fixed in the release.
2001-05-24 NB Updated for Bugzilla 2.12.
2001-07-03 GDR Now we have to build two TeamTrack modules.
2001-07-05 GDR Unpack TeamTrack integration into C:\Program Files\P4DTI-RELEASE to avoid picking up old teamtrack.dll.
2001-07-13 GDR Use automated build support.
2002-06-26 RB Fixed the procedure to build the Unix integration kit under Unix so that it has the right line endings.
2002-11-01 NB Add documentation for Bugzilla integration on Windows.
2002-11-14 RB Removed TeamTrack builds, as TeamTrack support has been handed off to TeamShare.
2004-03-03 RB Fixed the way we determine the release changelevel to avoid possible pending changelists.
2004-03-09 RB Added steps to update the Python Packages Index.

This document is copyright © 2001 Perforce Software, Inc. All rights reserved.

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.

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.

$Id: //info.ravenbrook.com/project/p4dti/branch/2005-03-02/agena-extension/procedure/release-build/index.html#2 $

Ravenbrook / Projects / Perforce Defect Tracking Integration / Master Product Sources / Procedures