Developer information - Issues

Introduction

An "issue" is an objection to something that has been developed within DEXlib. This could be a DEX, a Capability, Reference Data or the infrastructure it self. Issue logs are used to provide a visability and traceability to issues raised and resolved.
There are four issues logs maintained in DEXlib:

Main log
Infrastructure log
DEX Specification and Capability log
Reference data log

The Main log is used for ... The Infrastructure log is focused on issues against the DEXlib environment. The DEX Specification an Capability log is actually one log for each DEX Specification and Capability. The Reference data log is used for ...

Raising and resolving issues

This section describes how to raise an issue against a Capability.
An issue against a DEX, Reference Data or the DEXlib infrastructure is raised much in the same way.

Raising issues against a Capability

An issue should be raised if you find something that you disagree with or think is a fault in a Capability. You should not edit a Capability without the permission of the project leader. You need to have permissions as a modeller in order to be able to create a new issue. If you are not a modeler, explain the problem to someone who is and let them help you.

The following steps explains how to raise an issue in DEXlib.

Go to the folder of the capability (dexlib\data\capabilities\[capability identifier]\dvlp) and open the 'issues.xml' file.
Copy the empty issuses tag section, but exclude the 'comment' section (shown below) from the beginning of the 'issues.xml' file and paste it at the end of the file, just above the closing 'issues' tag.
```

<issue
  id=""
  type="general"
  category="minor_technical"
  by=""
  date=""
  status="open">
  <description>

  </description>
</issue>
            
```
Fill in the attributes or tags according to the instructions below.
- id; an identifier of the issue. The identifier must be unique only within the particular 'issues.xml' file. The convention is to use the initials in your name, a '-' sign, and a number, e.g. "MN-01".
- type; the primary XML element in 'capability.xml' file that the issue is against. This would be either; general, contents, abstract, contacts, introduction, business_overview, information_model_overview, templates, ref_data, related_standards or usage. The default is 'general'.
- category; The possible classifications are;
  - 'editorial' - for typing errors, spelling misstakes and suggestions.
  - 'minor_technical' - for ...
  - 'major_technical' - for ...
  - 'repository' - for ...
  The default is 'minor_technical'.
- by; the person raising the issue. The name should be the same one as provided in the contacts.xml file, in order for the capability project leader or modeler to be able to contact the creator of the issue for potential clarification. Further information about the 'contacts.xml' file is found here (LINK).
- date; The date the issue was raised. The format of the date should be 'yy-mm-dd'. MatsN: Why this un-ISO-ish format?
- status; Is 'open' as long as the issue is beeing discussed. When the issue has been resolved, the status is set to 'closed'.
- description; Description and possibly asuggestion for a solution.
Save the file and do a CVS update.
Post the issue on the plcs-dex exploder. Also adress the email directly to the project leader of the specific Capability.

Resolving issues

There are basically two types of comments, one that discusses the description of the issue, and one that describes a solution and closes the issue.

The following steps explains how to reslolve an issue.

Go to the folder of the capability (dexlib\data\capabilities\[capability identifier]\dvlp) and open the 'issues.xml' file.
Copy the empty 'comment' section within the issuses tag section, from the beginning of the 'issues.xml' file and paste it after the description tag inside the issue that the comment is concerning.
```
<issue ... >
  <description> ... </description>

  <comment
    by="" 
    date="">
    <description>

    </description>
  </comment>

</issue>
            
```
Enter the name (first and surname) and date (yy-mm-dd) of the comment.
Enter the text of the comment. If the comment is closing the issue (either by updating the capability, or by ignoring the basis for the issue) the status attribute of the issue should be set to 'close'.
Save the file and do a CVS update.
Post the issue on the plcs-dex exploder. Also adress the email directly to the project leader of the specific Capability.

Viewing issues

How can the issues be viewed? The four issue logs can all (soon) be accessed from the tools menu on DEXlib. For DEX Specifications and Capabilities, the individual logs can also be accessed from their pages.

The different logs

Main Issues log

An issue log of all the Major issues that affect all the DEXs and capabilities is maintained at:

          dexlib/docs/issues/main_issues.xml

Infrastructure log

An issue log of all the issues that are to do with the dexlib infrastructure is maintained at:

          dexlib/docs/issues/infrastructure_issues.xml

The issue log can be accessed from the tools menu on DEXlib.

DEX Specification and Capability log

An issue log is associated with each DEX and capability. The log is stored in:

          dexlib/data/[DEX]/dvlp/issues.xml

where [DEX] is the name of the DEX or capability directory.

A summary of all the issue logs can be accessed from the tools menu on DEXlib. Alternatively the individual logs are accessed from the DEXs or capabilities.

Reference data log

Issues can be raised against Reference data classes at any stage during the development.

The issues are recorded in the issue log: (../../data/refdata/dvlp/issues.xml)

Each issue has the following form:

      <issue
      id=""
      class=""
      class_file="plcs-rdl.owl"
      status="open"
      category="minor_technical"
      by=""
      date="04-07-19"
      seds="no"
      ballot_comment="no"
      resolution="accept">
      <description>
    
      </description>
      <issue>

Where:

id: an identifier of the isssue unique to the issue log
class: the class against which the comment has been made
class_file: the owl file in which the class is stored
category: Either: editorial | minor_technical | major_technical | repository
by: person raising the issue
date: date issue raised yy-mm-dd
status: status of issue. Either "open" or "closed"
seds: A formal issue that has been raised after publication. Either "yes" or "no".
ballot_comment: A ballot comment against the class. Either "yes" or "no".
resolution: Indication as to whether the issue has been accepted or rejected. Either "accept" or "reject".

When an issue is addressed, a comment should be added. The form of the comment is:

      <comment
        by="" 
        date="">
        <description>
        </description>
      </comment>

Where:

by: person raising the issue
date: date issue raised yy-mm-dd