Process documentation
Writing release note, migration guide, FAQ, and documentation entries for TPTP

Release notes, migration guide, FAQ, and documentation entries are now self-serve.

Adding a release note (readme) entry

All readme entries that are not All Project General Notices (i.e., applying to all features of TPTP) will be written by development from now on. To have an entry added to the All Project general notice, please open a bug against TPTP.Web.

In each project on the TPTP web there is a readme XML file that is parsed by the central readme XSLT and formatted into the TPTP readme file.

Please check that there are no syntax errors in the XML file or the release notes page will not appear in IE at all. In Firefox only the release entries in your project's readme.xml file are not rendered, but in IE the entire page is blank.

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: /cvsroot/org.eclipse
    user, password, connection type: same as development CVS
  2. Check out your project's folder:
    • Platform: tptp\platform
    • Monitoring: tptp\monitoring
    • Trace & Profiling: tptp\performance
    • Test: tptp\test
To add a readme, edit your project's readme file:
  1. Open resources\v4.2\readme.xml. Note that v4.2 is an example; this folder's name is different depending on which version of TPTP you're entering the entry for. Also note that there is one release note per major release and it includes the minor releases. For example, v4.2 includes notes for v4.2 and any patches and fixpacks on v4.2. If the note applies to only some of the releases, update the note to state that as of <name of fixpack> the problem is fixed.
  2. Each readme entry looks like this:
    <readme>
    	<title></title>
    	<category></category>
    	<bugzilla></bugzilla>
    	<description></description>
    </readme>
    		
    • For the <title>, put a brief description of the problem that the user will see.
    • For the <category>, use any of the category values defined in this file: category.xml.
    • For the <bugzilla> value, either:
      • Enter the number of the bugzilla that, once fixed, means that the readme can be removed from the readme.xml file
      • Enter the bugzilla number of the bugzilla that was opened against the documentation to have this information added into the on-line documentation if this is a permanent limitation.
      If no bugzilla number is entered, then the following line will be shown in the Release Notes:
      Invalid bugzilla number. Every release note entry must have a bugzilla number unless it is a General Notice.
      Only General Notices entries can have no bugzilla number because they're tips on how to read the Release Notes or links to the JRE/OS support statement.
    • In the <description>, you can use the following HTML formatting:
      <b>
      <br/>
      <code>
      <p>
      <ul>
      <ol>
      <li>
      <a href="..">
      <a name="..">
      <i>
      To have additional categories or HTML formats added, open a bug against TPTP.Web.

    For an example of a working readme.xml file, please view http://www.eclipse.org/tptp/platform/resources/v4.2/readme.xml

Adding a migration guide entry

For the migration guides the process is the same but the location of the XML file is different.

Please check that there are no syntax errors in the XML file or the migration notes page will not appear in IE at all. In Firefox only the notes in your project's migration XML file are not rendered, but in IE the entire page is blank.

A user is someone who uses the TPTP function directly such as by running a test or importing a log file. A consumer is someone who builds a product on top of TPTP such as writing an implementation of an extension point.

Each migration entry looks like this:

	<entry>
		<title></title>
		<description></description>
	</entry>
Where title and description have the same definitions as the readme entities of the same name.

Adding a frequently asked question entry

For the frequently asked questions (FAQ) the process is the same but the location of the XML file is different. In each project on the TPTP web there is a faq XML file named faq.xml that is parsed by the central readme XSLT and formatted into the TPTP frequently asked question page.

For any FAQ pertaining to a particular project please put the entry in the project's faq.xml file and for any FAQ applicable to all of TPTP please put the entry in the tptp_faq.xml file.

Please check that there are no syntax errors in the XML file or the frequently asked page will not appear in IE at all. In Firefox only the notes in your project's faq XML file are not rendered, but in IE the entire page is blank.

Each FAQ looks like this:

	<faq>
		<question></question>
		<answer></answer>
	</faq>
question is the question that users frequently ask and answer is the answer to that question.

Adding a documentation entry

For the main documentation page the process is the same but the file locations are different.

Please check that there are no syntax errors in the XML file or the documentation page will not appear in IE at all. In Firefox only the notes in your project's XML file are not rendered, but in IE the entire page is blank.

Each documentation entry looks like this:

	<topic>
		<audience type="committer"/>
		<category>Process</category>
		<version>NA</version>
		<link>
			<a href="http://www.eclipse.org/tptp/home/documents/category.xml">category.xml</a>
		</link>
	</topic>