Notes on formal aspects common to OASIS OData TC’s meeting minutes

Reference-ID: formal-aspects-meeting-minutes-v1-20130201
Version: 1.0-20130201 

1. Review of Action Items (AI) and Progress

Action items are referenced by their local ID as generated by the Kavi-Tool upon creation. This ID consists of the constant string AI# and an automatically incremented number padded to the left with zeros and to 4 digits like eg. AI#0123.

The ownership of action items is noted [owner: Given Family] and as indicated by the AI-List-Tool. Additionally the time stamp of retrieval is given in the preamble. The list of open action items (before the meeting) may be documented in an appendix esp. in longer minutes to help the reader foxus on the actual progress being made during the meeting.

1.1 Linking to AI progression sections in meeting minutes

The linkage to the documentation of an action items specific state progression inside meeting minutes SHOULD be provided through a publicly accessible URL of the meeting minutes. To ease the navigation for the reader this link MAY have a fractional part which is the lowercased action items ID where the ’#’sign has of course been stripped. For meeting minutes this fractional target is guaranteed to point to the relevant subsection of the minutes.

As an example, for linking the action item AI#0005 to its state progression (from ‘Ongoing (Note: Due 2013–01–10)’ to ‘Ongoing (Note: Due 2013–01–31)’) during meeting#20 the specific public URL is (fractional part=’ai0005’):

https://www.oasis-open.org/committees/download.php/47861/odata-meeting–20_on–20130110-minutes.html#ai0005

2 Review of Issues List (IL) and Progress

Issues are referenced by their local ID as generated by JIRA upon creation. This ID consists of the constant string ODATA- and an automatically incremented number like eg. ODATA–123. The list of processed issues may be documented in an appendix esp. in longer minutes to help the reader focus on the actual progress being made during the meeting and as a navigational support. If such an index is provided, it will have at most two main parts: First come the public comments (if any), second the JIRA issues. Each list of issues is sorted by ascending issue number. Noted are the ID, the summary and the reference to the relevant subsection where the issue progression has been documented.

2.1 Notation of Issue State Progressions during Meetings

We minute an issue state progression as an ordered triple consisting of:

  1. The initial issue summary (including its status before the meeting)
  2. Discussion content and decisions i.e. formally required motion text potentially overriding a proposed solution (of the issue’s instance in JIRA) at the time of the meeting.
  3. The resulting issue summary (including its updated status plus eventual modifications linking to the motion text after the meeting)

The rationale behind this is: a) to document the initial status - which may well deviate from the (tentative) status set inside the instance in JIRA at that time, b) to optimize the transfer of changes resulting from the discussion back into the issue’s instance inside JIRA (if dictated by the accepted motion) and last but not least c) to ease the lookup for the reader.

The value of the main status is one (and only one) from the set (New, Open, Deferred, Proposed, Resolved, Applied or Closed) as documented in “Best Practices for Issue Handling”, where the states and transitions are further explained as they have been adopted by the TC.

A step by step recipe on how to apply these resolutions to new revisions of work products is given in “How to Apply Resolved Issues” and shall assist the editors performing the many formally necessary (but often purely mechanical) steps needing attention along the way.

2.2 Lifecycle of ‘Mainstream’ Issues

For the purpose of this section any issue that results in an implemented change will be considered a ‘mainstream’ issue. The typical lifecycle of such an issue and with focus on the relation between actions, status and documentation in meeting minutes may be illustrated as:

  1. Created as New by Reporter -> New [+ Comments]
  2. [optional as step 2] The Proposed flag can be set during New discussions to indicate that the issues’ proposal is ready for resolution. If and only if this is the case, then the steps labelled 3 and 4 may be skipped. In all other cases the step labelled 4 will be mandatory.
  3. Accepted as Open by TC -> Open [+ Discussions [+ Motion [+ Amendment] ] ]
  4. [optional as step 4, but mandatory as status] The Proposed flag can be set during Open discussions to indicate that a proposal is ready for resolution. Only ready to implemented proposals will be resolved by the TC.
  5. Resolved as Proposed by TC -> Resolved
  6. Implementation during work phase visible to the editor.
  7. Signalled as Applied by Editor -> Applied [+ Discussions [+ Motion [+ Amendment] ] ]
  8. Closed as Applied by TC -> Closed

The relation of incoming and outgoind issues states is further listed and explained in the following subsection. Any remaining details on available issue states and transitions may be found in “Best Practices for Issue Handling”.

2.2.1 Relation of Incoming and Outgoing Issue States

The issues that are put on a TC meeting agenda MUST have one of the three following incoming states:

  1. New+Proposed
  2. Open+Proposed
  3. Applied

For each of those incoming issue states, the corresponding possible outgoing states - amended with explanations (noted in parentheses) - are:

  1. Incoming state: New+Proposed implies the possible outgoing states:
    1. New+Proposed (TC did not act on this),
    2. Open+Proposed (TC agreed to open but has not resolved yet),
    3. New (TC removed the issue from Proposed since the proposal was not complete),
    4. Open (TC accepted the issue but removed the issue from Proposed since the proposal was not complete),
    5. Resolved (successfully resolved),
    6. Closed (TC closed issue with no further action).
  2. Incoming state: Open+Proposed implies the possible outgoing states:
    1. Open+Proposed (TC did not act on this),
    2. Open (TC accepted the issue but removed the issue from Proposed since the proposal was not complete),
    3. Resolved (successfully resolved),
    4. Closed (TC closed issue with no further action).
  3. Incoming state: Applied implies the possible outgoing states:
    1. Resolved (if the TC disagrees with the application of the resolution),
    2. Closed (TC agrees with the application of the resolution).

2.3 Linking from JIRA issues to state progression sections in meeting minutes

The linkage from the representation of an issue as noted in JIRA to the documentation of its specific state progression inside meeting minutes SHOULD be provided through a publicly accessible URL of the meeting minutes. To ease the navigation for the reader this link MAY have a fractional part which is the lowercased issues ID. For meeting minutes this fractional target is guaranteed to point to the relevant subsection of the minutes.

As an example, for linking the issue ODATA–13 to its state progression (from New to New+Proposed) during meeting#20 the specific public URL is (fractional part=’odata–13’):

https://www.oasis-open.org/committees/download.php/47861/odata-meeting–20_on–20130110-minutes.html#odata–13

The corresponding private URL (only visible to TC members) would be:

https://www.oasis-open.org/apps/org/workgroup/odata/download.php/47861/latest/odata-meeting–20_on–20130110-minutes.html#odata–13

As we tend to keep the filenames persistent, one can usually build the public from the private URL by

  1. replacing ‘apps/org/workgroup/odata/’ with ‘committees/’ and
  2. removing ‘latest/’

Thereby we maximize the public navigation experience throughout our documentation.

2.4 Issues related to Public Comments

If an issue created in JIRA is related to a public comment (eg. because it has been accepted as an issue by the TC) the subject of the JIRA issue should follow the format as described in section [3.2].

3 Notation of Public Comments and Relations to Minutes and Issues

Public comments are referenced by their local ID pair as generated by the OASIS mailing list archiver upon receipt. The derived ID consists of the string literal c the ‘YYYYMM’ string from the year month folder, the string literal e and automatically incremented number padded to the left with zeros and to 5 digits like eg. c201301e00001.

3.1 Linking from Public Comments to processing sections in meeting minutes

Abiding the rules of OASIS all comments are acknowledged and considered. So every comment received through the single entry point odata-comment will be reflected in one or more meeting minutes.

The linkage from the representation of received comment as noted in the public comment archive rooted at https://lists.oasis-open.org/archives/odata-comment/ to the documentation of its specific processing inside meeting minutes SHOULD be provided through a publicly accessible URL of the meeting minutes. To ease the navigation for the reader this link MAY have a fractional part which is the derived ID as described in section [3]. For meeting minutes this fractional target is guaranteed to point to the relevant subsection of the minutes.

3.2 Linking from Issues to Public Comments

If a comment results in an issue created in JIRA the subject of the issue should indicate this by appending the string literal (public comment $ceID) with $ceID being replaced with the commentEntryID as described in section [3] (cf. [sample] below).

It is also beneficial, if the description of the JIRA issue starts with text following the pattern:

The public comment 
[$ceID](https://lists.oasis-open.org/archives/odata-comment/$yearMonth/msg$entryID.html) 
with title "$subjectOrTitle" indicates, ...

with:

3.2.1 Sample for Comment Linkage Notation in Issues

As a sample, the first comment received, resulted in issue ODATA–232 with the summary:

“Enhance description of normalization procedures (public comment c201301e00001)”

and the description:

“The public comment c201301e00001 with title ”Query String parsing in URIs“ indicates, that the description of normalization procedures in the ABNF Construction Rules can be enhanced.”.