[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]