Re: Evolving Documents (nee "Living Documents") side meeting at IETF105.

[Warren Kumari <[e-mail]>]

[ 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 <[e-mail]> 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