Subject: [Tools-discuss] Re: I-D ACTION:draft-ietf-tools-draft-submission-01.txt (fwd)

From: Alex Rousskov <[email-masked]>
Date: Thu, 23 Sep 2004 06:50:27 -0600 (MDT)

-- Forwarding to tools-discuss at Brian's request.
    Lots of good comments here.

---------- Forwarded message ----------
Date: Thu, 23 Sep 2004 11:18:41 +0200
From: Brian E Carpenter <[email-masked]>
To: [email-masked]
Subject: Re: I-D ACTION:draft-ietf-tools-draft-submission-01.txt

Alex,

I've lost track of where this is to be discussed, so please forward
these comments as appropriate.

Generally, this is good stuff.

> 6.  Overall toolset operation
...
>    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 selects one of the following three actions
>       (a) auto-post draft "as is" now; (b) correct extracted meta-data
>       and submit draft to Secretariat for manual posting later; or (c)
>       cancel submission.  Automated posting option may not be available
>       for drafts that failed validation.

I found (b) hard to understand as a summary until I read the later
description. So I suggest

(b) make manual corrections and submit draft...

Another point: if the submitter does *nothing*, i.e. none of a), b) or c)
the whole thing should time out and be garbage collected.

> 7.  Upload page
> 
>    To upload the draft, the submitter goes to a well-known URL on IETF
>    web site.  There, two exclusive options are available.  First, the
>    draft text can be uploaded using HTML file input form.  This form
>    provides input fields to upload plain text format of the draft and
>    all other formats allowed by IETF draft publication rules.  At the
>    time of writing, these formats are:  XML (RFC 2629), Postscript, and
>    PDF.

I see nothing in http://www.ietf.org/ietf/1id-guidelines.txt to suggest
that PDF is acceptable for I-Ds. It is an option for RFCs I believe, but
it would be an addition to current documented procedures to support
PDF format I-Ds.

I believe you should be simpler here. Insist on an ASCII document as the
one that is preprocessed (whether it is raw .txt or XML). If the submitter
also submits a Postcript and/or PDF, just treat that as an opaque file.
Come back to this issue in Version 2 of the tool.

> 8.3  Extraction
> 
>    Each stored draft format is interpreted to extract draft meta-data.
>    [[XXX10: mention somewhere that initially, some formats will not be
>    fully or at all interpreted, but eventually either the format needs
>    to be interpreted or it should not be accepted for automated posting
>    --Alex]].

See previous comment. If you follow the existing id-guidelines by
*requiring* a .txt or XML base document, I think it is OK to take the
additional formats on trust and upload them as opaque files.

However, I'd like to repeat a suggestion I made a year or two ago.
Make it compulsory that even a pure .txt draft should include a short
preamble in XML2RFC format with all the required metadata. It should
be easy to provide a template for this (or even offer the template
on the upload page).

> 
>    The following meta-data is extracted by the draft interpreter.
> 
>    identifier: Also known as draft "filename".  For example,
>       draft-ietf-tools-draft-submission-13.
> 
>    revision: A non-negative integer also known as draft version.  For
>       example, 13 in draft-ietf-tools-draft-submission-13.
> 
>    name: Common part of all draft identifiers for all revisions of the
>       same draft.  For example, draft-ietf-tools-draft-submission in
>       draft-ietf-tools-draft-submission-13.
> 
>    WG ID: IETF working group identifier.  WG value is empty for
>       individual drafts not meant to be related to 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".  [[XXX42: Is it possible that an
>       individual draft without a WG name component in its name is
>       adopted as a WG draft without changing draft name? See also "WG
>       flag" concerns.  --Alex]]

Yes, this is a choice that a WG can make. But see my next comment...
> 
>    WG flag: True for IETF WG drafts and false for all other drafts.  For
>       example, "true" for "draft-ietf-tools-draft-submission-13".
>       [[XXX40: Currently, there is no reliable way to extract WG ID from
>       the draft, because some WGs (e.g., OSPF) tell the Secretariat that
>       a draft-surname-wg-foo-05 draft is actually a WG document.  I
>       would encourage a policy change to require this-is-a-WG-draft
>       information to be embedded in WG drafts.  --Pekka Savola]][[XXX41:
>       A simple policy would be the best, but, in theory, the toolset can
>       also consult some IETF database to see if a
>       draft-surname-wg-foo-05 draft is actually a WG draft.  --Alex]]

This can be resolved robustly as follows. The tool should *only*
recognize as WG drafts those that follow the draf-ietf-wgname-*
convention - don't add complexity. But if a WG chooses to "cheat" by
not renaming a draft, that is their right and their problem - it's
simply out of band as far as the tool is concerned. No policy
change is needed, and the WG will suffer from any resulting confusion.
Their problem, not ours.

> 
> 
>    title: A human-friendly draft title.  For example, the title of this
>       draft is "Requirements for IETF Draft Submission Toolset"
> 
>    authors: A list of all draft authors.  For each author, their first
>       name, last name, and e-mail are extracted.
> 
>    abstract: Draft abstract text.
> 
>    submission date: Draft submission date.
> 
>    expiration date: Draft expiration date.

One possible addition is

      mailing list: email address of list for discussion of this draft

Enforcing that *would* be a minor policy change, but a very useful
one IMHO (e.g. see this draft itself).

> 
>    [[XXX11: number of pages and size would depend on format version;
>    they probably should not (do not need to) be specified manually; do
>    we need to extract them at this stage? --Alex]].

The byte count can obviously be generated automatically later.

Here's a heresy: let's just drop pagination and page counts from I-Ds.
They are basically useless anyway, and the RFC Editor always
repaginates at the end of the process.

> 8.4.1  Absolute requirements
...
> 
>    3.  A Working Group draft must be approved by the corresponding
>        working group.

    by a Chair or Secretary of the corresponding working group.

...
>    6.  An IETF IPR statement must appear in the draft text.  [[XXX16:
>        add the applicable parts of RFC 2026, 3667 and 3668 - this is
>        mostly a matter of checking the presence of boilerplate text.
>        --Henrik]]

Do you mean that the I-D boilerplate must be present, or that the entire
IPR and Copyright text must be present, or both?

> 
>    [[XXX17: Today, -00 WG drafts are approved by the Chair after
>    submission, not prior to submission.  See "Comparison with current
>    procedures" section.  --Alex]]

Not true. WG Chairs may pre-approve drafts, and are indeed requested to do
so at http://www.ietf.org/meetings/cutoff_dates_61.html

> 8.4.2  Desireable features
...
>    [[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]]

I'd say that to prevent both DOS attacks and human error, anything
less than 48 hours should be kicked over for manual handling.

> 9.1  External meta-data
> 
>    TBD: Input fields for meta-data that must be supplied by submitter
>    and cannot be extracted from the draft:
> 
>       Which author is the submitter? [[XXX30: with the exception for
>       Secretariat manual submission? No.  Secretariat submits on behalf
>       of one of the authors.  --Alex]][[XXX31: are there any situations
>       when a draft is submitted by somebody other than author and not on
>       explicit authors behalf? What happens to IPR "by submitting this
>       draft I ..." statement then? --Alex]];

It isn't "I" any more - the current version of the bolierplate
commits all the authors.

>       Does the author request this submission to be published (i.e.,
>       forwarded to IESG or RFC Editor for review and publication as an
>       RFC or BCP)? The author would tick a corresponding checkbox on the
>       web interface to set the "publication requested" flag.  [[XXX32:
>       clarify that for-publication submissions may be subjected to more
>       mandatory checks than other drafts.  --Alex]][[XXX45: Currently,
>       it is the WG Chair that submits "for publication" drafts to the
>       AD.  This meta-data flag would let authors do it.  The intent is
>       to enable more strict checks before the submission, to improve the
>       quality of the drafts submitted for IESG review.  Bad idea?
>       --Alex]

Yes, bad idea. I believe that for WG drafts, the WG Chairs or Secretary
need to be the gatekeeper - document authors cannot assert that there is
WG consensus. But for individual submissions, we need to decide whether
it is the author or the lucky AD who does it. The tool probably needs to
be designed flexibly in this area.

>       List of drafts obsoleted by this draft.  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]].

IMHO this is too complex and would be a luxury in Version 1. Maybe for
Version 2...

> 10.  Post Now action
...
>    [[XXX26: should responding to e-mail be
>    also supported (as an alternative to going back to the web page to
>    cut-and-paste the token)? --Alex]]

Yes please, this can be very handy when intermittently connected.

> 14.  Bypassing the toolset
> 
>    A buggy toolset or unusual circumstances may force a submitter to
>    submit draft to Secretariat for manual processing.  This can be done
>    by choosing the "manual posting" route supported by the toolset or,
>    as a last resort, by e-mailing the draft directly to Secretariat.  In
>    either case, an informal "cover letter" has to accompany the draft.
>    The letter should explain why the automated interface cannot be used.

This mechanism will also apply during the phase-in period for
the tool, when only a subset of people are using it.

> 
>    When processing manual submissions, the Secretariat may be able to
>    use the toolset.  A Manual Validation page similar to the default
>    Validation page provides authenticated Secretariat staff with
>    editable meta-data fields and a "force posting" action.  The forced
>    posting action accepts meta-data fields "as is" and proceeds with the
>    regular posting algorithm [[XXX22: Should we document the details
>    even though this page is for internal Secretariat use?
>    --Alex]]

Yes. There is no reason for it to be secret.

>    [[XXX23: Should forced posting script obtain authors consent
>    or do we want to be able to bypass that as well? --Alex]]

I think we need the flexibility - situations can arise where an
author is on sabbatical or medical leave or otherwise unavailable
for a long period.

> 15.  E-mail interface
...
>    off-line mode: A submitter can do all the manual work required to
>       submit a draft while being disconnected from the network.  E-mail
>       client actually submits the draft when connectivity is regained.
>       [[XXX39: This advantage would be significantly reduced if we
>       require submitter e-mail verification for each draft submission.
>       Such verification would mean that valid drafts cannot be posted
>       automatically when connectivity is regained -- sending an e-mail
>       just starts the process.  --Alex]]

Nevertheless, I think the verification emails are required - otherwise
we are very exposed to bogons.

> Appendix A.  Comparison with current procedures
> 
>    TBD: This section summarizes major differences between draft
>    submission approach currently in use by IETF and the proposed
>    toolset, including violations of the current IETF rules.
> 
>    o  Approval for version -00 of a WG draft.  [[XXX28: Clearly point
>       out that we propose to require that working group chairs post an
>       approval *before* a -00 is submitted - there is no option to
>       submit a -00 draft and have it sit and wait for the Chair's
>       approval.  This is a change from current procedure, and may need
>       approval from outside the tools team.  --Henrik]][[XXX29: I am not
>       sure the current procedure is required by IETF rules.  The order
>       does not seem to be codified anywhere so changing current practice
>       should not be that difficult.  The key is to convince IETF that
>       the change is worth it long-term.  --Alex]]

Non-issue. The WG decision is by definition before the draft is posted,
and as noted above it is existing practice for WG Chairs to pre-approve
postings.

> 
>    o  The toolset allows posting of draft renderings additional to plain
>       text as well as XML draft sources.  Currently, the Secretariat
>       only accepts plain text submissions of drafts.

Well, the I-D guidelines already allow PS, you are only adding PDF.
However, as suggested above, I would treat these as opaque files
(or simply not handle them in Version 1).

Regards
     Brian

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

---

From: Carl Malamud <[email-masked]>
Date: Fri, 24 Sep 2004 15:34:28 -0700 (PDT)

> be easy to provide a template for this (or even offer the template

This would be *really* helpful for a whole bunch of applications.

Carl

---

From: Alex Rousskov <[email-masked]>
Date: Fri, 24 Sep 2004 16:44:45 -0600 (MDT)

On Fri, 24 Sep 2004, Carl Malamud wrote:

>> Make it compulsory that even a pure .txt draft should include a 
>> short preamble in XML2RFC format with all the required metadata. It 
>> should be easy to provide a template for this (or even offer the 
>> template on the upload page).
>

I agree that having meta-data would be very helpful, but disagree that 
the right way to do it is to add XML blobs to plain text drafts. It 
would be an ugly hack, and we can do much better, without much extra 
effort, and while being more user-friendly.

The first part of the solution I prefer (currently documented in the 
ID Submission draft) is to create a meta-data file/record/whatever at 
the time of the submission. That can be done by interpreting XML 
sources (if available), text sources, and/or user input.

The second part is to make that metadata available as a part of the 
draft rendering/access interface. I hope we will document that soon. 
It could be as simple as accessing an 
"/archive/draftname/metadata.xml" URL.

Alex.

---

From: Carl Malamud <[email-masked]>
Date: Fri, 24 Sep 2004 15:47:58 -0700 (PDT)

> sources (if available), text sources, and/or user input.

That would be fine with me.  If you can make that conform to a
<reference> tag, that would be even better, making it compatible
with existing citation databases.

Carl

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 25 Sep 2004 09:37:50 +0200

Alex Rousskov wrote:
>>> be easy to provide a template for this (or even offer the template on 
>>> the upload page).
>>
>>
> The first part of the solution I prefer (currently documented in the ID 
> Submission draft) is to create a meta-data file/record/whatever at the 
> time of the submission. That can be done by interpreting XML sources (if 
> available), text sources, and/or user input.
> 
> draft rendering/access interface. I hope we will document that soon. It 
> could be as simple as accessing an "/archive/draftname/metadata.xml" URL.

I agree that this is the right way to go, both with respect to
extracting information from the draft and generating meta-information,
and having this available in xml format (maybe both conforming to 
<reference /> format and some superset of that), and finally to make
the metadata generally available.

I note though that although we can document the latter at will, we will
require buy-in from leadership and secretariat.  I'm starting the 
process of getting that by putting together a proposed priority
list, and making some contacts.

	Henrik