|
|
UDDI Spec TC
|
UDDI Spec TC Process
12 December 2002
Document identifier:
uddi-spec-tc-process-20021212
Location:
http://www.oasis-open.org/committees/uddi-spec/doc/process/uddi-spec-tc-process-20021212.htm
Editors:
Tom Bellwood, IBM <bellwood@us.ibm.com>
Luc Clément, Microsoft <lclement@microsoft.com>
Contributors:
Abstract:
This document describes the UDDI Specification TC processes as they relate to the OASIS Committee Specification Process. These include the UDDI Specification, Best Practices, Technical Notes and Document Management processes.
Status:
This document is updated periodically on no particular schedule. Send comments to the editors.
Committee members should send comments on this specification to the uddi-spec@lists.oasis-open.org list. Others should subscribe to and send comments to the uddi-spec-comment@lists.oasis-open.org list. To subscribe, send an email message to uddi-spec-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.
Table of Contents
1.1 Requirements Specification
1.2 Definition of Roles in Specification Development
1.4 Basic Principles of Specification Development
1.5 Stages of Specification Development
1.6 Specification Change Request and Errata Process
1.6.1 Specification Change Request
1.6.2 Specification Errata Process
2 Spec TC Best Practices and Technical Notes
2.1 Best Practice and Technical Note Criteria
3.3 Posting to UDDI Spec TC Page
This document describes UDDI Specification TC processes as they relate to the OASIS Committee Specification Process. These include the UDDI Specification, Best Practices, Technical Notes and Document Management processes.
This section describes the phases of development and the life-cycle of an UDDI Specification TC Committee Specification.
1.1 Requirements Specification
Requirements Specification documents are used to identify refine and prioritize requirements for a future specification.
· Requirements are driven by the TC membership and input from the public via the TC public comment list (uddi-spec-comment)
· The TC members discuss, refine or discard, and prioritize these requirements as needed.
· TC Chairs will call for a vote of the TC to approve the requirements.
o These TC votes require a simple majority of the voting quorum.
· Approved Requirements Specifications are made public on the TC web page
1.2 Definition of Roles in Specification Development
We define several roles here which participate in the specification development process. They are:
· Contributor: A contributor is someone who proposes and/or debates technical content for a specification, a specification component, a Best Practice, or a Technical Note. Generally, all members of the TC and/or a subcommittee developing such documents are considered contributors. Contributors need not be TC members though. Attribution of non-TC members in TC Specifications is at the discretion of the TC.
· Author: An author is one who creates written content which becomes part of a specification or other document produced by the TC or one of its subcommittees. There are often multiple authors for a document. Authors should not overlap responsibility for document sections.
· Editor: An editor is one who acts on behalf of the group to perform editorial tasks associated with the creation of a specification, a Best Practice or a Technical Note. This also includes the merging specification components into an overall specification. While it is intended that this role be held by only one person for a given document, there may be more than one editor defined as necessary.
1.3 Use of Subcommittees
As required, TC Chairs will call for the creation of subcommittees to develop various components of a specification, a Best Practice, or a Technical Note. The following rules apply to subcommittees:
· The TC chairs will call for the formation of and delegate work to subcommittees, whenever appropriate. The TC Chairs will assign a chair of the subcommittee.
· All subcommittee work will be guided by requirements approved by the TC.
· Each subcommittee will choose an editor for work products it produces. One or more authors may participate.
· Subcommittees will meet face-to-face or by phone as often as necessary in order to complete the specification draft components on a schedule agreed to by the TC.
· The subcommittee will use the TC’s private mailing list to carry out its work, unless a separate private mailing list is deemed to be necessary.
· Subcommittee membership and participation is open to all TC members.
· Subcommittees and subcommittee chairs and editors serve at the discretion of the TC chairs.
· Intermediate work products (files), including those for which multiple authors are involved, will be managed on the TC’s YahooGroups uddi-spec group, until an equivalent capability is offered by OASIS.
1.4 Basic Principles of Specification Development
The process by which the UDDI TC develops specifications adheres to the following principles:
- Specification components are developed by the TC and/or its subcommittees.
- Assembly of overall committee specifications into any of the states defined below is performed by the TC (or its delegate(s)), formed by editorial merging of constituent contributions from subcommittees as appropriate.
- No specification or specification component being developed by a subcommittee can exit that subcommittee without the approval of that subcommittee. A simple majority vote of the voting subcommittee quorum applies.
- No specification or specification component can go forward as a TC Specification without the approval of the overall TC. Standard voting rules for TC Specifications defined by the OASIS TC Process apply.
The principles of Technical Note and Best Practice development are outlined in Section 2 of this document.
1.5 Stages of Specification Development
We will define 3 stages of specification development:
1. TC Working Draft: This is the earliest work product of the TC on the path to developing a TC Specification. A Working Draft is an incomplete or work-in-progress document used as a first step in producing a specification. It represents merged content created by the TC and any subcommittees. One or more versions of a Working Draft may be developed during this stage. A specification stays in the Working Draft state until its quality is deemed suitable by TC vote to make it a Candidate Draft. Approval of a Working Draft only requires a simple majority of the voting quorum of the TC. Working Drafts are not made public, however all correspondence and Working Draft content will always be available to all TC members.
2. TC Candidate Draft: This stage of specification development is reached when a Working Draft is approved as such by vote. The criteria for reaching this stage is that the document is now suitable for public consumption – all major content is completed and it stands as a cohesive document. Once a Working Draft is deemed to be complete enough that it is ready for public review, a vote is taken to make it a Candidate Draft. This requires a TC review period lasting a minimum of 30 days, during which time no changes may be made to the document. The vote is taken at the end of this review period after issues raised are resolved by the TC. Any revision necessary as a result of feedback should be made and resubmitted for TC review. An additional 30 day review period should be allowed but may be waived depending on the nature of the changes. Voting rules here require a simple majority of the TC voting quorum. Candidate Draft documents are then posted for public comment. Candidate Draft documents are announced on the TC mail list, and are made available on the TC web page.
3. TC Committee Specification: A public review of a Candidate Draft should take place for a minimum of 30 days, during which time no changes should be made to the document. Any revision necessary as a result of feedback or as deemed necessary by the TC should be made and resubmitted for public review in the form of an updated Candidate Draft version; an additional 30 day review period should be allowed but may be waived depending on the nature of the changes. One or more Candidate Drafts may be created and posted for review before it is ready to become a Committee Specification. At the end of the last review period, the TC Chairs will submit the Candidate Draft for vote as Committee Specification. This state is as defined in the OASIS TC Process. Voting rules here are described in the OASIS TC Process document.
4. OASIS Standard. A TC Committee Specification may be advanced as an OASIS Standard. Rules for doing this are described in the OASIS TC Process.
1.6 Specification Change Request and Errata Process
From time to time, errors, inconsistencies or ambiguities will be discovered in a UDDI TC Specification or UDDI Standard based upon ongoing experience with the specification by those implementing it. Such feedback is essential to improving the quality of these documents.
The specification change request and errata process is intended to address defects found in a specification. It may NOT be used to add new functionality or substantively change existing functionality except as minimally required to effect a fix.
When an error is discovered in one of the UDDI specifications or related documents, the person discovering it should post to the uddi-spec mailing list if he/she is a UDDI Spec TC member or to the public uddi-spec-comment mailing list if they are not. In the latter case, debate on the uddi-spec-comment mailing list shall be sufficient to determine that the problem is valid and requires attention by the TC. The TC shall consider the issue, debate it, and reach agreement that it justifies a change to the specification. Such debate should occur on the uddi-spec mailing list..
When a consensus appears to be reached, the TC Chairs will inform the person having made the discovery to prepare a Specification Change Request (CR) and submit it, or in the case where the individual is not a member of the TC, the TC Chairs will delegate this responsibility to a TC member; IPR rules should be reiterated at that time by the TC Chairs.
1.6.1 Specification Change Request
Upon submission of the CR, the TC Chairs will assign it a tracking number and the CR will be assigned to an editor(s) for consideration as errata. This information will be tracked by the TC Chairs. The editor(s) of the affected document takes responsibility for the change and adds it to a list of candidate erratum for making up an errata package. In the course of preparing the revised text, further dialog and a number of drafts may be required between editors and the TC. This business will be carried out on the TC’s uddi-spec mailing list. Once the TC agrees to produce an erratum for the item, this information is communicated back to the uddi-spec-comment mailing list if the person who submitted it was not a member of the TC.
The Specification Change Request template located at http://www.oasis-open.org/committees/uddi-spec/doc/templates/uddi-spec-tc-cr-template.doc will be used to make submissions.
Upon submission and agreement by the TC that the error is indeed valid and should be corrected, the completed form is provided to the editor(s) of the appropriate specifications for consideration. If the Editor(s) determine that further work is required to integrate the proposed correction, they inform the TC and the Chair will call for a subcommittee to develop a workable solution. Otherwise, the editors will include the work as errata using the Specification Errata Process described in the following section.
1.6.2 Specification Errata Process
The process for integrating a set of errata into a specification is as follows:
· In consultation with the TC Chairs, once the editor(s) determine they have integrated a sufficient number of erratum to justify the release of an errata document / or revised spec is released to the TC for review.
· The errata is posted together with a marked up version of the specification document for a 15 day review period by the TC members, during which time no changes should be made to either the errata or the marked up document. These will be posted on the uddi-spec YahooGroup.
· Any revision necessary as a result of feedback should be made and resubmitted for review; an additional 15 day review period should be allowed but may be waived depending on the nature of the changes.
· At the end of the review period, the TC Chairs will submit the errata and amended specification document for vote. Voting rules for this vote are the same as for approval of a TC Committee Specification, as documented in the OASIS TC Process.
· Approved errata documents and the corresponding updated specifications will be posted on the TC’s web site.
1.7 Versioning of Specifications
This section addresses how specifications will be versioned. Revisions to a specification will result due to the incorporation of errata.
Errors and corrections (errata and corrigenda) to a specification will be collected over a period of time by the TC. The editors may provide drafts that reflect those changes from time to time though these will not be released publicly. When the TC wants to publish a revised version of a given specification as "completed and approved work of the TC," the specification will be identified with a “minor” revision number (i.e. a “dot” release such as 2.1 or 3.1), and approved by vote of the TC in accordance with TC voting rules for specifications.
As such, an errata set will be tied to an update of the version numbers associated with each of the specifications which make up the version of UDDI being amended. All version numbers of all such documents will be updated to a matching level for such releases of errata sets.
The UDDI Spec TC from time to time publishes Best Practices and Technical Notes. The contents of these documents are not a part of the specifications.
A Best Practice is a non-normative document accompanying a UDDI Specification that provides guidance on how to use UDDI registries. Best Practices not only represent the TC’s view on some UDDI-related topic, but also represent well-established practice.
A Technical Note is a non-normative document accompanying the UDDI Specification that provides guidance on how to use UDDI registries. While Technical Notes represent the TC’s view on some UDDI-related topic, they may be prospective in nature and need not document existing practice.
2.1 Best Practice and Technical Note Criteria
Non-normative documents fall into one of the following 2 categories; Best Practice and Technical Note. Documents may change classifications over time. For purpose of illustration, a document may be proposed, developed and submitted for consideration as a Technical Note (2), and then as it gains approval and adoption through sufficient practical experience in the industry, progress to become a Best Practice (1) if approved as such by the TC.
(1) UDDI Spec TC Best Practice
§ How: BPs must follow the same voting rules as for the approval of a TC Specification
§ What: BPs must be based on demonstrated experience. BPs should reflect tried, tested, and generally-agreed-upon solutions to frequently asked questions.
(2) UDDI Spec TC Technical Note
§ How: Simple Majority Vote
§ What: TC majority opinion on frequently asked questions where we don't have tried & tested experience OR on topics we feel require a published opinion.
2.2 Proposal
A best practice or technical note may be written about a real implementation or application of UDDI to solve a business or technical problem, or it may be written to provide recommendations regarding interaction between UDDI and other technologies and/or standards where a widely adopted practice would benefit the Web services community.
The Proposal stage is optional, but gives one the opportunity to present the idea for the submission to the TC without the need for investing the work necessary to prepare a completed work. A proposal may take the form of a simple abstract submitted to the TC mailing list, or may even be proposed as a topic of discussion at a TC meeting. The individual making the proposal can then gauge the support present in the TC for developing the work before proceeding to the next stage.
Individuals intending to submit proposals should use the technical note or best practice templates available at the following locations respectively http://www.oasis-open.org/committees/uddi-spec/doc/templates/uddi-spec-tc-tn-template.doc and http://www.oasis-open.org/committees/uddi-spec/doc/templates/uddi-spec-tc-bp-template.doc.
2.3 Submission
To be considered by the TC, the best practice/technical note submission must be based on a Committee Specification or OASIS Standard version of the UDDI specification. A best practice/technical note based on a future release of the UDDI specification may be created, but it will not be published until that version of the UDDI specification is released.
OASIS IPR rules and procedures apply for any TN/BP material submission.
Technical notes or best practices must use the format of the documents available at the following locations respectively http://www.oasis-open.org/committees/uddi-spec/doc/templates/uddi-spec-tc-tn-template.doc and http://www.oasis-open.org/committees/uddi-spec/doc/templates/uddi-spec-tc-bp-template.doc/.
2.4 Review
Within the period of 2 TC meetings, of the submission, an editing team will be assigned to the document by the TC Chairs. Members of the editing team will have experience in the subject matter and should be able to provide feedback to the author(s) and assist in editing the draft, if necessary. This team will review the submission and provide feedback to the author(s) within 2 TC Meetings, unless the team requests an extension to complete its work. In carrying out its work, the team should aim to reach consensus including the decision to extend. If the review team determines that the work cannot be completed in a reasonable time, the Chair has the right to reassign or table the effort.
The team will use the TC’s private mailing list to carry out its work, unless a separate private mailing list is deemed to be necessary.
After the editing team and author(s) have completed reviewing the edited draft, and after any issues they raise have been resolved with the Best Practice/Technical Note author(s), the document will be formally submitted to the TC at large for feedback and review. The TC has 30 days to comment on the BP/TN. Following resolution of any issues raised by the TC the BP/TN will be put to vote by the TC. In the case of a BP/TN which pertains to a future specification which has not yet been approved, the vote is automatically deferred until after that specification is approved as a TC Specification.
2.5 Assignment of Editors
For any document proposed as a Technical Note (2) or a Best Practice (1):
a) There will be a minimum of 2 editors, each from organizations other than that of the author. If 2 editors cannot be obtained, than the proposal is automatically rejected unless the author requests that consideration be deferred to a specific later date. If at that time 2 editors willing to serve cannot be found, the proposal is rejected.
b) Both the editors and the author need to reach agreement on content, failing this, the submission is rejected.
2.6 Voting Rules
For a Technical Note (2) a simple majority vote of the TC voting quorum in favor of creating a Technical Note is required.
For a Best Practice (BP) a TC vote follows the same rules as for approval of a TC Specification, as documented in the OASIS TC Process
Once accepted, the TN or BP will be posted as appropriate to the TC’s Web page.
2.7 Revision
Revisions to Best Practice/Technical Notes documents will be subjected to the same cycle for posting as new documents.
3.1 Naming Convention
The file naming convention for uddi document will be in the following form:
"uddi-spec-tc-zz-xxx-200ymmdd-yy"
where:
· “tc” is included if the document is a Technical Note
· “zz” used for Best Practices, Technical Notes or Change Requests and denoted as bp, tn or cr respectively
· xxx represents the topic using a "reasonable" number of characters to depict the content
· yy denotes a Working Draft (wd), a Candidate Draft (cd), a Committee Specification (cs) or an OASIS Standard (std). If the document is a Technical Note or Best Practice, then the value of “wd” is used prior to approval of the document. Once approved, this suffix is dropped.
Filenames use all lower case characters exclusively.
Pre-existing UDDI.org specifications (schema, WSDL) files name will remain unchanged.
3.2 Documentation Format
On a case by case basis, in consultation with the Editors, the Chairs will decide the format of the document PDF, DOC and/or HTML. The preferred format will be HTML.
3.3 Posting to UDDI Spec TC Page
TC Chairs will manage postings and updates of content.
3.4 Document Collaboration
Until such time that OASIS provides the TC document source control facilities, on an as required basis, the TC will utilize the uddi-spec YahooGroup for document collaboration. The suggested rudimentary file management process:
a) use of files description fields to note file state, Two states are suggested:
· "in" – no one is currently editing the file, and it's up to date
· "out - <name> - date"- file is currently signed out to <name> for update
b) only obtain a file out for update when it is "in"
c) when checking-in the file:
· move the existing copy of the file to the “Obsolete” folder, deleting any copies in excess of 2 which are there
· insure you notify TC members by checking the “Notify” box when you replace a file
d) Refrain from modifying a file for which you are not the author or editor. Rather, post suggestions/marked up copies/etc. to authors via the UDDI TC list. Bring to the attention of the TC Chairs authors/editors who are not being responsive.
|
Rev |
Date |
By Whom |
What |
|
1 |
20021010 |
Tom Bellwood, Luc Clément |
Initial version |
|
2 |
20021212 |
Luc Clément |
Incorporates decisions related to AR 001, 002 and 003 |
|
3 |
20030324 |
Luc Clément |
Update to links to reflect changes to URLs necessary for the Kavi implementation at OASIS |