Subject: Re: [Tools-team] draft-ietf-tools-notification-03.txt

From: Alex Rousskov <[email-masked]>
Date: Tue, 8 Feb 2005 22:36:52 -0700 (MST)

On Mon, 31 Jan 2005, stanislav shalunov wrote:

> http://www.internet2.edu/~shalunov/ietf-tools/draft-ietf-tools-notification-03.txt

Stas,

 	Here is my late high-level feedback on your Notification 
draft.  First of all, I am excited that you made a lot of progress! If 
done right and at full scale, IETF notifications would be a useful and 
cool feature.

 	1) My first and most important comment is about notifications 
scope. I believe the scope currently defined in the draft is too 
narrow and must be enlarged.  The draft currently defines 
notifications for single-document events.  That's fine, must at 
virtually the same cost we can and, IMO, should support notifications 
for other events, including events related to multiple documents 
(e.g., "all documents authored by Stas" or "all drafts on the BOF 
agenda") and events unrelated to specific documents (e.g., "WG 
consensus call", or "IESG membership change", or "IETF meeting 
schedule change").

 	While we should certainly start with events related to drafts, 
WG charters, and meetings, I am sure that (given the right toolset 
design), IETF will add many more useful events without any significant 
changes to the notification interface you are defining or to the tools 
that will implement the interface.

 	In summary, I believe that the focus on a "document" should be 
removed from the Notification draft and replaced with a more broad 
definition of an IETF-related "event".

 	2) Event tags should be hidden from human users whenever 
possible.  It might be fine to initially associate draft events with 
the draft name, but that implementation detail should not be a part of 
the overall design and should be invisible to the human user (except 
for low-level debugging purposes). The interface should allow users to 
specify events using whatever IDs are natural in a given _context_: "I 
want to follow THIS draft", "I am interested in any document authored 
by THIS author", "Notify me when THIS wg milestone is reached", "Tell 
me when any NEW WG is formed", etc. Sometimes, the context will be 
defined by some draft filename, of course, but that does not mean 
event tag will [always] be a draft name or mask.

 	Your current draft already has a few paragraphs illustrating 
why hard coding the filename:tag relationship causes trouble: a) A 
file name might change while subscriber interest in the draft is 
unlikely to change with the name change; and a) Some events are 
difficult or impossible to define in terms of draft names. The user is 
usually not interested in the draft name (which is just a low-level 
IETF ID), but in the draft contents and meaningful metadata. (The sad 
fact that some IETF draft IDs carry some meaning should not be 
misinterpreted as a design worth following).

 	3) When individual draft is accepted as a WG draft, the 
subscribers interested in the draft are most likely to remain 
interested. Do not drop them unless their event selection specifically 
excluded WG drafts. "Individual" or "WG" is just a state or flag 
assigned to each draft. The change in this flag value should not cause 
general subscriptions to be terminated, just like the change in IESG 
states should not cause such termination.

 	Again, this is an illustration why tag:filename tie does not 
reflect notification problem space well (see above).

 	4) Document states should not be assumed to be sequential by 
design. IESG states might be an exception, but we should make it very 
clear that a single draft may be in several different states at the 
same time. The implementation should support that so that new 
states/flags can be easily added by editing some XML config files, 
without any code modification. Perhaps "state" is not the best term 
here.

 	Related editorial comment: do we have to describe IESG states 
in this draft? Can we cite some document or web page instead? The set 
of IESG draft states and their specific definitions do not seem to be 
important for our purposes...

 	5) In the event anatomy, move "Document name" and "Document 
state" to a lower, event type-specific part. Only documents will have 
those. Other events may have other type-specific parts.

 	6) In the document event anatomy, "document state" should not 
be reported unless the event notifies of the state change. We are not 
reporting other unchanged document metadata, why is "state" special?

 	7) In the event anatomy, would "gist" be a better name for the 
"title" field?  I also disagree with the given "title" examples. 
Titles/gists should not contain information from other event field 
(e.g., draft filename). Software that renders notification will 
combine fields as it finds appropriate. Thus, "title" examples should 
be "new draft", "new version", "draft state change", etc.

 	8) I would consider joining "event abstract" and "event URL" 
into something like "event comment" or "event description". For most 
events, this field will contain a very short text pointing to some web 
page describing common events. For some special, custom events, the 
field will contain human-written text giving all the details about the 
event. I think this scheme would accommodate virtually all uses 
without being difficult to support or comprehend.

 	9) How about replacing "MISC" with "OTHER" or "UNCATEGORIZED"?

 	10) In "Kinds of Notifications", if "new document" (i.e., 
document birth) is special, should not document death be special as 
well.

 	11) Existence notification: See above regarding merging tags 
and event semantics. We should not try to encode the entire event 
semantics into the tag. The event metadata is type-specific and will 
contain necessary details. It should be possible to get notifications 
for, say, "new documents by Stas". See above for more examples. This 
draft cannot define all such event types. The system must be flexible 
enough to accept new event types with ease (and that something we must 
design for and require).

 	12) I did not understand Section 7.4. RSS notifications I get 
now are just like good email notifications -- they are very short 
gists with web pointers/links to more details elsewhere. You are 
saying that web notifications are like RSS notifications but then you 
talk about "all events displayed in order", and that confuses me. To 
me, displaying more than one event is a function of some event history 
browsing mechanism, not notification mechanism.

 	13) Section "Errors, Amendments, etc.": We should not try 
erasing any events. Is does not work in a distributed environment; the 
erase event will always be late under some conditions. Sending an 
"error" event, followed by the correct event is the only thing that 
works, IMO. And it is much simpler to implement too!

Please note that all of the above are thoughts/suggestions, even if 
they read like affirmative statements! While I have strong preferences 
on a few issues such as scope and tags, I do believe we need to debate 
them and my position may change.

Thank you,

Alex.

_______________________________________________
Tools-team mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/tools-team

---

From: stanislav shalunov <[email-masked]>
Date: 09 Feb 2005 15:10:29 -0500

Alex Rousskov <[email-masked]> writes:

> draft.

Thank you very much for doing this.  It is very helpful.

> scope.

[Discussed on the call.  Will wait for your description of changes.]

> possible.

[As clarified during the call, event tags are, in the terminology of
the draft, document or existential tags.]

Yes.  Users aren't to be expected to keep typing these things in.

Let me describe, briefly and in general terms, how I imagined the user
interface to work.

Working group web pages and similar pages might contain a few new
links:

* ``Notify me about future new drafts by this working group via
  email''

* ``See event history for this draft''

* ``Read the event history for this draft as an RSS feed''

* ``Notify me about future events related to this draft via email''

Users might follow these links.  In the case of email subscriptions,
they'd need to enter their email address, unless previously
authenticated.  When a user subscribes for the first time, he enters
his email address, receives a short ``confirm this'' message, and
confirms by responding or visiting a web page.  Along with this, if
the confirmation is done via the web, the user might be offered a
chance to create a username and password so that he won't need to
confirm subscriptions again.  He might also be offered a chance to
simply be remembered by the system (via a cookie).

A user who is subscribed to some existential notifications (the
typical case would be ``all drafts'' or ``all drafts by this WG and
that one'') would get email messages that would include the abstract
of the internet-draft.  The message would also contain two URLs
(mailto: and http:) that would help accomplish the same thing, viz.,
subscribe to future events related to this draft.

The business with tags would help application developers who would be
given a stable interface into the system.  The user interface would
not need to be as rigidly defined.  Third parties or the IETF in the
future might use the well-defined mechanisms to do whatever they like
with events: build search engines, complex notification systems, etc.
The most trivial example of using extensions of this kind would be if
I created a link on my personal page that let you subscribe to my
future drafts (the link might look like
http://notify.ietf.org/sub?t=draft-shalunov-*, and I would be expected
to produce it either by cutting and pasting after using a form
somewhere or, less typically, by constructing the link myself;
regardless of the way I got the link, I'd know it's stable).

> It might be fine to initially associate draft events with
> the overall design

I don't believe the spec is complete unless it gives a stable
interface for playing with events.

> states should not cause such termination.

``Drop'' is a word that seems to imply email delivery.  With RSS,
would you want the feed URL remain the same?  It'd be great if the
IETF had stable tags to refer to ``the same document'' that survived
republishing, but it doesn't.  If there were these more stable tags,
we could use them.

> design.

They are not.  (Indeed the order, as specified, is impossible to
follow for a draft.)

> IESG states might be an exception, but we should make it very clear
> that a single draft may be in several different states at the same
> time.

I don't understand.

> The implementation should support that so that new states/flags can
> be easily added by editing some XML config files, without any code
> modification. Perhaps "state" is not the best term here.

Are you talking about some kind of flags here?  What flags?  Where
would they come from?

> in this draft?

I'd prefer not to, but I see no better choice.  The text is borrowed
from the I-D tracker (with permission).

> Can we cite some document or web page instead?

I'd prefer to.  The tracker seems to have been developed without a
published requirements document.  Looks like we have to retroactively
publish the most important part of the design for the tracker (the
states).

Note that the events engine continues to track documents after they
exit the IESG queue and end up with the RFC editor.

> those. Other events may have other type-specific parts.

Depends on 1.

> reporting other unchanged document metadata, why is "state" special?

Originally, my tuple didn't contain state.  Henrik pointed out that
having it there would be beneficial.  It'd be easier to keep it as a
tuple at this point.  If you prefer, one could add old state to the
tuple, so that it'd be trivial to check if the state changed.  (For
now, you can look at the event type to learn that.)

> "title" field?

Perhaps.

> I also disagree with the given "title" examples. Titles/gists should
> not contain information from other event field (e.g., draft
> filename). Software that renders notification will combine fields as
> it finds appropriate. Thus, "title" examples should be "new draft",
> "new version", "draft state change", etc.

Can you give some examples where one would benefit from having that?
Non-replication looks like a good idea to me, but would we need to
needlessly repeat, for every dissemination mechanism, how to form the
email subject/RSS headline/WWW title?

> without being difficult to support or comprehend.

I wanted to separate out the URL, as it is structured (and it's well
known what to do about it in software).  The abstract, on the other
hand, is not structured, and the only thing software can do with it is
keep copying it essentially verbatim until it's shown to a user.

>  	9) How about replacing "MISC" with "OTHER" or "UNCATEGORIZED"?

Done (``UNCATEGORIZED'').

> document birth) is special, should not document death be special as

I don't think so, because birth events are the natural time to decide
whether you're interested in the future life of the event.  One could,
of course, write an add-on obituary service based on the Atom feed,
but it's not a very natural service.

> and event semantics.

Depends on 1.

> browsing mechanism, not notification mechanism.

The RSS notifications you're talking about (``items'') are parts of a
feed.  The feed contains a whole bunch of them.  WWW dissemination
mechanism would present a complete RSS feed in reverse chronological
order; this is similar to what most web-based RSS readers and blogging
software would do, if I understand correctly.

> works, IMO. And it is much simpler to implement too!

Why would it be bad to erase events locally?  Should I change
``Subsequently, the erroneous event, together with the new event of
type ERROR, is removed from RSS, Atom, and WWW notification feeds'' so
that it includes ``MAY''?

If you build an event database out of an email feed, you aren't bound
by the rules set by the draft.  (Besides, mirroring Atom feeds might
be a better way than building the event database, but that's
tangential.)

Thanks again for your input,

-- 
Stanislav Shalunov		http://www.internet2.edu/~shalunov/

I never let school stand in the way of my education.  -- Mark Twain