Subject: v3 format rollout schedule

From: Heather Flanagan <[email-masked]>
Date: Mon, 26 Aug 2019 10:45:01 -0700

Hola a todos!

The v3 format transition is almost here! As mentioned during the plenary at IETF 105, though, there was always a possibility that the tools and end-to-end processes might not be ready by end of August. There are two showstopper bugs from the RFC Editor perspective, involving <xref> section links and comments cutting off non-commented text. The developer has released fixes in 2.24.0 and 2.25.0 which are in the process of being tested. The timing has me pushing back the RPC target date to September 16.  

Once the v3 transition happens, the community should expect several months of debugging and increased workload for both the RPC and the authors. Additional files will need to be checked, new artwork will need to be managed, and tooling bugs will need to be chased down and fixed. 

As a reminder, here are a few important links to help keep people up to date on the transition and how to use the new features of xml2rfc:

https://www.rfc-editor.org/rse/wiki/doku.php/design:format-implementation <https://www.rfc-editor.org/rse/wiki/doku.php/design:format-implementation>
https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html <https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html>

Thanks much, and let me know if you have any questions.
Heather Flanagan, RSE

---

From: Julian Reschke <[email-masked]>
Date: Tue, 27 Aug 2019 08:08:21 +0200

On 26.08.2019 19:45, Heather Flanagan wrote:
> Hola a todos!
>
> The v3 format transition is almost here! As mentioned during the plenary
> at IETF 105, though, there was always a possibility that the tools and
> end-to-end processes might not be ready by end of August. There are two
> showstopper bugs from the RFC Editor perspective, involving <xref>
> section links and comments cutting off non-commented text. The developer
> has released fixes in 2.24.0 and 2.25.0 which are in the process of
> being tested. The timing has me pushing back the RPC target date to
> September 16.
>
> Once the v3 transition happens, the community should expect several
> months of debugging and increased workload for both the RPC and the
> authors. Additional files will need to be checked, new artwork will need
> to be managed, and tooling bugs will need to be chased down and fixed.
>
> As a reminder, here are a few important links to help keep people up to
> date on the transition and how to use the new features of xml2rfc:
>
> https://www.rfc-editor.org/rse/wiki/doku.php/design:format-implementation
> https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html
>

It's great that there is progress.

That said, I'm still concerned that there is no single spec describing
the vocabulary that's being introduced, and there are tons of issues
raised on github and on the xml2rfc* mailing lists that have not been
resolved.

Best regards, Julian

---

From: Richard Barnes <[email-masked]>
Date: Wed, 28 Aug 2019 10:57:17 -0400

Julian - Could you please expand on these concerns for those of us who have
not been involved?  The "no single spec" one seems especially concerning.

---

From: Kent Watsen <[email-masked]>
Date: Wed, 28 Aug 2019 15:44:02 +0000

> Julian - Could you please expand on these concerns for those of us who have not been involved?  The "no single spec" one seems especially concerning.

Having spent some time looking at V3, I can attest that RFC 7991 does not reflect what `xml2rfc` implements.  Many of the deviations are captured by draft-levkowetz-xml2rfc-v3-implementation-notes-09.  An rfc7991bis is needed to reflect reality.

Kent

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 28 Aug 2019 12:34:38 -0400

I believe that the stated policy was that once there was a rolled out 
v3, the RFC would indeed be superseded (obsoleted) by a new one.

Short of insisting on sticking with things which experience proved were 
mistakes, I do not see what other choice there was / is.

Yours,
Joel

On 8/28/2019 11:44 AM, Kent Watsen wrote:
> 
>> Julian - Could you please expand on these concerns for those of us who 
>> have not been involved?  The "no single spec" one seems especially 
>> concerning.
> 
> 
> Having spent some time looking at V3, I can attest that RFC 7991 does 
> not reflect what `xml2rfc` implements.  Many of the deviations are 
> captured by draft-levkowetz-xml2rfc-v3-implementation-notes-09.  An 
> rfc7991bis is needed to reflect reality.
> 
> Kent
>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Aug 2019 18:22:40 +0200

On 28.08.2019 16:57, Richard Barnes wrote:
> ...

There's more context over here:
<https://mailarchive.ietf.org/arch/msg/xml2rfc-dev/4klkISejMULrdA8K8JVvgmdmwiA>.

It's nice that Heather explained her view over there. However I remain
unconvinced that what she summarized there will lead to a V3 definition
that is suitable to be *the* canonical format, and also work well for
implementers other than the xml2rfc author (that is, alternate
formatters, tools *producing* V3, and tools doing other interesting
things with V3 files).

IMHO we need to restart the work on 7991bis (and related docs, such as
the HTML format and the preptool definition), and do that in a
transparent way. I understand that this document does not require IETF
consensus, but that also doesn't mean it's ok not to properly follow up
on the implementer feedback that was sent since the publication of RFC799x.

Best regards, Julian

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 28 Aug 2019 12:59:26 -0400

+1 to what Joel said.

But with the proviso that the RFC and ID formats are not something the
RFCInterest group should decide by themselves. It might be appropriate to
do a -bis on RFC7991 to reflect the state of the tools after the initial
rollout. But the format has to evolve to meet the needs of the IETF as a
whole, not just the interest group.

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 28 Aug 2019 13:17:13 -0400

Julian, are you really asking that we stop the rollout of v3, have an 
extended working group process to design a new v3, and then develop 
tools, etc. for that?   I think the community would be very unhappy at 
the delay.

And just to be clear, I am pretty sure there was input from lots of 
constituencies at every stage of the development of the v3 we have in 
front of us.

Yours,
Joel

On 8/28/2019 12:22 PM, Julian Reschke wrote:
> on the implementer feedback that was sent since the publication of 
> RFC799x..
> 
> Best regards, Julian
> 
>

---

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 28 Aug 2019 10:31:18 -0700

On 28 Aug 2019, at 10:17, Joel M. Halpern wrote:

> tools, etc. for that?

I read Julian's message quite differently. I believe he is asking that 
every change from what the community agreed to in RFC 7991 be again 
discussed in the community. That is in contrast to what is happening 
currently, which is that one developer is making many changes to RFC 
7991 and those changes will be implemented in the canonical format 
without community discussion.

> I think the community would be very unhappy at the delay.

The community would indeed be very unhappy about a delay due to starting 
over. No one has asked the community if a delay to vet just the changes 
to the community's agreement on RFC 7991 would be OK.

> constituencies at every stage of the development of the v3 we have in 

You are incorrect. There was input from some of us early during the 
current stage of development of v3 (that is, changes to RFC 7991), but 
that input was rejected forcefully by the developer. We were told that 
getting the tool done in a timely manner was more important than vetting 
the changes, and that the developer's changes would be accepted without 
community review.

My personal response to that was to stop reviewing the changes because 
it felt like a waste of my time. Because of this, I am removing my name 
as editor of 7991-bis because the changes in it will not reflect a 
community consensus.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Aug 2019 19:34:31 +0200

> tools, etc. for that?   I think the community would be very unhappy at

Rolling out what we have now is fine. Just label it "beta". Pretending
it's done when there's a huge backlog of issues however is IMHO not ok.

I'm not asking for a working group. What I'm asking for is that we take
revising RFC 7991 (which does *not* describe what's being rolled out)
seriously, and that the feedback that has come in over almost three
years is actually being taken into account.

> constituencies at every stage of the development of the v3 we have in

<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues>: 44 open
issues.

<https://github.com/rfc-format/draft-iab-rfcv3-preptool-bis>: 12 open
issues.

<https://github.com/rfc-format/draft-iab-html-rfc-bis>: 14 open issues

There's also unprocessed feedback it xml2rfc's trac instance, plus many
mails on xml2rfc/xml2rfc-dev that haven't been replied to.

I understand that people want to finish this. It's taken too long,
agreed. But what happens now looks like rushing things out, instead of
doing it properly, and the way it was promised back when RFC799x were
published.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Aug 2019 19:44:01 +0200

> v3, the RFC would indeed be superseded (obsoleted) by a new one.

The stated policy was that the specs would be revised based on
implementation feedback *while* the implementation happens. What seems
to be happening now is that what was implemented will be rubberstamped
as "v3" after the fact.

Don't get me wrong: I actually support many changes that were made. I
also support most of the additions - and I have implemented them. It's
just that some of the changes IMHO go into the wrong direction, and I'd
like to see an actual discussion about these things happening.

> mistakes, I do not see what other choice there was / is.

Fixing mistakes is fine. But the scope of changes goes way beyond that.
On the other hand, other issues remain unaddressed. Example: how to
format acknowledgements - leading to authors putting prose into artwork
to get the ASCII output they want (see recent xml2rfc mailing list
threads with sample V3 documents).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Aug 2019 19:53:54 +0200

On 28.08.2019 18:59, Phillip Hallam-Baker wrote:
> RFCInterest group should decide by themselves. It might be appropriate

It was called "design commitee", AFAIR. And in hindsight I agree that
the process didn't work that well. I'm not convinced that something else
would have worked much better though. Designing vocabularies is tricky
and invites bike-shedding. (Remember the Atom WG?).

> to do a -bis on RFC7991 to reflect the state of the tools after the
> initial rollout. But the format has to evolve to meet the needs of the
> IETF as a whole, not just the interest group.
> ...

Absolutely. But then it also shouldn't evolve just based on the
preferences of the implementer, right? That's why I was asking for a
transparent process to revise 7991bis, after all.

Best regards, Julian

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 28 Aug 2019 13:57:32 -0400

Labeling what we roll out as beta, and more importantly noting that 
there are further changes that are needed, makes sense to me.  With an 
important caveat.   That was not how I read your note, which is why I 
was asking.

There is an issue in that we will either need to preserve the beta code 
permanently, or be able to convert any beta RFCs with formatting 
preserved into final RFCs.  If all the changes are extensions, that 
clearly works.  However, if they are not, I wonder how we publish RFCs 
with requisite permanence.

Yours,
Joel

---

From: Julian Reschke <[email-masked]>
Date: Wed, 28 Aug 2019 20:00:18 +0200

> discussed in the community. That is in contrast to what is happening

Well. The community did not agree on RFC 7991 - the IAB did.

Even the design group consensus was weak on certain points. Some of the
changes in the implementation are actually in these areas, and with some
of them I'm actually very happy.

> without community discussion.

Yes, that's a problem.

> to the community's agreement on RFC 7991 would be OK.

Exactly.

Also, the only reason why we are facing a potential delay right now is
because (a) it took ages to start the development after the specs were
done (in Summer 2016), and (b) we did not took care of the spec
revisions in time.

Best regards, Julian

---

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 28 Aug 2019 13:51:30 -0700

On 28 Aug 2019, at 10:57, Joel M. Halpern wrote:

> there are further changes that are needed, makes sense to me.

Me too.

> With an important caveat.   That was not how I read your note, which 
> is why I was asking.
>
> There is an issue in that we will either need to preserve the beta 
> code permanently, or be able to convert any beta RFCs with formatting 
> preserved into final RFCs.

Yes.

> If all the changes are extensions, that clearly works.  However, if 
> they are not, I wonder how we publish RFCs with requisite permanence.

There will always be that question because there will at some point 
likely be a v4.

The question is whether the community wants to review all the proposed 
changes to RFC 7991 before the RFC Editor starts publishing things in 
XML format. As Julian points out, there are dozens of open issues that 
have been filed on RFC 7991 and on the changes being made by the 
contractor. Should we deal with those now, or should we basically agree 
to having an incompatible v4 format in about a year? My preference would 
be "do the review now".

--Paul Hoffman