[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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]