Network Working Group S. Shalunov Internet-Draft Internet2 Expires: July 30, 2005 January 26, 2005 Requirements for Document Notification Service draft-ietf-tools-notification-01 Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on July 30, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract The output of the IETF consists of documents. The IETF process is largely related to changing the status of documents. Active participation in the work of the IETF often consists of writing or editing documents or providing input to the process of changing the documents' status. Passive participation often consists of reading documents and observing the changes of their status. Shalunov Expires July 30, 2005 [Page 1] Internet-Draft Document Notification Service January 2005 This document describes the requirements for an automated service that helps the IETF participants to learn about the existence and follow the changes of status of any particular document. Table of Contents 1. Requirements Notation . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Document Definition and Document Tags . . . . . . . . . . . . 5 4. Events in the Life of a Document . . . . . . . . . . . . . . . 7 4.1 Event Anatomy . . . . . . . . . . . . . . . . . . . . . . 7 4.1.1 Document tag . . . . . . . . . . . . . . . . . . . . . 7 4.1.2 Document name . . . . . . . . . . . . . . . . . . . . 7 4.1.3 Date and time . . . . . . . . . . . . . . . . . . . . 7 4.1.4 Event title . . . . . . . . . . . . . . . . . . . . . 7 4.1.5 Event abstract . . . . . . . . . . . . . . . . . . . . 8 4.1.6 Event URL . . . . . . . . . . . . . . . . . . . . . . 8 4.1.7 Event type . . . . . . . . . . . . . . . . . . . . . . 8 4.2 Types of Events . . . . . . . . . . . . . . . . . . . . . 8 5. Existence Notification . . . . . . . . . . . . . . . . . . . . 10 6. Status Notification . . . . . . . . . . . . . . . . . . . . . 12 7. Notification Dissemination Mechanisms . . . . . . . . . . . . 13 7.1 Email Notification Dissemination . . . . . . . . . . . . . 13 7.2 RSS Notification Dissemination . . . . . . . . . . . . . . 13 7.3 WWW Notification Dissemination . . . . . . . . . . . . . . 13 8. Errors, Amendmends, and Event Retention . . . . . . . . . . . 14 9. Phases of Tool Development . . . . . . . . . . . . . . . . . . 15 10. Security Considerations . . . . . . . . . . . . . . . . . . 16 11. Internationalization Considerations . . . . . . . . . . . . 17 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . 18 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 18 Intellectual Property and Copyright Statements . . . . . . . . 19 Shalunov Expires July 30, 2005 [Page 2] Internet-Draft Document Notification Service January 2005 1. Requirements Notation 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 [RFC2119]. Shalunov Expires July 30, 2005 [Page 3] Internet-Draft Document Notification Service January 2005 2. Introduction At present, notifications related to IETF documents are sent to up to three different mailing lists: the IETF announcements list (ietf-announce@ietf.org), the general IETF list (ietf@ietf.org), and to the mailing list of the working group, if there is one. Different types of messages go to different mailing lists. Someone who is interested in all notifications about a particular document would need to subscribe to the three mailing lists and monitor subject lines for both the document's file name and its title. Such person would receive not only notifications about the document status and its changes, but also various messages related to the discussion of the document. For some people, this would be a convenient way to follow a document. Others might find that they might be getting too many messages of no interest and risk missing messages of interest. An automated notification service that allows one to follow only the changes of official status of a document, without necessarily following the changes of all the IETF documents, or the day-to-day activity of the working group responsible for the document, thus, appears beneficial. This document describes requirements for such a notification service. When this service is deployed, it becomes immediately useful on its own right by supplementing the existing notification mechanisms. As experience is gained with the tool and it is accepted by the IETF community, the tool might be used to help automate existing notification mechanisms. Shalunov Expires July 30, 2005 [Page 4] Internet-Draft Document Notification Service January 2005 3. Document Definition and Document Tags This document discusses the status of other documents. These other documents include: 1. IETF internet-drafts; 2. RFC documents; 3. STD documents; 4. BCP documents; 5. FYI documents. In the future, this list might be expanded, should the IETF or the RFC editor choose to start new document series. Throughout the life of a document, continuity between versions is preserved by being able to refer to the document using the same tag. This tag will be called a document tag. This document assumes that any documents to which the automated notification service needs to be applicable possess these document tags. Document tags are strings of characters. For an internet-draft, the document tag is the file name without any extension or a version number (dot in front of an extension and dash in front of a version number are omitted, as well). For example, this document's tag is "draft-ietf-tools-notification" (without quotes, naturally). Documents' tags never change; so, should this document ever be published as an RFC, the document tag will remain the same; should this document be published, e.g., as a BCP and later reclassified as a historic FYI, the document tag would still be the same. Note that the RFC editor currently already keeps the internet-draft file name (without the extension or the initial "draft-" string, but with the version number) from which an RFC originated; it can be found in the file rfc-index.xml distributed by the RFC editor as the element. This is an extremely useful practice that should continue. It is clearly preferable that document tags be unique. However, the current IETF policies do not appear to disallow the reuse of the file name of an expired internet-draft for a new internet-draft. Changing this unfortunate policy is outside of scope of this document and of the IETF Tools team in general. Should such tag collision occur, the notification service MAY treat the new internet-draft as a continuation of the old one (for the purposes of notifications). The author believes that such collisions need to be prevented from happening by the internet-drafts administrator (or the internet-drafts submission tool, or whatever or whoever accepts IETF internet-draft in the future). Note that the tool currently used by the internet-drafts administrator will (advantageously) not allow such reuse. Shalunov Expires July 30, 2005 [Page 5] Internet-Draft Document Notification Service January 2005 Occasionally, personal drafts are republished as working group drafts. In this case, since heritage can be partial and ambiguous, the new working group draft MUST be treated by the notification service as a completely new document. Shalunov Expires July 30, 2005 [Page 6] Internet-Draft Document Notification Service January 2005 4. Events in the Life of a Document The notification service deals with events in the life of documents. 4.1 Event Anatomy An event is a tuple with the following members: 1. Document tag; 2. Document (new) name; 3. Date and time; 4. Event title; 5. Event abstract; 6. Event URL; 7. Event type. The individual members of the tuple are discussed below. 4.1.1 Document tag Document tags are explained in Section 3. 4.1.2 Document name For an internet-draft, the name of the document, is the file name without the extension (or the dot preceding it): e.g., "draft-ietf-tools-notification-00". For other kinds of documents, the name is the document series name followed by the document number (without a separating space): e.g., "RFC1234". Note that an event is often (but not always) associated with a change in the name of the document. The new name is always used. 4.1.3 Date and time Date and time are specified together in the following format: four digits specifying year; dash; two digits specifying month; dash; two digits specifying day of the month; the capital letter "T"; two digits specifying the hour of the day in 24-hour format; colon; two digits specifying minute; two digits specifying second; and, finally, the capital letter "Z". This timestamp always contains exactly 20 characters and refers to universal coordinated time (UTC). The timestamp describes the time when the event occured. Example of a valid timestamp: "2005-01-24T04:15:12Z". This timestamp format MUST be used; no other formats or variations or this format are allowed. 4.1.4 Event title The title of the event is a human-readable synopsis of the event. It should be suitable for use as an email message subject or a web page title. Examples of reasonable titles: Shalunov Expires July 30, 2005 [Page 7] Internet-Draft Document Notification Service January 2005 o "New internet-draft: draft-ietf-tools-notification-00.txt"; o "New version of internet-draft: draft-ietf-tools-notification-17.txt"; o "Draft forwarded to IESG: draft-ietf-tools-notification-17.txt"; o "IESG comments on draft-ietf-tools-notification-17.txt"; o "draft-ietf-tools-notification-17.txt published as RFC8888"; o "RFC9999 obsoletes RFC8888". (Naturally, the quotes do not appear in the actual titles.) Examples of bad titles: o "Event happened"; o "Draft advanced"; o "RFC publication"; o "Frobnication Considered Harmful on the Internet". Note that, in particular, the title of the document itself makes a poor event title. 4.1.5 Event abstract The event abstract elucidates the event and should be suitable for being used as a body of an email message or of a short web page that would be followed by the event URL, where more information about the event could be obtained. The abstract generally should not exceed a page of text or so. The abstract SHOULD contain as much relevant information as practical within the space limits. 4.1.6 Event URL The event URL points to a more complete description of the event. For example, currently, the URL might point to a relevant URL within the I-D tracker [cite: FIXME]. Should no event description be published as a document with a URL, the event URL MAY be the URL of the document itself. 4.1.7 Event type The event type, as a member of the event tuple, is an opaque identifier (a string of characters). Particular event types are discussed in Section 4.2. 4.2 Types of Events The following event types are valid: NEW New document is created. VERSION New version of an internet-draft is available. WGLC Working group last call issued on the document. Shalunov Expires July 30, 2005 [Page 8] Internet-Draft Document Notification Service January 2005 IESG-SUBMIT The document has been submitted to the IESG for approval. IESG-CHANGE The document had some status change while being considered by the IESG (e.g., IESG review, comments, request for a change). IETFLC General IETF last call issued on the document. RFC-SUBMIT The document has been submitted to the RFC editor for publication. RFC-CHANGE The document, not yet published by the RFC editor, had some status change (e.g., authors' 48 hours). RFC-PUBLISHED The document is published as an RFC (and, perhaps, simultaneously as an STD, BCP, or FYI). STD-REMOVED The document is no longer an STD. BCP-REMOVED The document is no longer a BCP. STD-CHANGED The status of an STD changed while it remained an STD (e.g., advanced). RFC-CHANGED The document remains an RFC, but some change in its status happened (other than those specifically mentioned above, e.g., a FYI reclassified as historic). ERROR An event was previously entered into the system erroneously and this is now discovered and corrected (e.g., it was erroneously detected that a document was forwarded to the RFC editor when, in fact, the document still remains in the IESG queue). MISC An event related to the document, but not mentioned above. The most specific event type MUST always be used. In particular, the MISC event type MUST NOT be used when a more appropriate event type exists. Shalunov Expires July 30, 2005 [Page 9] Internet-Draft Document Notification Service January 2005 5. Existence Notification Notifications are generally of two kinds: notifications of existence of documents, which help the service's user learn about new internet-drafts (discussed in this section), and notifications about the change of status of specific documents, which help learn about events in the life of a particular document a user is interested in (discussed in Section 6). Existence notifications deal with events of type NEW. Status change notifications deal with events of all other types. Just as document tags define particular documents, some way is needed to define classes of documents about which a user would like to learn. For simplicity's sake, these tags are based on file names. An existential tag is a sequence of characters, of which three have a special meaning: asterisk ("*"), question mark ("?"), and backslash ("\"). A document tag can match an existential tag. Given an existential tag and a document tag, the match is decided as follows: 1. In the existential tag, all sequences of two consecutive backslash characters (as the string representing the tag is read from left to right) are replaced with a pseudo-character not otherwise in the alphabet. 2. In the existential tag, all asterisks not preceded with a backslash are replaced with a pseudo-character not otherwise in the alphabet. 3. In the existential tag, all question marks not preceded with a backslash are replaced with a pseudo-character not otherwise in the alphabet. 4. In the existential tag, all pseudo-characters are replaced with a backslash. 5. If, in the existential tag, each pseudo-character can be replaced with a (possibly empty) string of characters and each pseudo-character can be replaced with a single character so that the existential tag coincides with the document tag, the document tag matches the existential tag. Otherwise, it does not match. An event is said to match an existential tag if the event's type is NEW and the event's document tag matches the existential tag. The user of the notification service obtains a set of events of interest by deciding on existential tags of interest and then submitting these tags in a way discussed in Section 7 to the notification service. For example, a user interested in internet-drafts of the IETF Tools team might subscribe to the existential tag "draft-ietf-tools-*". To Shalunov Expires July 30, 2005 [Page 10] Internet-Draft Document Notification Service January 2005 watch emergence of personal drafts by John Doe, one might use "draft-doe-*". Shalunov Expires July 30, 2005 [Page 11] Internet-Draft Document Notification Service January 2005 6. Status Notification A user can submit a document tag to the notification service in a way discussed in Section 7 to obtain a set of all events whose document tag equals to the one submitted. Shalunov Expires July 30, 2005 [Page 12] Internet-Draft Document Notification Service January 2005 7. Notification Dissemination Mechanisms Different users would find different notification mechanisms more convenient. The following mechanisms are defined: 1. Email, 2. RSS, and 3. WWW. 7.1 Email Notification Dissemination Users can subscribe to existence notifications with given existential tags and to status notifications with given document tags. Each event that requires notification would then generate a single, separate, email message. Email messages generated by the notification service MUST conform to [RFC2919]. 7.2 RSS Notification Dissemination FIXME: I might use some help here. I really only use RSS with rss2email. 7.3 WWW Notification Dissemination The WWW mechanism is similar to the RSS mechanism (Section 7.2), except for the format. In the case of WWW notifications, an HTML representation of the RSS feed is used. Shalunov Expires July 30, 2005 [Page 13] Internet-Draft Document Notification Service January 2005 8. Errors, Amendmends, and Event Retention Should it be detected that a notification for an event was generated in error (the event did not, in fact, occur), a new event of type ERROR is created that explains in its title and abstract the nature of the error. Email notifications are generated for this new event. Subsequently, the erroneous event, together with the new event of type ERROR, is removed from RSS and WWW notification feeds. Should it be detected that a notification for an event was generated with an error, the event, in its corrected form, should reenter the notification service. When email notifications are generated, it MUST be noted in the title (using the word "CORRECTED" in uppercase, followed by a colon, at the start of the title) and in the abstract that the event was corrected. The correct type of event MUST be transmitted in this case (rather than "ERROR"). Subsequently, the erroneous event is corrected in the RSS and WWW notification feeds. Note that these provisions only covers true clerical errors and not errors of judgment or others. The notification service retains information about all events in perpetuity. While not visible through the RSS and WWW notification interfaces, any history of revisions of erroneous events MUST be retained in perpetuity as well. Shalunov Expires July 30, 2005 [Page 14] Internet-Draft Document Notification Service January 2005 9. Phases of Tool Development FIXME: This needs to be discussed further. Shalunov Expires July 30, 2005 [Page 15] Internet-Draft Document Notification Service January 2005 10. Security Considerations To prevent unwanted email notifications, the notification service should follow the usual good mailing list practice: only subscribe after receiving a confirmation (via email or WWW) of a subscription message sent to the email address being subscribed; an exception is formed, of course, when an authenticated WWW user is subscribing an his own address to new notifications. To prevent sensitive information disclosure, the notification service SHOULD strive to run with the privileges of an unauthenticated network user. (To minimize polling, the service might receive privileged hints of the form "there is new data for draft such-and-such in the I-D tracker" or similar, but the actual data put into the notifications should come, as much as possible, from an already public source.) In cases where the notification service would, by design, be disclosing information not otherwise public, careful auditing would need to be conducted: just as it is conducted with the tools that currently make the needed information public. In general, with email notification, those with access to the mailbox of the recipient are to be able to unsubscribe from future notifications. However, IETF mailing lists (such as working group mailing lists) are an important exception to this. Subscribers to IETF mailing lists MUST NOT be able to unsubscribe the mailing lists from document notifications to which the list administrator has subscribed them (users are, of course, always free to unsubscribe from the IETF mailing list itself, but they are not to decide whether the mailing list will receive notifications about, e.g., a working group draft). FIXME: The exact way in which this is best accomplished needs to be discussed further. Shalunov Expires July 30, 2005 [Page 16] Internet-Draft Document Notification Service January 2005 11. Internationalization Considerations The IETF generally conducts its business in English. However, should notification of events in other languages become necessary in the future (after, perhaps, a policy change), the notification service MUST be able to use UTF-8 character set from the start. Since, for characters in US-ASCII, UTF-8 coincides with US-ASCII, the burden of using UTF-8 on the implementor is negligible (and consists of placing "UTF-8" in any appropriate character set fields, where required). Some email clients and many WWW clients display messages and pages in UTF-8 differently from messages in US-ASCII, or not at all. For this unfortunate reason, the notification service MUST use the US-ASCII character set specification when the message happens to actually be in US-ASCII, reserving UTF-8 for the occasions when characters outside of US-ASCII are actually present. Shalunov Expires July 30, 2005 [Page 17] Internet-Draft Document Notification Service January 2005 12. IANA Considerations This document requires no action from the IANA. 13. References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2919] Chandhok, R. and G. Wenger, "List-Id: A Structured Field and Namespace for the Identification of Mailing Lists", RFC 2919, March 2001. Author's Address Stanislav Shalunov Internet2 1000 Oakbrook Drive, Suite 300 Ann Arbor, MI 48104 US Phone: +1-734-913-4260 Email: shalunov@internet2.edu URI: http://www.internet2.edu/~shalunov/ Shalunov Expires July 30, 2005 [Page 18] Internet-Draft Document Notification Service January 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights 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; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat 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 implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 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. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Shalunov Expires July 30, 2005 [Page 19]