Documentation for Extensible Issue Tracker (ExIT)

4.1 Summary view

The "home page" of the issues list (issues.html) displays a summary of all issues. This home page also provides access to the other views.

For each issue, the summary table displays by default:

• The issue identifier and title
• The deadline for deciding the issue (if any)
• The current state of the Working Group's work on the issue
• The issue type
• Any user-defined category information
• A summary of open action items
• The current state of the Working Group's acknowledgment to the reviewer, in the case where the group has made a decision on the issue

4.2 Issue details

The "home page" of the issues list (issues.html) also shows the details of each issue (available by following the issue identifier link in the summary table). The details section is sorted according to the sort order chosen for the summary table.

The details of each issue include:

• The issue identifier and title
• The issue description
• The list of topics that the issue concerns
• The history of the group's discussion of the issue
• Any user-specified category information
• The issue transition history. Each transition may have an accompanying description, which is displayed if present.
• When an issue has been decided, the acknowledgment cycle
• The list of all action items associated with this issue. Each action item indicates the action owner, action description, action deadline if present, and action history. Each action item is delimited by a box. The box is displayed in gray when the issue has been closed.

For more information on the meaning of issue transitions, acknowledgment cycle, and action history, see the section below on ExIT logic.

4.3 View by Reviewers

The reviewers view lists the groups and individuals who raised issues. An issue is associated with an individual only when the individual did not raise it on behalf of a group.

By the Candidate Recommendation transition on the Recommendation track, a Working Group is expected to be able to show the Director that the specification has received wide review. To help the Director determine at a glance that a specification has received wide review, check "Hide issue details" checkbox then push Reformat. The resulting view summarizes the names and number of reviewing groups and individuals. The default view ("Hide issue details" is not checked) lists the issues raised by each group and individual (with links back to the issue details).

4.4 View Open Actions

Two views of open action items are available:

1. View by action owners
2. View by issue

The first view is designed to help group participants track their open action items. The second view is designed to help a group close a particular issue.

4.5 View by what Topic the Issue Concerns

This view lists all topics that are concerned by the issues. Each topic indicates which issue(s) refer to it. An issue may refer to more than one topic. Issues refer to topics by URI.

4.6 View Issue Changes

Because ExIT keeps a running history of message dates (for discussions, transitions, announcements, etc.), groups can view the state of the issues list between two arbitrary dates. The changes view is generated dynamically from an issue home page by entering at least the "start date" and optionally an interval "end date", and pushing the "Changes" button.

Absence of an "end date" means "from the start date onward." Both start and end dates are inclusive; an event is considered within the range if it occurs on or after the start date and prior to or on the end date.

Some uses of the changes view include:

• Building a summary of changes during a particular interval (e.g., in the last month or since the last AC meeting).
• Establishing whether an interval was discussed on or near a particular date (that may be associated with another event, such as a workshop).
• Announcing issue changes to individuals who wish to monitor such changes; see the section on future work.

4.7 Graphical Views of Distributions

There are two graphical views of issue data (in SVG):

1. A bar graph showing the distribution of issues by type.
2. A bar graph showing the distribution of issues according to the latest transition (decided, accepted, etc.).

5.1 Schema validation

To ensure that your issue data is valid, we encourage you to use the online XML Schema Validator. Each issue home page includes a link to the online Schema validator for the issue data of that list.

The default Makefile also allows you to type "make validate", which also calls the online validator.

5.2 Using XInclude to store Issue Data in Multiple Files

ExIT supports XInclude and allows you (but does not require you) to create a single issues list from multiple source files. Your issues.xml file should include all of the metadata in the file header. In place of the <issue> element, refer to an external issue file with <xi:include href="myissue.xml"/>.

Some XSLT processors (including xsltproc) support XInclude natively. To use XSLT processor support, adjust your Makefile accordingly (e.g., see the "--xinclude" option for xsltproc).

If your XSLT processor does not support XInclude, you may use ExIT's implementation of XInclude (an XSLT transform). Here is an example of an xsltproc call that takes an issues.xml and expands the XInclude markup:

xsltproc $(EXITXSLPATH)xinclude.xsl issues.xml

where $(EXITXSLPATH) represents the path to the ExIT XSLT file xinclude.xsl. The result of this processing should be issues data that conforms to the ExIT XML Schema.

For a more complete example, see the xinclude example in the ExIT source.

5.3 Abbreviating issues date with references to email archives

ExIT includes a mechanism to take advantage of the XHTML structure W3C mailing list archives. The abbreviated syntax (which does not conform to the ExIT XML Schema) lets you:

• Extract certain pieces of issue data from the generic W3C mailing list by reference to an email with a URI.
• Override certain parts of the source in the issues data file.

For example, suppose that the "full form" of an issue in its initial state is:

  <issue id="issue-1" type="proposal">
    <title>
       Section 4.1 should be deleted
    </title>
    <transitions>
     <raised xlink:type="simple" 
          xlink:href="http://www.example.com/list/">
        <date>2003-12-12</date>
	<description>
  	  <eg>
            ...description of issue here...
 	  </eg>
	</description>
        <originator>
         <loc xlink:type="simple" 
              xlink:href="mailto:joe@example.com">Joe Reviewer</loc>
       </originator>
     </raised>
   </transitions>
  </issue>
 

The most compact abbreviated form is:

  <issue id="issue-1" type="proposal"
            src="http://lists.w3.org/Archives/Public/...">
  </issue>
 

The value of the "src" attribute is a URI that refers to an email in a mailing list archive. The following xlstproc call shows how one would expand an issues.xml file with data in this abbreviated form into a form conforming to the ExIT XML Schema:

xsltproc $(EXITXSLPATH)abbr2full.xsl issues.xml

The abbreviation mechanism allows you to extract the following information from an email automatically:

• The email subject is used as the issue title.
• The email body is used as the issue description.
• The email data is used as the date of the "raised" transition.
• The sender email address is used as the "mailto" URI for the originator. The same information is used as the originator name.

An email subject line may not make the best issue title, so ExIT lets you override the issue title locally as follows:

  <issue id="issue-1" type="proposal"
            src="http://lists.w3.org/Archives/Public/...">
    <title>
       This title overrides the email subject.
    </title>
  </issue>
 

Similarly, ExIT lets you to override the issue description locally as follows:

  <issue id="issue-1" type="proposal"
            src="http://lists.w3.org/Archives/Public/...">
    <transitions>
      <override>
         <description>
           This description overrides the email body.
         </description>
      </override>
    </transitions>
  </issue>
 

The title and description overrides may be used together. The abbreviated form is compatible with the remaining pieces of issue data (e.g., discussion, other transitions, actions, etc.).

Since this mechanism automatically retrieves data from the W3C mailing list when ExIT generates views, you may wish to use this mechanism in combination with the XInclude mechanism. This allows you to "expand" the abbreviated form once, then include the expanded form in issues.xml. The ExIT source includes an example issues file that includes individual issue files that themselves use the abbreviation mechanism. The associated Makefile illustrates how to expand individual issues into a file that can be included into an issues.xml file. The individual issues files are only expanded when the issue data is modified to avoid unnecessary requests to the mailing list server.

7.1 Structure of issue data

The ExIT XML Schema is the definitive source of information on issue data. A few notes:

• The ExIt namespace URI is "http://www.w3.org/2003/10/issues"
• Familiarity with the XMLSpec DTD will be useful for creating structured content inside of descriptions and certain other elements of ExIT. This data is converted to XHTML using tools provided by the XMLSpec community.

7.2 Issue Logic

The primary logical component of ExIt is the "issue". An issue consists of:

• A title
• A unique identifier
• A list of resources that the issue concerns (e.g., specifications)
• An issue type
• An optional deadline by which the issue must be addressed
• A transition history
• An action item history
• User-specified categories (for extensions to ExIT)

ExIt considers that an issue is "closed" when all of the following are true:

1. The issue is in a decision state.
2. The transition cycle is in a decision state.
3. Each associated action is in the decision state.

Otherwise an issue is open. Note that an issue may be "decided" without being "closed". This means that the Working Group has reached a decision, but has more to do: to complete actions or the acknowledgment cycle.

7.3 Acknowledgment Logic

Once an issue is in the decision state, the Working Group announces the decision to the reviewer and seeks acknowledgment from the reviewer that the reviewer is satisfied. This is called the acknowledgment cycle. The transitions of the acknowledgment cycle are:

• Initial states
• Proposal states
• Decision states

7.4 Action Logic