Infrastructure documentation
Setting up the release notes, migration guides, and FAQ files for entries by multiple committers

Release notes, migration guide, and FAQ entries are now self-serve. This document explains how to set up the infrastructure so that any TPTP committer can add an entry to any of these three guides. There used to be a "user" migration guide but that practice was stopped because users of all languages need to know how to migrate their workspace, and that means that the information must be packaged in the TPTP on-line help ("Help Contents").

 

The Pieces

Each of the three guides is created using the same technique. Every guide is constructed of at least the following files:

  1. Projects' XML files: an XML file in every TPTP subproject containing the content of the guide for one release of TPTP
  2. Central XML file: a file listing the location of the XML files identified above
  3. Central XSL file: a file that formats the content of the Projects' XML files to produce HTML that is easily read by the user
  4. Central HTML or PHP file: a file that imports the central XML file and central XSL file and applies one to the other to create the final guide

A. Projects' XML files

Each project contributes its own content to every guide and there is distinct content for each version of the guides. Every major release of TPTP has a new guide created, and any patches or fixpacks of that release must put their content into the corresponding major release guide instead of a distinct patch or fixpack release guide.

The entries in the Projects' XML files must follow the format explained in Writing release note, migration guide, and FAQ entries for TPTP. Basically there is a standard XML structure and for some elements in that structure HTML formatting is applied to their values to produce an easily readable guide for the user.

B. Central XML file

Because each project, and each version of TPTP, has unique content for a particular guide, the central XML file lists the relative locations of the Projects' XML files that should be processed for a particular guide.

C. Central XSL file

The XSL file is used to format the XML content of every Projects' XML file into its HTML equivalent. You should not need to alter any of these files unless someone requests support for an HTML tag or attribute not currently supported. The HTML processing is duplicated across the files instead of factored into its own reusable file because there wasn't enough time to figure out how to reuse or import a common XSL file. If you know how, or have the time to figure it out, please feel free. :o)

D. Central HTML or PHP file

The HTML or PHP file reads in a named central XSL file and a named central XML file and dynamically applies the XSL to the Project XML files identified by the central XML file to display the guide to the user.

 

Create the guides

To start creating the guides, follow these steps:

  1. Check out the TPTP web site from CVS
  2. Create the new version of the Projects' XML files
  3. Create the new version of the central XML file
  4. Create the new version of the central HTML or PHP file
  5. Create the new version of any additional files needed by a particular guide
Note that you do not need a new version of the central XSL file.

 

1. Check out the TPTP web site from CVS

If you are unfamiliar with how to check out your project's web site,

  1. Add a new CVS repository:
    host: dev.eclipse.org
    repository path: /home/cvs/org.eclipse
    user, password, connection type: same as what you use for regular check-in and check-out of TPTP code
  2. Check out the entire tptp site: www\tptp

 

2. Create the new version of the Projects' XML files

In each project (tptp\monitoring, tptp\performance, tptp\platform, and tptp\test) you will find a folder named resources. In this folder you need to create a folder for the version of TPTP whose resources you are creating, e.g. for TPTP V4.4 create a folder named v4.4.

Copy the three files from the v4.3 folder (faq.xml, readme.xml, and migration_guide_consumers.xml) into the new folder. Clear the entries in each of these copies in the new folder so that they are blank for the new version of TPTP.

 

3. Create the new version of the central XML file

Each guide has its own central XML file that needs to be created.

The release notes guide

In folder tptp\home\downloads\releasenotes you will find a file, releasenotes_files4_3_0.xml. Copy this file into the same folder and rename it to match its corresponding TPTP version. Edit the new file to point to the readme.xml files that you created in the previous step.

The migration guide

In folder tptp\home\downloads\migrateguide\4.3 you will find a file, migration_guide_consumers_files4_3_0.xml. Create a new folder to match the corresponding TPTP version and copy this file into the new folder. Rename the file to match its corresponding TPTP version. Edit the new file to point to the migration_guide_consumers.xml files that you created in the previous step.

The FAQ guide

In folder tptp\home\documents\webcontent\faq\v43 you will find a file, faq_files.xml. Create a new folder to match the corresponding TPTP version and copy this file into the new folder. Edit the new file to point to the faq.xml files that you created in the previous step.

 

4. Create the new version of the central HTML or PHP file

Each guide has its own central HTML or PHP file that needs to be created.

The release notes guide

In folder tptp\home\downloads\releasenotes you will find a file, releasenotes4_3_0.html. Copy this file into the same folder and rename it to match its corresponding TPTP version, e.g. releasenotes4_4_0.html. Edit the new file to point to the releasenotes_files4_4_0.xml file that you created in the previous step and the central XSL file, readme.xsl.

That is, change all occurrences of 4.3 to the version that you are creating and change the following section,

<body onload="Initialize();
              SetTarget('target_content'); 
              SetInput('releasenotes_files4_4_0.xml'); 
              SetStylesheet('readme.xsl'); 
              Transform();">
so that the SetInput('releasenotes_files4_4_0.xml'); line points to the central XML file that you created in the previous step.

The migration guide

In folder tptp\home\downloads\migrateguide\4.3 you will find a file, tptp_migration_guide_consumers.html. Create a new folder to match the corresponding TPTP version and copy this file into the new folder. Rename the file to match its corresponding TPTP version. Edit the new file to point to the migration_guide_consumers_files4_4_0.xml file that you created in the previous step.

That is, change all occurrences of 4.3 to the version that you are creating and change the following section,

<body onload="Initialize();
              SetTarget('target_content'); 
              SetInput('migration_guide_consumers_files4_4_0.xml'); 
              SetStylesheet('../migration_guide_consumers.xsl'); 
              SetParam('old_version','4.3');
              SetParam('version','4.4');
              Transform();"gt;
so that the SetInput('migration_guide_consumers_files4_3_0.xml'); line points to the central XML file that you created in the previous step, and 'old_version' points to the previous major release of TPTP and 'version' points to the current major release of TPTP.

The FAQ guide

In folder tptp\home\documents\webcontent\faq\v43 you will find a file, faq.php. Create a new folder to match the corresponding TPTP version and copy this file into the new folder. Edit the new file to point to the faq_files.xml file that you created in the previous step. (This step will not be necessary if you created that file in the same folder as this file.)

That is, change all occurrences of 4.3 to the version that you are creating and change the following section,

	$STATUS_CONTENT.= "<script language=\"JavaScript\">\n";
	$STATUS_CONTENT.= "Initialize();"; 
	$STATUS_CONTENT.= "SetTarget('target_content');"; 
	$STATUS_CONTENT.= "SetInput('faq_files.xml');"; 
	$STATUS_CONTENT.= "SetStylesheet('../faq.xsl');"; 
	$STATUS_CONTENT.= "Transform();"; 
	$STATUS_CONTENT.= "</script>"; 
so that the $STATUS_CONTENT.= "SetInput('faq_files.xml');"; line points to the central XML file that you created in the previous step.

 

5. Create the new version of any additional files needed by a particular guide

Only the release notes has additional files that need to be maintained: readme4_3_0_all.xml and category.xml.

readme4_3_0_all.xml

In the tptp\home\downloads\releasenotes folder you'll see a file, readme4_3_0_all.xml. The entries in this file are common to all TPTP subprojects, for example, "TPTP" refers to "Test and Performance Tools Platform". The entries in readme4_3_0_all.xml will probably be sufficient for the new version of TPTP but it could be that a new common entry may be identified that will need to be entered into the file.

If you need a file with different entries than the existing readme4_3_0_all.xml file, then create a new copy of this file in the same folder and name the copy as per the version number of TPTP, e.g. readme4_4_0_all.xml. Edit the entries or add a new entry and update the central XML file to point to this new file.

category.xml

This file contains the names of the categories used in the release notes guide, e.g. Agent Controller. You should not need to edit this file unless a new component needs to add a new release note. If this is necessary, do the following:

Copy one of the existing categories, e.g.

<category id="MAE">
	<name>Managed Agent Explorer</name>
</category>
	
And edit the category so that the id is the initials of the new name. If the new id value would be the same as an existing id value in the file then use a different value. The id value must be unique and should relate to the category name.
<category id="MNC">
	<name>My New Category</name>
</category>
	

 

Add the links to the new guides on the web site

Links to the new guides need to be added in two places: the central Documentation page and the Downloads page. Open a bugzilla against Build to have the Downloads page updated and edit the index.html file in tptp\home\documents to add a new entry under the Release Notes in the User section and API Migration Guides in the Consumers section. (The FAQ is not listed on the Documentation or Downloads pages.)