ietf
[Top] [All Lists]

Re: Community Input Sought on SOWs for RFC Production Center and RFC Publisher

2013-08-16 15:30:55

Hi Sandy,

I'm not sure how or if it plays into the SoW but your diagram
shows errata handling in the publisher part.

Many people find the current errata process not that great, but
we've collectively not gotten around to figuring out something
better.

I think the possible consequence is that it might be good to
have some flexibility in terms of how errata are processed in
future, e.g. if we all do get around to figuring out something
better it might be good for that not to be precluded by this
SOW being overly prescriptive in that respect. (I don't know
that the SOW is prescriptive about this btw, I did read it a
few days ago but didn't consider this aspect and am about to
head out for the evening... and going out wins:-)

As I said, I'm not sure if that might result in some change
here, but be good if the folks thinking about this SOW keep that
in mind.

Ta,
S.

On 08/16/2013 09:16 PM, Sandy Ginoza wrote:
Greetings,

Since the publication of RFC 5620, the RFC Editor has been working to 
implement the RPC and Publisher split.  Based on our attempts to create two 
separable entities per RFC 5620 and later RFC 6635, our understanding of the 
motivations for splitting the RPC and Publisher into distinct functions, and 
our discussions with the RSE, the RSE has created a figure 
<http://www.rfc-editor.org/rse/wiki/lib/exe/detail.php?id=rfcpublisher&media=rfc-publisher-split-c.jpg>
 to describe where the split resides in practice.  We believe the figure 
accurately reflects the most practical split in terms of work allocation and 
portability.  

The split described in the figure eliminates the need for the Publisher to 
have staff with detailed RFC-specific knowledge by placing the majority of 
staff-related responsibilities with the RPC. Our understanding is that it is 
important for the SoWs to be aligned with the split described in the figure, 
so many of our comments below are an attempt to align these documents.  We 
provide our comments below for consideration. 

Thank you,
Sandy Ginoza 
(for the RPC and Publisher)


Notes: 
------

"Current" refers to text as provided in the Proposed SoWs: 
  http://iaoc.ietf.org/documents/RPC-Proposed-SoW-2013-final.pdf
  http://iaoc.ietf.org/documents/PUB-Proposed-SoW-2013-final_000.pdf

"Figure" refers to the figure available at 
  
http://www.rfc-editor.org/rse/wiki/lib/exe/detail.php?id=rfcpublisher&media=rfc-publisher-split-c.jpg


RFC Production Center
---------------------

1) In the following, we suggest changing "reference IETF documents (RFCs and 
Internet Drafts)" to "referenced documents (RFCs and Internet Drafts)" 
because not all RFCs/I-Ds are IETF-stream documents.

Current:
1.2.  Validation of references

Ensure that references within specifications are available and that 
referenced IETF documents (RFCs and Internet Drafts) are latest versions 
available.  Also, match citations and references for consistency.  In the 
IETF standards stream, specific rules on the suitability and availability of 
references apply, as documented in RFC 2026 and successors, as interpreted by 
the IESG.  Editing of documents may be delayed waiting for normative 
references to become available.


2) In the following, we suggest that "ASN.1 (and particularly MIBs and 
MIB-related details)" be updated to reflect "MIBs".  Although MIB modules are 
written using a subset of ASN.1, the RPC does not check all ASN.1, we only 
check MIBs.  This change will reflect what is done in practice.  If the 
intent is to actually require the RPC to check all ASN.1, please let us know 
and we will discuss checking tools with the RSE and IAD.

Current:
1.3.  Validation of formal languages

The RPC should validate the syntax of sections of documents containing formal 
languages.  In particular ASN.1 (and particularly MIBs and MIB-related 
details), YANG, ABNF, and XML should be verified using one or more tools as 
approved by the RSE.      


3) Publication takes place in the "Electronic Signing & Announcements" box 
within the figure.  The following text does not seem to align with the figure:

Current:
2.     Documents forwarded to RFC Publisher

2.1.  The RPC will edit the documents from all streams consistent with the 
RFC Style Manual, the RFC Series, and the intent of the Authors.  Documents 
so edited will be placed in the ready-to-publish state and forwarded to the 
RFC Publisher.

In the figure, the publication-related actions occur on the RPC side because 
the RPC is responsible for posting RFCs in the public archive, sending out 
the RFC announcements, updating the various indexes, and digitally signing 
the RFCs.  This makes it possible for the RPC to respond to requests for 
legal verification of RFCs.  Therefore, we suggest the following update: 

2. Documents forwarded to RFC Publisher

2.1. The RPC will edit the documents from all streams consistent with the RFC 
Style Manual, the RFC Series, and the intent of the Authors.  Documents so 
edited will be published on the RFC Editor website. 

Alternately, Section 2.1 could be removed, as the documents will not be 
forwarded to the "Publisher" for publication and because how docs will be 
edited is discussed in Section 1.1.1.  


For consistency with the above update, we suggest that item 2.2 be updated as 
follows:

Current:
2.2. Additionally, the RPC will forward records of all interaction and edits 
relative to the document, including dialogue with the document authors and 
stream representatives, to the RFC Publisher for archiving.

Suggested:
2.2. The RPC will post all relevant documents, including the related RFC 
files, records of all interaction and edits relative to the document, 
dialogue with the document authors and stream representatives, on the RFC 
Publisher server for archiving.


4) Because the Publisher is responsible for the website, 
webmaster(_at_)rfc-editor(_dot_)org is a Publisher address (and the address 
in mentioned in the Publisher SoW). We suggest that 
"webmaster(_at_)rfc-editor(_dot_)org" be removed from the text below.

Current:
6.2.  Response to general questions directed to 
rfc-editor(_at_)rfc-editor(_dot_)org and webmaster(_at_)rfc-editor(_dot_)org, 
coordinating as necessary with the RFC Publisher and RSE.


5) If item 3 (above) is accepted and Section 2.1 is updated or removed from 
the SoW, the Work Standards should be updated to refer to "publication" or 
"published" instead of "Forwarded Date" or "forwarded", for example:

Current:
A.2.1.1. A document is “received” by the RPC on the date of the receipt of a 
request to publish by the each of the respective streams (Receipt Date).

A.2.1.2. A document is “ready-to-publish” on the date it is forwarded to the 
RFC Publisher by the RPC (Forwarded Date).    

We suggest:
A.2.1.1. A document is “received” by the RPC on the date of the receipt of a 
request to publish by the each of the respective streams (Receipt Date).

A.2.1.2. A document is "published" on the date the RFC is made available on 
the RFC Editor website and the RFC announcement is sent (Publication Date).

Note that the contractual definition of the "Publication Date" is not new; it 
is currently defined in 
http://iaoc.ietf.org/documents/RFC-Publisher-Current-SOW-2012-5-24-11_000.pdf 
as 

The date of announcement is defined as the date of publication. 


If "Forwarded Date" is changed to "Publication Date", then these items should 
also be updated:

Current:
A.2.2.1. Processing times per document are from Receipt Date to Forwarded 
Date in total business days.

A.2.2.2. While the overall goal for document publication is 30 business days 
(6 weeks) from Receipt Date to Forwarded Date, the times measured in the 
defined Service Levels are times in RPC state.


6)  We suggest removing the first sentence of A.2.2.4 because it is redundant 
with earlier text and is not as clear as A.2.2.2, which can be summarized as: 

- Overall goal: time in all states (RFC-Editor-controlled states + 3rd party 
states) < 6 weeks
- Actually measured for SLA: time in RFC-Editor-controlled states

Note that we also recommend changing "RPC state" to "RFC-Editor-controlled 
states" throughout for clarity.  Alternately, we suggest that "RPC State" be 
defined as special term. 


Publisher
---------

7) In our understanding of the figure, the Publisher function provides access 
to the post-publication data, but the RPC would actually make any changes to 
post-publication data.  So, it seems inaccurate to include the Publisher is 
'responsible for [...] post-publication data'.  Therefore, we suggest the 
following update:

Current:
The RFC Publisher function is described in RFC 6635 and is responsible for 
the storage and post-publication data for RFCs, access to the website, access 
to the errata reports, search tools and indexes, the archive of documents, 
and all backups and failover processes.

Suggested:
The RFC Publisher function is described in RFC 6635 and is responsible for 
the storage of and access to the website, errata reports, search tools and 
indexes, the archive of documents, and all backups and failover processes.


8) As mentioned in item 3 above, we believe that the action of publishing 
documents, and therefore the publication processes, are the responsibility of 
the RPC.  With that in mind, we suggest the following update to the Overview:

Current:
The Publisher will accept, store and publish documents from the RFC 
Production Center and
other material as determined by the RSE.  The RSE may authorize other 
entities to submit
documents directly for publication, but those documents are published on the 
authority of the
RSE.  Changes to the publication process and public-facing tools will be made 
under the advice
and approval of the RSE.

Suggested:
The Publisher will accept and store documents from the RFC Production Center 
and other material as determined by the RSE.  

We suggest that the remainder of the text be removed.  While the Publisher 
houses the tools used by the various RFC Editor components, it is the various 
components that have the staff to suggest and implement changes to the 
publication process and tools.

Also, it is not clear to us what is meant by "other entities to submit 
documents directly for publication".  Does this refer to web content or 
perhaps I-Ds that are to be published without being edited?  Both of these 
cases seem to fall into the RPC SoW, as the RPC is responsible for content on 
the website, and even if an I-D is to be published without changes, it would 
need to be updated to conform with current format and boilerplate standards.  
Are there other cases in which this "directly for publication" may apply?


9) To make it clear that the RPC updates various data, and the Publisher 
simply makes it available on a server, we suggest changing these instances of 
"publish" and "post" to "make available" as follows:

Current:
RFCs are published on the Publisher’s website. This site includes one or more 
indexes with hyperlinked access to published documents as well as a 
convenient search engine.

Suggested:
RFCs are made available on the Publisher’s website. This site includes one or 
more indexes with hyperlinked access to published documents as well as a 
convenient search engine.

(Note: SM also suggested making "Publisher's website" be "RFC Editor website")


Current:
1.2.5.     post Web content as provided by the RSE, ISE, and/or the RFC 
Production Center,

We suggest deleting Section 1.2.5 from the Publisher SoW or updating it to 
read:
      1.2.5.     make available Web content as provided by the RSE, ISE, 
and/or the RFC Production Center,


Current: 
3.1.1.  Publish state information for each document in the publication 
process.

Suggested: 
3.1.1.  State information for each document in the publication process.


10) With the understanding that the RPC is responsible for creating and 
maintaining the web content (which presumably includes organizing the web 
content), and the Publisher for serving the content, we suggest this item be 
altered as follows. (Also: second sentence deleted because already covered in 
1.2.6.)

Current:
1.2.7.     provide continual incremental improvements, including regularly 
redesigning web page trees to respond to common usage patterns.  However, 
stable identifiers must be maintained for the RFCs, archives, Errata, indices 
and other items.

Suggested:
1.2.7.  provide data about the website usage patterns so that the maintainers 
of the web content can organize it accordingly.


11) We believe the following item should be updated because an address should 
be provided to reach the Publisher (and this same address is used numerous 
times in Appendix 1 for items for which the Publisher is responsible) and 
because the RPC should not be a middleman in cases of server failure, etc. 

Current: 
1.4. Customer Support Services. Messages sent to certain conventional 
addresses as defined by the RSE, such as webmaster(_at_)rfc-editor(_dot_)org, 
shall automatically be delivered to the RFC Production Center

Suggested: 
1.4. Customer Support Services. Messages sent to certain conventional 
addresses as defined by the RSE, such as webmaster(_at_)rfc-editor(_dot_)org, 
shall be coordinated with the RPC as appropriate.


12) We question whether integration is really a publisher task.  The RPC has 
a programmer, so it seems the RPC would be responsible for the programming 
aspects and the Publisher would be responsible for ensuring the right 
access/security for integration. 

Current:
3.1.2.     Integrate Production Center state information with the IETF tools 
or such other tool sets as directed by the RSE to provide end-to-end status 
tracking of documents 

Perhaps Section 3.1.2 should be deleted, as Section 2.3.2 indicates that the 
Publisher should provide appropriate access for integration.


13) We suggest removing item 3.1.3, because it seems to be covered by 
providing state information, as described in Section 3.1.1.

Current:
3.1.3.     Provide external visibility regarding when a document is in an 
extended waiting period, the token-holder and circumstances of the wait.


14) While the Publisher may participate in discussions about the technical 
support systems required to address policy changes, we do not believe the 
Publisher needs to be involved in discussion regarding all publication policy 
changes.  Therefore, we suggest the following update:

Current:
6.1.  Participate in the discussions of the technical publication process 
with the RSE for policy changes.

Suggested:
6.1.  Participate in policy discussions about technical support of the 
publication process. 


15) It is not clear to us that the Publisher enforces RFC Series consistency, 
as the Publisher is responsible for making the files available and 
maintaining the archives.

Current: 
7.  Accountability

The Publisher is primarily responsible to the RSE as regards to RFC Series 
consistency.

Perhaps this should be updated as:
7.  Accountability

The Publisher is primarily responsible to the RSE regarding technical support 
and hosting of the RFC Series. 


15) The Work Standards are listed in "Exhibit B", but there is no "Exhibit A" 
- is some text missing, or should Exhibit B be Exhibit A?


On Aug 16, 2013, at 11:47 AM, Ray Pelletier wrote:

All;

Are there any more comments on the SOWs?

This item will be on the IAOC agenda for its call on 22 August.

Ray

On Aug 12, 2013, at 5:54 PM, IETF Administrative Director wrote:

The RFC Series Editor (RSE) is proposing changes to the Statements of Work 
(SOW) for the RFC 
Production Center (RPC) and the RFC Publisher.  The IAOC wants to receive 
community input prior to 
negotiating the proposed changes with the contractor.  Community input will 
be discussed with the RSE 
prior to negotiations and reviewed by the IAOC.

In forwarding the proposed Statements of Work the RSE said:  "The changes 
seek to make the SoWs 
more current [implementing RFC 6635] and specific, correcting the issues of 
"multiple masters" 
directing the RPC and Publisher, as well as preparing the way for a more 
significant revision to the SoWs
when the RFC Format changes are operationalized.  The SoWs have also been 
reviewed and supported 
by the RSOC [RFC Series Oversight Committee].  We consider the changes 
within the SoWs critical to the 
clear function of the RPC and Publisher, but suggest that the changes do 
not imply a significant change 
in responsibility for the RPC or Publisher."

The proposed SOWs, the current SOWs and a diff file for each can be found 
here under Community 
Review: <http://iaoc.ietf.org/rfps.html>

We appreciate the community's input and look forward to hearing from you.  

Thanks

Ray Pelletier
IAD




<Prev in Thread] Current Thread [Next in Thread>