wrt: IETF filename convention (and a bit about subcommittees)

[=JeffH <Jeff.Hodges@neustar.biz>]

This is the most recent (heh) revision of the brief doc RLBob & I cooked up 
when the SSTC was originally established..

OASIS Security Services Technical Committee Document Guidelines
http://www.oasis-open.org/committees/security/docs/draft-sstc-doc-guidelines-02.txt
(also attached below)

We (the SSTC) have actually for the most part, where actual SSTC doc filenames 
are concerned, followed it.

Sections 5, 5.1, and 5.2 are the most directly relevant to the point(s) I 
brought up on the ORMS concall.

One should disregard the "subcommittee"-based notions expressed in 
draft-sstc-doc-guidelines -- we (SSTC) ultimately found that having 
subcommittees do their work on distro lists separate from the main SSTC list 
(security-services@) was not useful, and also having formal subcommittees 
themselves was not terribly useful because the overhead. We relatively soon 
migrated to using informal focused subteams for addressing particular problems. 
It was interesting and validating of these notions (to me anyway) that we went 
thru much the same evolution within the Liberty Alliance Technical Expert Group.

In terms of draft documents and the IETF process itself, section 7 "Naming and 
submitting" of http://www.ietf.org/ietf/1id-guidelines.txt is also relevant and 
worth perusing -- as is section 2 "General Considerations".

=JeffH



OASIS - Security Services TC
RL "Bob" Morgan
Jeff Hodges
16-Feb-2001

OASIS Security Services Technical Committee Document Guidelines
<draft-sstc-doc-guidelines-02.txt>

This document is an OASIS-Draft and is in conformance with relevant
OASIS SSTC document standards (i.e., itself).

comments to:  security-services@lists.oasis-open.org


Abstract

This document specifies document-handling practices for the OASIS
Security Services Technical Committee (SSTC) and its subcommittees.

1.  Introduction

This document recommends standards for name, format, and availability
of documents that are being worked on in subcommittees of the OASIS
SSTC (and, potentially, other areas of OASIS). It is loosely based on
standards for documents in IETF working groups, as described in [2],
[3], and [4].  The intended  benefits are: clarity of document status,
uniform availability,  consistent document-handling among different
working groups, and  facilitation of group web site maintenance; all
while being as  consistent as possible with the otherwise free-form
OASIS process.

The standards expressed here are for draft documents and Committee
Specifications produced specifically by the SSTC and its subcommittees.

See Article 2, Section 2 of [5] for the standards used for  producing
OASIS Specifications and other OASIS-wide documents.

2.  Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [1].

"TC" is used throughout this document to mean "Technical Committee",
which specifically means the Security Services TC at this stage in this
document's life cycle.

3. Intellectual property rights policies

The OASIS General Policy for intellectual property rights (IPR) is
expressed in [6] as:

   In all matters of intellectual property rights and procedures,
   the intention is to benefit the public at large, while respecting
   the legitimate rights of others.

The reader must refer to [6] for detailed description of IPR rules,
conventions, and required document noticies. TC and TC subcommittee
draft documents SHOULD contain applicable IPR notices from [6], and
approved TC final documents MUST contain applicable notices from [6].

4.  Document evolution model

4.1  Overview

This recommendation provides a simple model of how documents move from
initial ideas to final, approved SSTC work products.

Documents begin as drafts, proceed through a number of revisions, and
finally, upon approval by the committee, are published as Committee
Specifications. Upon approval by the OASIS membership as a whole, they
are published as OASIS Specifications. Article 2, Section 2 of [5] 
documents the latter step  of this overall process. This document is 
concerned with the steps up to and including a document becoming an
SSTC  Committee Specification.

Document filenames reflect the overall process.  Draft documents are
denoted by their filenames beginning with "draft-". Draft documents are
not permanent, and may be superseded or removed at any time.  Detailed
document guidelines including filename conventions are  presented in
section 5, below.

Completed TC draft documents that are intended to be submitted for 
OASIS membership approval are to be published as Committee 
Specifications as specified in section 4.X, below.

4.2  The TC Editor Function

The collection of TC documents, including but not limited to TC drafts,
individual submissions, Committee Specifications, is managed by the  TC
Editor Function (the "TC Editor" aka "security-editors"). The TC Editor 
is a role that is occupied at any particular time by one or more TC 
members (at this time decided upon at the pleasure of the TC Chair). 

The TC Editor is addressed by electronic mail using the address..

  security-editors@lists.oasis-open.org

The TC Editor has responsibility for assigning document filenames 
(according to the guidelines in this document), ascertaining whether
said documents meet the guidelines as specified in this document,
remanding the documents to the authors if deemed necessary (e.g. if the
document(s) don't meet these guidelines), publishing said  documents on
the TC website and denoting status thereof (e.g. whether the
document(s) are a TC Draft, individual submission, or Committee
Specification). 

4.3  Individual submission and TC draft documents

A distinction is made between "individual submission" draft documents
and "TC or TC subcommittee" draft documents (hereinafter referred to
simply as "TC draft documents").  An individual submission (which may 
of course be submitted by more than one person) represents only the
opinions of its authors.  A TC draft document is intended to reflect
the (rough) consensus of the TC or applicable TC subcommittee. The
topics of TC draft documents will typically be specified in the TC or
subcommittee charter or are otherwise agreed upon by the TC, while
individual submissions may be on any topic relevant to the work.

Document filenames reflect the distinction between individual
submissions and TC or subcommittee documents.

Migration of individual submission draft documents to TC draft
documents is done via a motion or general consent of the TC or
subcommittee (see Chapter 2, Section 4 of [7]). Likewise, working group
document also  may migrate to an individual submission of the TC or
subcommittee via a motion or general consent of the TC or subcommittee.

4.4  Publishing Committee Specifications

A member of the TC or subcommittee may move to recognize a TC draft as
a Committee Specification, or the Chair may call for general consent 
(see Chapter 2, Section 4 of [7]). The TC draft MUST satisfy the
document guidelines  as specified in this document at the time such a
motion is made.  A simple majority of the full TC membership is
required in order to  recognize a TC draft as a Committee
Specification. 

Upon such recognition, the filename of TC draft remains unchanged from 
the filename (as specified in 5.2 below) at the time of recognition. 
The TC draft's status as a Committee Specification is duly noted by the
TC editor in the TC document repository and any index or content
listing thereof. 

4.5  TC Document Repository

The TC document repository is available via this URL..

  http://www.oasis-open.org/committees/security/docs/

5.  Document guidelines

These guidelines apply to all documents submitted for committee or
subcommittee consideration, and apply while draft documents are being
worked on by the applicable group.

5.1  Availability

Documents shall be available via the TC's web page on the OASIS web
site, or via at most one non-OASIS site.  Documents shall be available
via HTTP, and optionally via FTP.

Documents may be sent to committee e-mail lists, but any documents so
sent will subsequently be made available via the committee web site,
unless the author specifically informs the committee chair not to do
so.  Thus, documents sent to mailing lists should conform to these
guidelines. 

The presence of new documents and new revisions shall be announced to
the working group mailing list.

5.2  Document Filename Conventions

TC drafts MUST be named using the format:

   "draft-sstc-" + [ subcommittee mailing list acronym + "-" ]
    + short title + "-" + two-digit version + "." + doc format

   e.g. "draft-sstc-core-assertions-05.html".

The "[ subcommittee mailing list acronym + "-" ]" is NOT used for TC 
drafts that are TC-wide and/or have been approved as Committee 
Specifications (see section 4 above). 

Individual submissions MUST be named using the format:

   "draft-" + main author's last name + "-" + short title
     + "-" + two-digit version + "." + doc format

   e.g. "draft-morgan-coolidea-00.txt".

5.2.1  Subcommittee mailing list acrocyms

This is the present list of SSTC subcommittee mailing list acronyms 
for use with the file name convention for TC drafts:

   bindings
   conform
   core
   protocol
   consider
   use

5.3  Formats

PDF format is the preferred distribution document format. Document
source formats are XML encoded according to the XXX DTD for text, and
Powerpoint source for illustrations (one illustration per powerpoint
slide, one powerpoint file containing multiple slides per corresponding
XML textual source file).

5.4  Content elements

A document must include, at the beginning, the author's names, the date
of submission, the document name including version number, the name of
the working group, and an email address to which comments can be
directed.  A document must include, at the end, author contact
information for all authors, including at least an email address for
each.

A document should include, at the beginning, a short abstract, and, if
applicable, a table of contents.  Sections and subsections should be
numbered, and usually named also, for ease of reference.  A document
should include, at the end, References and Acknowledgements sections.

6.  Reference(s)

[1] Bradner, S.  "Key words for use in RFCs to Indicate Requirement
    Levels", RFC 2119, March 1997. Available at: 
      http://www.ietf.org/rfc/rfc2119.txt

[2] Bradner, S.  "IETF Working Group Guidelines and Procedures", BCP
    25, RFC 2418, September 1998. Available at: 
      http://www.ietf.org/rfc/rfc2418.txt

[3] "Guidelines to Authors of Internet-Drafts", IETF.
    Available at: 
      http://www.ietf.org/ietf/1id-guidelines.txt

[4] Bradner, S.  "The Internet Standards Process -- Revision 3", BCP
    9, RFC2026, October 1996. Available at: 
      http://www.ietf.org/rfc/rfc2026.txt

[5] Organization for the Advancement of Structured Information 
    Standards, "AMENDED AND RESTATED BYLAWS OCTOBER 13, 2000". 
    Available at: 
      http://www.oasis-open.org/who/bylaws.shtml

[6] "OASIS Policy on Intellectual Property Rights (OASIS.IPR)"
    Available at:
      http://www.oasis-open.org/who/intellectualproperty.shtml

[7] Robert III, Henry M., Evans, William J., Honemann, Daniel H., 
    Balch, Thomas J. "Roberts Rules of Order Newly Revised", 10th Ed.,
    Perseus Publishing, New York, October 2000, ISBN 0738203076.

[8] Morgan, RL "Bob"  "Internet2 Middleware Initiative Working
    Group Document Guidelines", internet2-mi-doc-guidelines-00.txt,
    25-Jan-2001. Available at:
    http://middleware.internet2.edu/internet2-mi-doc-guidelines-00.txt

7.  Acknowledgements

This document is largely based on internet2-mi-doc-guidelines-00.txt by
RL "Bob" Morgan, [8]. The authors gratefully acknowledge the
suggestions  of Neal McBurnett, and information about OASIS practices
supplied by Karl  Best.

8.  Author information

RL "Bob" Morgan
Computing & Communications
University of Washington
rlmorgan@washington.edu

Jeff Hodges
Oblix Inc.
jhodges@oblix.com


9.  OASIS Intellectual Property Notice

OASIS takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to pertain
to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or
might not be available; neither does it represent that it has made any
effort to identify any such rights. Information on OASIS's procedures
with respect to rights in OASIS specifications can be found at the
OASIS website. Copies of claims of rights made available for
publication and any assurances of licenses to be made available, or the
result of an attempt made to obtain a general license or permission for
the use of such proprietary rights by implementors or users of this
specification, can be obtained from the OASIS Executive Director.

OASIS invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary rights
which may cover technology that may be required to implement this
specification. Please address the information to the OASIS Executive
Director.

10.  Copyright Notice

Copyright (C) The Organization for the Advancement of Structured
Information Standards [OASIS] (date). All Rights Reserved. 

This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it or
assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing the
copyright notice or references to OASIS, except as needed for the
purpose of developing OASIS specifications, in which case the
procedures for copyrights defined in the OASIS Intellectual Property
Rights document must be followed, or as required to translate it into
languages other than English. 

The limited permissions granted above are perpetual and will not be
revoked by OASIS or its successors or assigns. 

This document and the information contained herein is provided on an
"AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMTED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.