OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

regrep message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: FW: [chairs] OASIS TC Process: Reminders, Clarifications, Updates



Some good info here!


Kathryn Breininger
Manager, Standards Authoring, Release, & Technical Orders
Product Standards Office
Boeing Research & Technology
The Boeing Company

MC 62-LC
425-965-0242 desk
425-512-4281 cell
425-237-4582 fax

How are we doing?  Please click on the attached link to take the Product Standards Office Customer Satisfaction Survey.
PSO Customer Survey

-----Original Message-----
From: Robin Cover [mailto:robin@oasis-open.org]
Sent: Monday, March 21, 2011 5:53 PM
To: OASIS Chairs List; TC Members
Cc: Robin Cover
Subject: [chairs] OASIS TC Process: Reminders, Clarifications, Updates

TC Members,

This communication provides reminders, clarifications, and updates on ten (10) topics related to the OASIS TC Administrator's activities to support the TC Process, particularly as governing specification development and publication. The message is being posted to the list tcmembers@ in addition to chairs@ because many of the TC specification editors do not have a Chair/Secretary role (in Kavi), and would not otherwise receive the message.

- What document changes are allowed after an approval ballot?
- May a TC approve an imaginary/nonexistent WD as CSD/CND?
- Are separate submission request forms needed for CD and PR?
- Are the OASIS Naming Directives applicable to all TC work?
- May TC members delete TC resources?
- May TCs request publication or review limited to one part?
- Why is it important to cite publicly accessible URIs?
- Where are the templates for creating TC documents?
- How can we activate a TC Wiki, JIRA Project, or SVN repo?
- May we invite guests to TC meetings?

The ten topics represent permathreads/FAQs, at least for the past eleven weeks, where I have composed similar messages several times, or dozens of times. These were drafted to help TCs transition their work to meet new expectations set by the revised OASIS TC Process (with the two Tracks), the IPR Policy, the new Naming Directives document, revised templates, new TC submission request forms, and updated methods for publishing approved work in the OASIS Library. I feel that the information below is needed with enough frequency to justify a general memo.

Some of the reminders apply especially to TC Chairs, Editors, Secretaries, or Webmasters; others apply broadly to all TC Members who participate in meetings or contribute content to the TC mailing list(s), TC repositories, issues tracking system, Wiki, Subversion (SVN version control system), etc.

For each topic I provide a summary, with reference(s) in "[n]" notation to further detail in the final section "Notes and References".

Personal note:

As Interim TC Admin for a few weeks I have had opportunity to work with many Chairs and other TC participants as the transition work is underway.  I have not been able to provide timely assistance in many cases, and deeply regret my own limitations. I know that Member expectations have not been met. Going forward: Paul Knight is joining Staff to help in the transition as we orient a new TC Admin lead.

With respect to the details of this memo: all dispositions and actions of the OASIS TC Admin are subject to review by the Board. I am accountable to the Members and to the Board for Administration of the TC Process; in any ruling or opinion I may be persuaded or required to change my mind, and am prepared to do so. The TC Admin work, including the production and maintenance of documentation, is an evolving practice, attempting to take into consideration Member needs and preferences as well as changing policies and tools, all within resourcing constraints.

Please send feedback/comments on this memo to Robin Cover (robin@oasis-open.org).

==============================================================
#1 What document changes are allowed after an approval ballot?
==============================================================

A TC specification or other document which has been approved may not be changed without assigning new/incremented Working Draft level identifiers for version/revision, OTHER than a small number of allowable changes that are
(typically) made by TC Admin in the act of publication.

TCs are therefore reminded that they need to carefully examine a Working Draft that is candidate for approval; once approved at CD level, content and hyperlink changes, for example, cannot be made. [1]

==============================================================
#2 May a TC approve an imaginary/nonexistent WD as CSD/CND?
==============================================================

The occasional allowance made by TC Admin in the past for approval of a Working Draft "subject to certain changes..."
is being discontinued, primarily for resourcing reasons.
TC Admin does not have time to verify that ONLY certain kinds/classes of changes, or changes consistent with a certain stated goal, or ONLY certain enumerated changes, have actually been made in a Working Draft that's approved for CD.  This practice is judged procedurally suspect, and has created numerous problems due to ambiguity, demonstrable lack of adherence to limited specified changes, and other consequences.

Until further notice, motions to approve a WD as CSD/CND must be made with reference to an existing, published Working Draft release -- one that actually exists at the date/time of the motion, as clarified in the TC Handbook.
[2]

==============================================================
#3 Are separate submission request forms needed for CD and PR?
==============================================================

Yes. TCs sometimes combine into a single meeting (or motion) the approval of a WD at CSD/CND level and approval to advance the CD to Public Review status.  The TC Process allows direct progression of a CSD or CND to CSPRD/CNPRD without an intervening WD, but the CD - PR requests to TC Admin should be made separately, using two different online forms, available from the document titled "TC Administration Requests". [3]

==============================================================
#4 Are the OASIS Naming Directives applicable to all TC work?
==============================================================

Not universally, not yet. Accommodations are made to grandfather older TC naming patterns and practices for any specification at the current Version.  TC Admin continues to work with individual TCs to migrate practices for resource identification so that they conform to the Naming Directives document rules for use of directories (paths/URIs) and filenames.  But for any Work Product at the current Version #.# level, TCs are given the option of continuing older/legacy naming patterns.

When TCs identify new deliverables, including development of Work Products as a new Version, the expectation is that the identifiers and other features will conform to the new Naming Directives. [4]

http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html


==============================================================
#5 May TC members delete TC resources?
==============================================================

Deletion of TC content created/uploaded is forbidden by rule, even though some OASIS facilities may not be configured to prevent resource deletion. All members are asked to honor this directive.

The formulation of this principle in the revised Naming Directives document (similar to text from the 2006 Naming
Guidelines) is as follows:

    "As part of the OASIS commitment to transparency, openness,
    and accountability, resources published in the OASIS Library,
    TC Document Repository, and other venues must not be deleted.
    All revisions are retained. With the exception of resources
    identified by "latest version" URI aliases, content
    instantiated as regular files and directories must not be
    over-written, replaced, renamed, or removed. TC Members are
    expected to follow this rule even in cases where a
    collaboration tool (by some means) might allow resource
    deletion." [5]


==============================================================
#6 May TCs request publication or review limited to one part?
==============================================================

TCs are hereby reminded that each release of a Work Product, as well as interim Working Drafts as candidates for approval, must clearly identify all parts (directories, files) that are constituent parts of the release.  No parts may be excluded, and no parts may be progressed/advanced/approved independent of the whole.  Since almost all Work products are multi-part, and increasingly so, planning and careful attention are in order [6].


==============================================================
#7 Why is it important to cite publicly accessible URIs?
==============================================================

Using member-only URIs (password-protected resource identifiers) has a detrimental effect on OASIS because it creates the impression that OASIS is not truly "open" -- apparently denying visibility and access to the public.  When non-OASIS members click on hyperlinks for member-only URIs, they will not imagine that the resource is actually available, IF ONLY one knows the magic transform to construct a URI for the online resource using a non-password-protected link.

TC Chairs and Editors are urged to exercise vigilance and exemplary/model behavior by always citing public URIs, and to remind TC members when the requirement is being overlooked in TC contributions. [7]

==============================================================
#8 Where are the templates for creating TC documents?
==============================================================

See the two dedicated documents that are part of the 2010-10 OASIS TC Handbook [8]

A. Standards Track Templates
http://docs.oasis-open.org/TChandbook/Reference/StandardsTrackTemplates.html

B. Non-Standards Track Templates
http://docs.oasis-open.org/TChandbook/Reference/NonStandardsTrackTemplates.html

==============================================================
#9 How can we activate a TC Wiki, JIRA Project, or SVN repo?
==============================================================

A TC may request installation and configuration of a Wiki, JIRA Issues Tracker Project, or Subversion (SVN) version control system repository using email: the TC Chair should send email to TC Admin (tc-admin@oasis-open.org). [9]

==============================================================
#10 May we invite guests to TC meetings?
==============================================================

Guests are not allowed to attend regular TC meetings, but could be invited to attend and participate in a meeting designated as an unofficial event (outside the scope of authority for TC Process and IPR Policy). A "guest" in this context means any person other than a TC Member (Voting Member, Member, Persistent Non-Voting Member, Secretary, Chair) or TC Observer. [10]

- Respectfully submitted,
   Robin

Robin Cover
Interim TC Administrator
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783

======== Notes and References ========

------------------------------------------------------------------------

[1] Further on allowed changes to an approved document

As described in the TC Process and TC Handbook, the only changes allowed in a document approved by a TC are those changes associated with publication to reflect the new status of the approved Work Product. The seven (7) allowed changes are made by TC Admin in the process of publication after the approval of the Work Product.

TCs sometimes ask for permission to introduce minor changes after document approval, or ask the TC Administrator to make these changes -- often called "tweaks".  The most common kinds of changes requested are to fix obvious typos, to repair incorrectly formatted hyperlinks, or to adjust hyperlink destinations, etc. Except for changes enumerated in the TC Process "2.18 Work Product Quality, Allowed changes", these trivial changes are disallowed, however seemingly minor or obvious.

The TC Administrator will create the correct URI references in the document cover page to match the approval level, etc, as well as in headers/footers, as applicable. No changes will be made to the document (body) content, which includes References (unless Designated Cross References or citation of a new OASIS Standard). The allowed changes are for metadata items as part of the act of publishing.


2.18 Work Product Quality, Allowed changes http://www.oasis-open.org/committees/process-2010-07-28.php#quality-allowedChanges
http://docs.oasis-open.org/TChandbook/Reference/WPQualityRequirements.html
   sub: Allowed Changes

See also TC Process:

3.2. Public Review of a Committee Draft
3.4.1 Submission of a Candidate OASIS Standard

------------------------------------------------------------------------

[2] Further on motions to approve an imagined WD

In recent history (e.g., 2009-2011), TC Admin has occasionally made accommodation to a TC's perceived need to approve a Working Draft as a CD where the WD exists only notionally.
For example: "I move to approve WD14 as a Committee [Note/ Specification] Draft, with the correction of one URI reference that John mentioned in this morning's email message to the TC list."  Or: "I move to authorize the editor of FOO specification to correct all the schemas according to the prose specification intent, and that the new WD06 package be approved as CSD02."

Steps were taken in October 2010 to put an end to this practice of allowing motions that approved imaginary, nonexistent Working Drafts at CD level, and similarly for other kinds of motions to approve documents not instantiated. The TC Handbook (2010-10-15) thus stated, for example, with respect to CSD, that a WD number and publication date be referenced to unambiguously identify an existing document:

    "A Working Draft must be approved by a Full Majority
    Vote of the TC as a Committee Specification Draft (CSD)
    before any further lifecycle progression can occur. The
    motion must include the Working Draft number and date."

The online form for a Committee Specification Draft Creation and Upload Request similarly asked for a specific Working Draft Number and Working Draft URL in support of the goal that an existing Working Draft be named in the motion to approve:

    "Working Draft Number: Please enter the working draft
    number (WD##) that was approved as a Committee
    Specification Draft by the TC

    Working Draft URL: Please provide a link to a zip file
    containing all of the necessary resources including the
    editable source of the working draft and any related
    resources such as namespace documents or schema files."

Committee Specification Draft Creation / Upload Request http://marypmcrae.com/csd-creation-request
   from:
TC Administration Requests
http://docs.oasis-open.org/templates/TCAdminRequests15-10-2010.html

Resourcing problems have arisen operationally because some TCs (increasingly) have continued to approve imaginary WDs, where the TC Handbook and forms were intended to require nomination of existing WDs.

As of 2011-03-18, the TC Handbook reads as follows, to bring greater clarity:

    "The motion to approve at CSD level must include the
    Working Draft identifier for a resource which has been
    published at the time of the motion, including: title,
    publication date, and URI. For the Working Draft URI,
    please provide a link to a ZIP file containing all of
    the necessary resources, including the editable source
    of the Working Draft and any related resources such as
    namespace document drafts, XML schema files, XML
    instances, and all files that are part of the Work
    Product."

We (previous and current TC Admin) believe the above requirement is needed not only as a practical matter, but is consistent with the intent of the TC Process on document approvals, revisioning, and allowed changes.

E.g., "The TC may at any stage during development of a Work Product approve a Working Draft as a Committee Specification Draft or Committee Note Draft, as appropriate.
Approval of these drafts shall require a Full Majority Vote of the TC. The TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Specification Draft or Committee Note Draft.


------------------------------------------------------------------------

[3] Further on separate submission request forms needed for
     CD and PR

TC Administration Requests
http://docs.oasis-open.org/templates/TCAdminRequests15-10-2010.html
See in that document the section: "Public Review Requests"

Different forms are used for different kinds of reviews. If a TC desires a review period longer than the required minimum number of days: use the form most similar to the intent and present the special request in the Note field.

------------------------------------------------------------------------


[4] Further on the OASIS Naming Directives

The "OASIS Naming Directives" document was published on October 14, 2010 to align with the new TC Process. It introduces a number of changes for the construction of specification URIs
(paths/directories) and filenames for approved work, which is published in the OASIS Library. This document was produced by Staff and TAB, with review from selected document experts, as a revision of the "OASIS Naming Guidelines" in two parts, approved by the OASIS Board initially in 2006. The document continues to be updated in minor (non-substantive) ways to provide clarify; any substantive changes are reviewed by TAB, and possibly by other experts.

The "Naming Directives" are referenced in TC Process under the phrase "the OASIS file naming scheme" - see:
http://www.oasis-open.org/committees/process-2010-07-28.php#quality-general

The two rules which specifically address URIs (paths) and filenames are as follows, where the tokens are defined in the respective document sections:

Path/URI:
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#paths
  pattern:
http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/[doc-id].[ext]

Filename:
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#nameConstruction
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#filenameSyntax
  pattern:
[WP-abbrev]-[version-id]-[stage-abbrev][revisionNumber].[ext] ==
[doc-id                                               ].[ext]

OASIS Naming Directives
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html

OASIS Naming Guidelines, In Two Parts
Part 1: Filenames, URIs, Namespaces
Part 2: Metadata and Versioning
http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNaming.html
http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html

------------------------------------------------------------------------

[5] Further on resource permanence and non-deletion

Resource Permanence
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#resourcePermanence
URI Persistence
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#URI-persistence

The two URIs preceding in the Naming Directives were updates to the Naming Guidelines, initially approved by the OASIS Board in 2006

http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingV05.html
with commentary:

"Assignment of URIs to resources is considered to be permanent except for a small class of approved exceptions, documented by the TC Administration (e.g., "Latest version: " URI), so files may be revisioned but not overwritten. This rule applies to secondary resources identified by fragment identifier...

Once assigned to a resource, an identifier (URI) should never be retired and re-assigned to some other resource: the relationship between identifier and resource should be considered fixed and unseverable. This applies to primary resources (e.g., a conceptual whole document) and to secondary resources associated with a fragment identifier component of a URI [post-pound # fragment portion]. Some CMS products [Moin Wiki] will rewrite the value of an (X)HTML ID attribute when a document is saved -- breaking URI references that link to internal document components."

http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingCommentaryV05.html#URI-Design
http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamingCommentaryV05.html#secondaryResources

------------------------------------------------------------------------

[6] Further on Multi-Part Work Products

The TC Process description of a Multi-Part Work Product specifies that all constituent parts be clearly identified, have a single Work Product name, a single version/revision number, and that the Work Product be treated as one entity -- (as a whole) must be approved by a single Work Product Ballot.

Lack of clarity in some TCs about part-whole relations has led to delays in spec development and publication when it became clear that certain components were (or were not) intended as "parts" of a whole, or when it was learned that no "part" can be excluded from public review, and no "part" can be nominated by itself for public review (via defined "Work Product Approval Motion" and "Work Product Ballot."

In practice, TCs should understand that a ZIP archive which represents a Working Draft candidate-for-approval or other
(approved) release package is treated as the entire Work
Product: no components may be omitted, and any components included in the ZIP file are assumed to be part of the release.

http://www.oasis-open.org/committees/process-2010-07-28.php#quality-multiPart
http://docs.oasis-open.org/TChandbook/Reference/WPQualityRequirements.html#multi-part


------------------------------------------------------------------------


[7] Further on publicly accessible URIs for OASIS resources

TC members are reminded that only publicly accessible URIs should be used in TC documents (e.g., in Wiki articles, in email messages, JIRA issue comments, in submission request forms, and other document genres). The correct (public) URIs for resources are visible for documents and archived messages, etc. by using the public repositories rather than using the Kavi member-only interfaces.  For any kind of resource, the transform from private/member-only to public is documented in the Naming Directives.

http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#accessibleURIs

------------------------------------------------------------------------

[8] Further on document "templates"

The term "template" can be confusing because the resources are not word processing templates. As of October 2010, the instance represents an initial (Working Draft level) starter document that is provided to a TC by TC Admin.

See also the description of DocBook and DITA authoring environment templates from the Work Product Quality Checklist document in the Handbook, and the /templates/ directory in the OASIS Library

http://docs.oasis-open.org/TChandbook/Reference/WPQualityChecklist.html#templates

Work Product Templates
http://docs.oasis-open.org/templates/

How are "templates" used under the new process?

a) Someone fills in a submission request for a "template"
    using the online form for a Work Product Registration;
    the form requests essential metadata, identification of
    intended Track, and designation of document type for
    Non-Standards Track

b) When submitted, the forms processing creates a JIRA issue
    in the TCADMIN JIRA queue; the TC receives notification
    of the submission request

c) TC admin prepares an initial starter Working Draft level
    document using the metadata and other form information.
    This document lacks typical cover page information; see
    below #10 for structural elements present in WD vs approved.

d) TC Admin returns the Working Draft (01) to the TC or to
    the requester, with instructions for use (and request for
    feedback on usability)  Example:
    http://lists.oasis-open.org/archives/cmis/201103/msg00022.html
    http://lists.oasis-open.org/archives/cmis/201103/msg00026.html
    http://lists.oasis-open.org/archives/cmis/201103/doc00000.doc
     filename = cmis-v1.1-wd01.doc

e) The editors of the Working Draft create initial content
    for the initial starter document (01); create additional
    WD revisions WD02, WD03... upload WDs to Kavi, ask for
    internal review, etc

f) At some juncture (let's say WD04) the TC approves the
    WD (WD04) as CD and fills in a form for CSD/CND publication
    in the OASIS Library.  Further editorial work continues on
    the WD which is rev'd to WD05 at the next Kavi upload event.

g) If TC Admin judges that the CD-level Work Product as approved
    meets the requirements (quality) for publication, the CSD
    (CSD01, CSD02, CSD03...) is published in the OASIS Library;
    if fatal defects are found by TC Admin in the candidate
    CSD, the TC is notified and the release is rejected
    as a valid CD. The published document adds a cover page
    using available metadata. including possibly information
    updated in a WD (word processor) Custom Properties.

------------------------------------------------------------------------

[9] Further on Wiki, JIRA, SVN

For usage of these (optional) tools as publication venues,
see:

Welcome to OASIS Tools
http://tools.oasis-open.org/
  with key URIs:
TC Wiki instances:    http://wiki.oasis-open.org/
JIRA Issues tracking: http://tools.oasis-open.org/issues/secure/Dashboard.jspa
Subversion (SVN):     http://tools.oasis-open.org/version-control

Note on Wikis: The boilerplate documentation for TC Wikis is slightly out-of-date, and potentially misleading:

   "Wiki pages are transient documents, so intermediate edits
    may not be saved. TC members should move all permanent
    work and stable artifacts to the TC's document repository,
    where the archival work product of the TC also can be
    viewed by the public."

That text represents an initial guess, but in the years since we began using Moin, I know of no instances where versioned information has been lost. Guidance about storing content in Kavi ("the TC's document repository") is still advisable.

------------------------------------------------------------------------

[10]  Further on inviting guests to (TC) meetings.

TCs sometimes use the OASIS event management and notification machinery to advertise meetings that do not count for quorum or gaining/losing voting rights, and similarly, for advertising conference calls hosted by a member company which are not intended as official TC meetings. Guests are sometimes invited to present, or otherwise participate.

Narrowly, on the matte of inviting guests to official TC meetings, this text was prepared in another context by Jamie Clark (OASIS Staff member):

   ****************************************************

"Occasionally, we see TC meeting reports or minutes that refer to non-member 'guests' attending a TC meeting.

This is a reminder that, because all contributions to a TC must come from TC members, in order to be used by the TC under our IPR Policy, official TC meetings are not open to non-TC members.  That's not a waivable requirement, as it is necessary to OASIS applying proper open licensing to the output of TCs.

This does not mean we must be hostile to input from other OASIS members or non-members. TCs often have scheduled open seminars (face-to-face or telephonic), to which others may be invited and attend, so long as those sessions are clearly delineated from a TC meeting. Such informal sessions, even if they abut a TC meeting, have no IPR covenant conditions, and help make clear the distinction.

Of course, non-TC-members always can also make technical contributions via the public comment facilities, or by joining the TC."

   ****************************************************

------------------------------------------------------------------------


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]