[ A top-post followup ]
I’d like to repeat that this is just a *proposal*.
I still think it is a good idea, and that it is has value — but, like with anything, what matters is what the community wants.
I’d like to continue the discussion / pushing the idea, but I’m happy to abandon it if the consensus is that it’s a bad idea (aka, this isn’t a hill I’m willing to die on...)
W
On Wed, Jul 3, 2019 at 1:04 PM Warren Kumari <warren@xxxxxxxxxx> wrote:
Hi there all,
TL;DR: Being able to mark a specific version of an *Internet Draft* as
“stable” would often be
useful. By encoding information in the name
(stable-foo-bar-00) we can do this.
Heather and I will be holding a side meeting at IETF 105 to discuss
the idea and get feedback.
When: Tue, July 23, 3:00pm – 4:30pm
Where: C2 (21st Floor)
Details:
Back at IETF 103 (Nov 2018, Bangkok) Job presented on “Living
Documents” at the GROW session -
https://datatracker.ietf.org/meeting/103/materials/slides-103-grow-living-documents-growroutingsecurity-00
..
Ever since then I’ve had an action item to write this up, and get more
feedback on this. I’ve had a number of discussions with people about
this, and have had a bit of a tricky time explaining it -- we’ve
realized that this is because there are multiple use cases, and people
have been pigeonholing the idea into their preconceived use-case.
The two *main* use-cases are:
“Evolving” documents (there were originally called “Living documents”,
but that name is already in use in the web community, and so we chose
another name to make it less confusing).
“State of Play” documents.
My main use-case / interest is the “evolving documents” idea, and so
I’ll be focusing on that
(the “State of Play” idea is taking the sorts of things used to plan
interop events in QUIC and HTTPBIS, and creating a common format and
location for them; this will be fleshed out further in the future).
There are a number of topics / drafts where the best current practice
changes over time - a simple example of this is something like routing
security, and so I’ll use it as an example (also, the concept was
first presented in GROW!), but the concept is applicable to all sorts
of cases.
The best practices for routing security (what / how to filter,
route-leak prevention, etc) change over time and it is not really
feasible to document how to e.g build route filters and then release
-bis documents quickly enough to keep up with how the operational
advice changes; this means that much of this sort of information
doesn’t get documented in the IETF, and instead is scattered around in
institutional knowledge, personal blogs, IRC channels, etc.
An obvious solution is to simply document this in an Internet Draft,
and then update the ID as the advice changes; this is indeed a
reasonable solution, but makes it hard to refer to the WG’s *best
current* understanding while still allowing the WG to continue working
on the draft. If you refer to a specific version
(draft-ietf-foo-bar-23) it is hard to let people (especially external
people!) know when the WG thinks that there is a new “stable” version
(draft-ietf-foo-bar-30); if you refer just to the draft name
(draft-ietf-foo-bar) it makes it hard for the WG to make any changes
to the draft without potentially causing confusion.
In order to allow us to refer to “stable” and “development” versions
of drafts I’m proposing that we use the draft naming scheme to
annotate a version as “stable”:
Currently when draft-wkumari-bar-03 gets adopted by the BAR working
group, it gets renamed to draft-ietf-foo-bar-00. I’m proposing that,
when a WG determines that there is consensus that a version of a draft
is “stable”, a copy of the draft would be created called
draft-stable-foo-bar-00. When a new version of draft-ietf-foo-bar is
deemed stable, it would be copied into draft-stable-foo-bar-01. This
is simple for external people to understand, etc. When and if the
draft becomes an RFC, the link for draft-stable-foo-bar would redirect
to RFCxxx (just like draft-ietf-foo-bar).
There are a few open questions / notes (AKA FAQ!):
1: How does the WG decide that a document is “stable”?
One obvious option would be for the chairs to run something that looks
like a very lightweight WGLC. Another would simply be to have the
chairs decide (chairs are already trusted to judge consensus). This is
still open and I’m looking for feedback…
2: What are we calling these?
The original name for this was “Living Documents” - a number of people
have pointed out that this name is already in use in, and so has
“baggage”. I’d love some suggestions, so far the closest I’ve gotten
is “Evolving Documents”. There are only 3 problems in computer
science: off-by-one errors and naming things…
3: Why did it take so long from IETF 103 till this is being suggested?
<Warren hangs head in shame> This has been sitting on my todo list,
and kept getting pushed down. I had some time at an ICANN meeting and
finally wrote it up…
4: We had also considered a new tag in the Datatracker, and allowing
the chairs to assign it to a specific version of a document; this
would have been simple to implement, but much of the purpose of this
idea is to make it easy for external people to reference the latest
version of a document - and expecting them to understand datatracker
tags seems more complex.
5: What happens when an “Evolving Document” dies?
Evolving documents are just copies of drafts, tagged with a prefix
(just like adopted WG documents are tagged with a draft-ietf) - this
means that they behave just like any other draft - it is hoped that,
if a WG decides to abandon an “evolving document” they would replace
it with a tombstone (e.g “The foo WG has decided to abandon this
document because $reasons”).
6: Can an Evolving Document update an RFC?!
Nope - see the previous question; this is simply a way to mark an ID
as “stable”, they don’t have special powers. Just like an ID cannot
update an RFC, neither can an Evolving Document.
7: Can an Evolving Document become an RFC?
No!, see the previous two questions :-) The ID that an evolving
document is a based on can be published an RFC (and it might be
identical to an evolving document), but this doesn’t in any way change
the RFC publication process. It is expected that if / when the ID gets
published, the datatracker link (e.g:
https://datatracker.ietf.org/doc/stable-foo-bar/ ) will point to the
published RFC, just like ID links (
https://datatracker.ietf.org/doc/draft-ietf-foo-bar/ ) currently do.
8: This looks like you are creating something like semantic versioning
for drafts. Why not simply create something like
draft-ietf-foo-bar-17.42.9?!
This does have some similarities, but I think a better analogy is
“development” and “release” branches. I also believe that the current
draft naming and versioning system has been around for a long time, is
well understood, and works well - we have lots of tooling which uses
it, and it has lots of history. I really really *really* don’t want to
mess with that - this proposal allows those who would like to annotate
a version as “stable” to do so without us mucking with the existing
process, etc.
9: This ain’t new, $person proposed something similar at $meeting_or_list….
Indeed. As an example, Phillip Hallam-Baker mentioned a desire for
something similar at the IETF102 plenary; I think that this
demonstrates that there is an interest for this, let’s explore it
further.
10: Does a WG have to use this? I think it’s a [waste of time |
confusing | useless for my WG | <something>]?
Nope. This is only for those WGs that would like to use it - if you
don’t want to use it, feel free to ignore it. If you think it would be
better if only $something, please come tell us. Obviously, if you feel
that this is harmful, please speak up!
Please come to the side meeting and discuss the idea of Evolving
Documents further,
Warren Kumari and Heather Flanagan
P.S: I'm traveling for the next few weeks (and am also part of the NOC
team, and so get to Montreal early), and so my responses might be
delayed - 'pologies in advance.
--
I don't think the execution is relevant when it was obviously a bad
idea in the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair
of pants.
---maf
I don't think the execution is relevant when it was obviously a bad idea in the first place.
This is like putting rabid weasels in your pants, and later expressing regret at having chosen those particular rabid weasels and that pair of pants.
---maf
This is like putting rabid weasels in your pants, and later expressing regret at having chosen those particular rabid weasels and that pair of pants.
---maf
