Jump to: navigation, search

Difference between revisions of "Development Resources/Project Plan/XML"

Line 1: Line 1:
{{Warning|Note that projects may choose to specify their project plans as part of the release record in the [[Project Management Infrastructure]].}}
+
{{Warning|Note that projects may choose to specify their project plans as part of the [[http://wiki.eclipse.org/Project_Management_Infrastructure/Project_Metadata#Releases|release record]] in the [[Project Management Infrastructure]].}}
 
As per a resolution from the Board that led to {{bug|215301}}, all projects are required to provide their current project plan in the following XML format.
 
As per a resolution from the Board that led to {{bug|215301}}, all projects are required to provide their current project plan in the following XML format.
  

Revision as of 10:35, 8 April 2013

Warning2.png
Note that projects may choose to specify their project plans as part of the [record] in the Project Management Infrastructure.

As per a resolution from the Board that led to bug 215301, all projects are required to provide their current project plan in the following XML format.

XML Template

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<?xml-stylesheet type="text/xsl" href="http://www.eclipse.org/projects/project-plan.xsl"?>
<plan plan-format="1.0" xmlns="http://www.eclipse.org/project/plan" xmlns:html="http://www.w3.org/1999/xhtml"
      name="Project Name">
   <release projectid="technology.dash" version="1.0"/>
   <introduction>
     <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
   </introduction>
   <release_deliverables>
     <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
   </release_deliverables>
   <release_milestones>
      <preamble>
         <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
      </preamble>
      <milestone date="7/1/2008" milestone="M1"><html:div>optional html</html:div></milestone>
      <milestone date="8/1/2008" milestone="M2"><html:div>optional html</html:div></milestone>
      <milestone date="9/1/2008" milestone="RC1"><html:div>optional html</html:div></milestone>
      <milestone date="6/28/2009" milestone="1.0"/>
      <postamble><html:div>html content</html:div></postamble>
   </release_milestones>
   <target_environments>
     <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
     <internationalization>
          <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
     </internationalization>
   </target_environments>
   <compatibility_with_previous_releases>
       <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
   </compatibility_with_previous_releases>
   <themes_and_priorities>
     <preamble>
         <html:div>Some xhtml content here.  Make sure to use the prefix before the elements</html:div>
     </preamble>
     <theme name="Appealing to the Broader Community">
        <description>...(optional) html...</description>
        <committed bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</committed>
        <proposed bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</proposed>
        <deferred bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</deferred>
     </theme>
     <theme name="Design for Extensibility">
        <description>...(optional) html...</description>
        <committed bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</committed>
        <proposed bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</proposed>
        <deferred bugzilla="...(recommended) bugzilla search url...">
           ...(optional alternate) html...</deferred>
     </theme>
   </themes_and_priorities>
   <appendix name="Project Refactoring">
     ...html...
   </appendix>	
 </plan>

Note that the HTML content must be prefixed with the correct namespace prefix, and the XHTML namespace must be included. XHTML is required as it will allow for tooling to help with validation and editing support. Do not Wrap your XHTML content with CDATA. Anywhere it says to use HTML content, you should be using XHTML which is the XML equivalent of HTML.

When using the bugzilla attribute the url must be encoded with &amp; as the argument separator. Bugzilla seems to prefer just a ; but that will make the php script break when trying to render the plan.

Obviously, the milestone, theme and appendix elements can be repeated as many times as necessary.

Tools for Editing your Plan

Getting the WTP XML Tools set up is simple, and worth it since it provides instant HTML validation and content assist:

  • From Eclipse 3.4, install the WTP XML Editor: Ganymede Update Site, Web and Java EE Development, Eclipse XML Editors and Tools
  • Register the XML Schemas in WTP's Catalog. This will give you Ctrl+Space Content Assist as well as Validation Support and Automatic Closing of Elements in the XML Editor:

Hints for Editing your XML

  • The XML plan must reside on the Eclipse Website. So, you'll need a local Eclipse Project which is shared with CVS Team Provider (Repository=:extssh:dev.eclipse.org:/cvsroot/org.eclipse, Module=www/your/project
  • Create an empty XML file in your project ("myplan_1_0.xml"). Copy and paste the raw XML from an existing XML plan into your local project. There are two variants:
  • Little HTML markup: RTSC and Project Dash use the project plan markup as the default namespace, which means that all XHTML needs to be qualified by the "html:" namespace tag. Use this if you anticipate little HTML contents.
  • Much HTML markup: Target Management (TM) uses the XHTML markup as the default namespace, which means that all Plan elements need to be qualified by the "p:" namespace prefix. Use this if you anticipate much HTML contents, e.g. because you are carrying forward contents from an older HTML based project plan.
  • Start filling in the HTML contents and bugzilla queries. You can right-click > Validate to see if your document is valid according to the XSD. If you carry forward some older HTML, it might not be valid XHTML any more; there is tooling to automatically convert HTML into XHTML, e.g. http://valet.htmlhelp.com/tidy/
  • Your bugzilla queries (hyperlinks) should be encoded by replacing each single "&" character by "&amp;" in order to be a valid XML attribute. No other characters need to be escaped.
  • Particularly note that XHTML does not allow the following constructs: nested tags inside <p> elements; attributes like "width" or "background" in elements -- use a "style" markup instead.
  • Enclosing your HTML stuff inside a single <div> item which sets up the XHTML default namespace for the elements within it is one idea to avoid prefixing each element:
    <html:div xmlns="http://www.w3.org/1999/xhtml"><ul><li><big>Valid</big> Namespaced.</li></ul></html:div>
  • When you think it's OK, commit your plan in order to get it rendered on the server. Note that you will need to register the Plan URL in the Portal, see #Specifying the Plan below.
  • If you prefer checking it locally before commiting, this is also possible. You will need to copy the following files into the project that holds your plan: project-plan-render.xsl, project-plan-bugzilla.xsl, url-encode.xsl.
  • Inside your local plan xml, change the header which points to the XSL to read
    <?xml-stylesheet type="text/xsl" href="project-plan-render.xsl"?>
    . Now, open your plan XML with a browser like firefox and it should render correctly.
  • If you want to have strict XHTML validation, download the plan.xsd file into your local project, then edit the WTP XML Catalog Preferences to point to your local XSD rather than the common one. In the local XSD, exchange occurrences of processContents="skip" by processContents="strict".
  • Having the plan.xsd local, also allows you to right-click > Generate on it in order to generate a sample XML Template from the XSD. This is another option for starting your plan.

Note: In order for the plan to render, it MUST be valid against the schema it. It is highly recommended that you validate your XML against the schema. The Eclipse Web Tools project provides all the necessary tools to do the validation.

Bugs as Plan Items

The goal of the bugzilla queries is to support the use of bugzilla items for planning. The project team should assign target milestones to each bug, including both defects and enhancements. Additionally, the team should assign keywords (or keywords-in-titles) to each bug entry in order to classify them into themes. The bugzilla queries would then be, e.g., "all 2.6M1, 2.6M2, 2.6M3, ..., 2.6 bugs with keyword 'designforextensibility'", etc.

One option for mapping to the committed / proposed / deferred items is that all bugs with explicit milestones assigned are considered committed; those assigned a generic milestone or "---" are considered proposed; those assigned a milestone like "Future" are considered deferred. The DSDP-TM project uses this scheme, with keyword markup in the bugzilla subject line. Another idea is to only retrieve bugs with a "plan" or "investigate" keyword by the queries, or to only add bugs with specific priorities, in order to avoid flooding the plan with less interesting small items.

If a project chooses not to use bugzilla item for planning (contrary to collective wisdom of the senior Eclipse project leads), the project plan format allows arbitrary html text paragraph(s) instead.

Specifying the Plan

The project plan xml file is placed in the project's website CVS. The project meta-data item "projectplanurl" is then defined to point to that xml file. Use the portal to modify the project meta-data.

Note that in addition for specifying your "current plan" in the Portal, bug 238434 is open requesting an ability to render arbitrary XML project plans as HTML.

Examples

  • Dash Sample

Known Issues

Some Bugs and Enhancement Requests are known in the projectplan renderer, follow the link into Bugzilla for more information.