Subject: [Tools-team] id submission tool draft -03 comments

From: Henrik Levkowetz <[email-masked]>
Date: Sun, 10 Oct 2004 21:37:16 +0200

Hi Alex, all,

    Below are my comments on the -03 version of the draft.  The comments
inlined in the draft text are available here:

http://ietf.levkowetz.com/tools/rfcmarkup/rfcmarkup.cgi?url=../../reviews/draft-ietf-tools-draft-submission-04.a.txt&comments=HENRIK

and a side-by-side diff showing both the comments and suggested
grammar fixes is available here:

http://ietf.levkowetz.com/reviews/draft-ietf-tools-draft-submission-04.a-from-3.diff.html

	Henrik

-----------
Comments:

Section 4., para. 2:
    Posted draft: A draft accepted into public IETF draft repository and,
       hence, publicly available on IETF web site.  Posting (a.k.a.,
       publication) of a draft does not imply any IETF or IESG review and
       endorsement.
 HENRIK: I'd rather avoid the mention of publication here - submitting a
 	draft for publication pretty much means submitting it for
 	publication as an RFC, the action a chair does when the draft is
 	ready for IESG review.

Section 6., para. 5:
    Check action: Stores the draft in the toolset staging area, extracts
       draft meta-data, validates the submission (Section 8).  Produces
       the Check page.
 HENRIK: "Upload page" also describes storing the draft in the staging
 	area.  Should not also be stored by the check action, I think.

Section 6., para. 6:
    Check page: Displays draft interpretation and validation results
       (Section 9).  Draft rendering preview may also be given on this
       page.  After reviewing draft interpretation and validation
       results, the submitter has four basic choices (a) auto-post draft
       "as is" now; (b) make manual corrections and submit the draft to
       Secretariat for manual posting later; (c) cancel submission; or
       (d) do nothing.  The automated posting option may not be available for
       drafts that failed validation.
 HENRIK: Draft rendering is a new concept, and may not be clear to the
 	reader.  Exactly what is ment by draft rendering here and later
 	in the text needs to be clarified, I think - I'm not sure for
 	myself what is ment at all places where this occurs in the text.
 	(Possibly use a different word...)

Section 7., para. 2:
    The Upload page exposes the "post-if-valid" knob of the Check action
    (Section 8) (R80).  Hint: a corresponding "post if valid" checkbox
    next to the "upload" or "validate" button may suffice.
 HENRIK: Do we need/want the extra path this gives?  Maybe we should just
 	have the basic sequence of pages, without this shortcut.

Section 8.1, para. 0:
 8.1  Preprocessing
 HENRIK: I wonder if 'preprocessing' is the best word here.  In addition
 	to collision with other (e.g. C language) usage of the word, there
 	is a collision with the use of the word in the first sentence of
 	para. 2 below.  Change to "Processing of XML sources" or "processing",
 	depending on context?

Section 8.1, para. 2:
    Both original and preprocessed XML sources may be posted later.  The
    original source with include PIs may be useful to the RFC Editor and
    diffs.  The preprocessed version without PIs becomes the default
 HENRIK: I don't understand the '... and diffs.' part above
    public XML source of the posted draft (R10).  If any of the include
    PIs cannot be handled, the entire action fails (R11).
 HENRIK: Maybe say "submission fails" rather than "action fails", here
 	and later?  (That's more readable language, I think...)

Section 8.3, para. 1:
    Each stored draft format is interpreted to extract draft meta-data
    (R14).  If a given format is interpreted and meta-data extraction
    fails, the format is not accepted for automated posting (R15).  In
    this case, the submitter can either delete the offending format(s)
    from the submission and auto-post OR proceed along the manual
    submission route so that the Secretariat can verify all formats.
 HENRIK: I don't understand "... and auto-post".  s/ and auto-post// ?

Section 8.3, para. 7:
    WG ID: IETF working group identifier.  WG value is empty for
       individual drafts not meant to be work items of a known WG and for
       non-IETF drafts.  For example, "tools" in
       "draft-ietf-tools-draft-submission-13" and "opes" in
       "draft-rousskov-opes-ocp-00" are both WG IDs.
 HENRIK: Is it wise to try to extract WG IDs from personal drafts? And is
 	it useful?

Section 8.4.1, para. 5:
    4.  Current draft state must allow new revisions to be posted (R21).
        [[XXX15: document IESG review states when new revisions are
        allowed.  Secretariat, Harald, and Pekka opinions seem to differ
        here.  Secretariat: No revisions are allowed in any state except
        for "I-D exists", "AD watching", or an explicit IESG request for
        a new revision.  Harald:  no revisions once submitted for
        publication.  Pekka: In practice, revisions are allowed in any
        state; don't try to solve a process knowledge problem (the I-D
        author should not submit new versions) using a technical means.
        Need further clarification.  If no clarification, always allow
        until approved, but issue a warning when draft is under IESG
        control.  --Alex]].
 HENRIK: My experience with practice supports Pekka's view here...

Section 8.4.1, para. 7:
    6.  An IETF IPR statement must appear in the draft text (R23).
        [[XXX16: add the applicable parts of RFC 2026, 3667 and 3668 -
        this is mostly a matter of checking the presence of boilerplate
        text.  --Henrik]][[XXX57: Do you mean that the I-D boilerplate
        must be present, or that the entire IPR and Copyright text must
        be present, or both? --Brian E.  Carpenter]]
 HENRIK: Maybe "An IETF IPR Statement and other boilerplate requred for
 	drafts according to RFC 3667 and 3668 (or successors) must appear
 	in the draft text (R23)"

Section 8.4.2, para. 3:
    [[XXX33: What to do when two versions are submitted with a
    suspiciously small gap? How small should the gap be to warrant
    warnings/actions? --Stanislav]][[XXX59: to prevent both DOS attacks
    and human error, anything less than 48 hours should be kicked over
    for manual handling.  --Brian E.  Carpenter]]
 HENRIK: Maybe specify 24 hours?

Section 9., para. 4:
    The Check page provides a preview of the draft plain text format
    rendering (R31), with a link to see how the entire draft (with all
    its formats) would be rendered if posted (R82).  Hint: the Check page
    preview should be sufficiently long to let authors detect obvious
    draft mismatch or misinterpretation errors but short enough to avoid
    dominating the page.  Displaying just the draft "prefix", including
    abstract, may be sufficient.
 HENRIK: 'prefix' is too diffuse / open to interpretation.  Specify more
 	exactly what this includes, in addiotn to the abstract. Maybe:
 	Title, Authors, Filename, Date, Abstract

Section 9.1, para. 3:
       List of drafts obsoleted by this draft (R33).  This is useful to
       make obsoleted drafts invisible.  [[XXX43: Can non -00 draft
       obsolete other drafts? Or is this reserved for -00 versions for
       some reason? Is this reserved for WG drafts only? --Alex]].
       [[XXX44: This may open a bigger can of worms than we want to deal
       with, as it allows anybody to "kill" any other draft.  The toolset
       would probably need a manual check by Secretariat and/or approvals
       from both(?) WG Chairs.  A lot of work for something relatively
       rare? --Alex]][[XXX60: This is too complex and would be a luxury
       in Version 1.  Maybe for Version 2.  --Brian E.  Carpenter]]
 HENRIK: Agreed. Skip this for now.

Section 10., para. 4:
    [[XXX2: should the posting program inform all authors that their
    draft is being posted (since the draft says they all made an IPR
    statement)? Default answer: yes.  Obtaining consent from all authors
    seems impractical.  --Alex]][[XXX26: responding to e-mail should also
    be supported (as an alternative to going back to cut-and-paste the
    URL with a token) --Alex]]
 HENRIK: I agree with both of these notes.

Section 15., para. 3:
 HENRIK: Providing we know the data - the exact requirements on this
 	page comes from the secretariat, rather than the community.

Section 16., para. 5:
    [[XXX37: If there is only one draft format, can e-mail body be used
    for submission? --Alex]]
 HENRIK: I think this is a definite advantage but not a MUST.

Section 16., para. 6:
    [[XXX38: To easily filter out spam and reduce human errors, should we
    require a special keyword in the subject or body of the submission
    e-mail? For example, we can require and check that the subject starts
    with "Please post" --Alex]]
 HENRIK: Or - subject or first N (8?) lines of the e-mail should contain
 	one of the words "post" or "submit" ?

Section 17., para. 19:
    [[XXX50: Is it appropriate for us to specify stage deadlines for the
    first two stages? Should IESG do that instead? Would be nice to have
    at least a rough number to illustrate the relative duration of stages
    though.  --Alex]]
 HENRIK: It would probably not be appropriate for us to specify the deadlines.

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

---

From: "Barbara B. Fuller" <[email-masked]>
Date: Sun, 10 Oct 2004 18:29:46 -0400

Hi Henrik:

>  HENRIK: My experience with practice supports Pekka's view here...

There is really no disagreement among the three opinions.

(a) The state "I-D exists" means simply that someone has submitted an 
I-D.  Therefore, revisions are of course allowed.

(b) The state "AD is watching" means that an AD is following the progress 
of the I-D and may wish to shepherd it if and when the author submits a 
request to publish the I-D as an RFC.  Therefore, revisions are of course 
still allowed.

(c) When the author submits a request to publish the I-D as an RFC, the 
document enters the state "Publication Requested," and the author receives 
a message that includes the following statement:

"Please note that once a request to publish an I-D as an RFC has been 
submitted, the I-D must not be revised without the explicit advance 
approval of the shepherding Area Director (AD)."

Therefore, from this point forward, revisions are only allowed when the 
shepherding AD or the IESG requests them.  Needless to say, if the authors 
continued to revise the I-D while the AD or the IESG was reviewing it, then 
the AD/IESG would be evaluating a moving target.

SOooo, Pekka is correct....revisions are allowed at any time...but certain 
rules apply.  And Harald is correct too...unsolicited revisions are not 
allowed after publication is requested.  However, they are allowed if the 
AD or the IESG requests a revised I-D.  Please note that one of the I-D 
Tracker sub-states is "Revised I-D Needed," the definition of which is: "An 
updated I-D is needed to address the issues that have been raised."

I hope that this information clears up some of the confusion about this issue.

Regards,

Barbara
------------------------------------------------
Barbara B. Fuller
Acting Executive Director
Internet Engineering Task Force

Natick, Massachusetts Office:

Phone: +1-508-650-4020
Fax:     +1-508-650-4639

Reston, Virginia Office:

Phone: +1-703-620-9053
Fax:     +1-703-620-9071

---

From: "Alex Rousskov" <[email-masked]>
Date: Mon, 11 Oct 2004 16:49:39 -0600

On Sun, 10 Oct 2004 21:37:16 +0200, Henrik Levkowetz <[email-masked]> wrote:

> Hi Alex, all,
>
>     Below are my comments on the -03 version of the draft.

Henrik,

	Thanks a lot for the comments! I have already applied a few and will try
to finish tonight. I will post version 04 then.

Alex.

---

From: Alex Rousskov <[email-masked]>
Date: Wed, 13 Oct 2004 00:12:04 -0600 (MDT)

Henrik,

 	Thanks again. I have made the corresponding edits and 
submitted the 04 version of the draft for posting. I hope I did not 
overlook any comments.

 	There are still a few XXXs I need to resolve, but we are 
getting close. I also need to put each Rnnn requirement into a 
corresponding implementation stage and polish the text.

 	I took the liberty to "skip" a few editorial changes you sent, 
for now (e.g., do English speakers really put "the" in front of a 
possessive like "submitter's hat"?).

 	As for non-editorial changes, I did not skip any. Please let 
me know if the changes I made do not reflect your wishes. Here are 
comments related to a couple of issues you raised.

> 	area.  Should not also be stored by the check action, I think.

The "Upload page" section does not describe storing. Am I missing 
something?

> 	para. 2 below.  Change to "Processing of XML sources" or "processing",

I think that preprocessing (in a programming language sense or even in 
a general sense) is exactly what is going here as far as resolving XML 
PIs is concerned. I agree that plain text or HTML generation is not 
preprocessing. I have split the subsection into two subsections 
accordingly and polished "preprocessing" occurrences elsewhere.

> HENRIK: Is it wise to try to extract WG IDs from personal drafts? And is

I think it can be useful (otherwise including WG acronym in a draft 
name would be useless as well!) and should not hurt if tools and 
humans treat this information with care (as they should today). 
However, I do not have a strong preference here. Please let me know if 
you do.

Thank you,

Alex.

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 13 Oct 2004 15:18:52 +0200

Hi Alex,

> submitted the 04 version of the draft for posting. I hope I did not 

Ok, good.

> possessive like "submitter's hat"?).

Withouth looking up the specific sentence, I think I remember this,
and it could go either way, but I chose to put in 'the' because it
made the sentence more definite.  I think all grammar changes I made
were quite deliberate :-)

> The "Upload page" section does not describe storing. Am I missing 

It says "Interface to copy draft from submitters computer into
the toolset staging area" - which I read as storing it in the
staging area ...

> accordingly and polished "preprocessing" occurrences elsewhere.

Ok.

> However, I do not have a strong preference here. Please let me know if 

I don't have a strong preference.  It just seemed a bit chancy, with
added complexity for not so large gain.  For drafts named draft-ietf-
[something] the next part is positively the working group, while for
individual drafts there is not such a strong convention, so you'd have
to mach each part of the name against a list of existing WGs - ...
added complexity ,:-)

	Henrik