Subject: Question about pseudocode and <CODE BEGINS>

From: Brian E Carpenter <[email-masked]>
Date: Tue, 14 Dec 2021 10:34:29 +1300

Hi,

Do people think it's a good or bad idea to label pseudocode
in an RFC with <CODE BEGINS>?

The reason it seems like a good idea is so that readers are
free to use the pseudocode as the basis for real code,
under the BSD license that the IETF Trust grants for code
components.

I'm not sure why it might be a bad idea, but the Trust's
legal language seems to refer only to real code.

(The case in point is
https://www.ietf.org/archive/id/draft-ietf-anima-asa-guidelines-04.html#appendix-C-14 )
  
Regards
    Brian Carpenter

---

From: Russ Housley <[email-masked]>
Date: Mon, 13 Dec 2021 16:42:15 -0500

The point of <CODE BEGINS> and <CODE ENDS> is to be clear that it can be copied into an implementation.  Doe you envision the pseudocode being put in the code, even as comments?

Russ

> On Dec 13, 2021, at 4:34 PM, Brian E Carpenter <[email-masked]> wrote:
> 
> Hi,
>

---

From: "Salz, Rich" <[email-masked]>
Date: Mon, 13 Dec 2021 21:45:54 +0000

>    The point of <CODE BEGINS> and <CODE ENDS> is to be clear that it can be copied into an implementation.  Doe you envision the pseudocode being put in the code, even as comments?

I can see that copying it into an implementation as comments could be very useful, so yes.

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 14 Dec 2021 11:01:59 +1300

> I can see that copying it into an implementation as comments could be very useful, so yes.

Yes, I certainly wouldn't exclude that. In any case, copying snippets would be OK. Most of the actual example is abstract, but there are a few literal snippets from the code of a demo implementation (which is already under a BSD license).

     Brian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 14 Dec 2021 01:25:00 +0100

> The point of <CODE BEGINS> and <CODE ENDS> is to be clear that it can be copied into an implementation.  Doe you envision the pseudocode being put in the code, even as comments?

Indeed, the criterion should not be what language the code is in (pseudocode being a not-so-well-defined language, but still a language), but whether the code is intended to be (1) an illustration or to be (2) a template that can be used in implementation.  Note that “real code” often also needs massaging before it can be used in an implementation.  The illustration is fine with a documentation license, but the template needs a code license.  (Of course, some code is dual use; test vectors for example are often both illustration and code, so they need a code license.)

Grüße, Carsten

---

From: "John Levine" <[email-masked]>
Date: 13 Dec 2021 21:21:56 -0500

>I can see that copying it into an implementation as comments could be very useful, so yes.

Urrgh. The TLP says that the code license applies to "components
intended to be directly processed by a computer".  That doesn't
include pseudo-code.  But ...

The code license requires that you include the three paragraph Revised
BSD license, while the rule for text is that the excerpt must be
copied verbatim with "all IETF legends, legal notices and indications
of authorship contained in the original IETF RFC." 

In this case I think you're better off treating it as text.  The only
advantage of the code license is that you can modify the code, but it
doesn't sound like that's an issue here.

R's.
John

---

From: "John Levine" <[email-masked]>
Date: 13 Dec 2021 22:14:39 -0500

>doesn't sound like that's an issue here.

Replying to myself, if someone started with your pseudocode and wrote
an equivalent in a real programming language, I'd say that's not the
text from the draft, even if it shares some variable names, so I
wouldn't worry about it.

R's,
John

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 14 Dec 2021 16:14:44 +1300

> doesn't sound like that's an issue here.

If the pseudocode has any value, it would be to serve as framework
for an actual implementation. Both solutions seem wrong for that.

Frankly I'd prefer if it could be a DWTFYWWI license, but I don't think
the IETF Trust has one of those. Maybe we need a CC0 option too?

    Brian

---

From: "John Levine" <[email-masked]>
Date: 14 Dec 2021 09:59:45 -0500

>the IETF Trust has one of those. Maybe we need a CC0 option too?

The trust license is non-exclusive.  As the author, you can let people
do whatever you want with the stuff you wrote.

R's,
John

PS: The BSD license is effectively DWTFYWWIBDSU, where those last
letters stand for But Don't Sue Us.

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 15 Dec 2021 08:53:33 +1300

> do whatever you want with the stuff you wrote.

Yes indeed.

> letters stand for But Don't Sue Us.

I think that's why CC0 is more than a few words long, too.

Anyway, I'm seeing arguments why <CODE BEGINS> is reasonable for pseudocode.

     Brian

---

From: "John R Levine" <[email-masked]>
Date: 14 Dec 2021 14:55:56 -0500

> Anyway, I'm seeing arguments why <CODE BEGINS> is reasonable for pseudocode.

I agree that it's reasonable, but it's not what the TLP says.  I can talk 
to the other trustees about it.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Job Snijders <[email-masked]>
Date: Wed, 15 Dec 2021 13:05:04 +0100

Hi Brian, others,

(... apologies for potentially pulling this thread direction you didn't
have in mind when initiating this conversation)

> in an RFC with <CODE BEGINS>?

I think pseudo-code in RFCs is a bad idea... regardless of the label! :-)

Pseudo-code literally is just fantasy speak; probably closer related to
dada poetry (it being a chaotic expression rather than something that is
productive!). Pseudo-code - by both definition and tradition - cannot be
interpreted in any meaningful way.

There is no compiler available for 'pseudo-code', so how can humans
ever stand a chance to make sense of what the authors intended? 

I'd like to point out two examples:

Example #1: Dissemination of Flow Specification Rules (now RFC 8955)
-----------
One of the challenges with implementing Flowspec rule ordering was that
the original specification included pseudo-code, which was one of the
aspects that multiple implementers ended up mis-implementing to some
degree, because there was ambiguity: https://datatracker.ietf.org/doc/html/rfc5575#section-5.1

When the -bis effort started, it was pointed out that the pseudo-code
was highly problematic and one of the sources of confusion, which led to
the -bis document being needed in the first place! The authors agreed
and graciously contributed their time to improve the document by
replacing pseudo-code with python code.

  Fantasy code: https://datatracker.ietf.org/doc/html/draft-ietf-idr-rfc5575bis-04#section-5.1
   Actual code: https://datatracker.ietf.org/doc/html/draft-ietf-idr-rfc5575bis-05#section-5.1

Anyone will agree that the actual code serves a purpose, whereas the
fantasy pseudo-code introduces more room for implementation error.

Example #2: RPKI Origin Validation (RFC 6811)
-----------
This snippet increased confusion, rather than help prevent it:
https://datatracker.ietf.org/doc/html/rfc6811#section-2.1

---

All in all - I believe pseudo-code should be eradicated from the IETF's
body of work, rather than be wrapped or labeled. Use of pseudo-code
should be discouraged at all levels of our organization.

Kind regards,

Job

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Dec 2021 13:23:19 +0100

> should be discouraged at all levels of our organization.

Non sequitur, I’d say.

Yes, pseudocode can have problems.  As can any other form of description.
As long as author and reviewers are aware of these problems, they can be mitigated.

I’ll offer Page 4 of RFC 7396 as an example where pseudocode has worked very well (*).
Sure, this could have been translated into Python or Ruby without much change, but the pseudocode is readable to people with very different programming backgrounds.

What is a larger danger in my experience is lengthy sequences that really are pseudocode but are instead phrased as English prose (still with all the problems pseudocode can have, see above), without any explanation for *why* a particular (often confusing) algorithmic choice was made in that normative English-language-as-pseudocode implementation.

(This is also true of pseudo-formal descriptions other than code; a recent example was 7484bis where the English-language data description did not address some questions that were obvious once we tried translating them into CDDL — now CDDL is not pseudocode, but the translation clearly demonstrated that there was a false sense of security about the semiformal English-language description.)

Grüße, Carsten

(*) Well, except for the RFC 7386 desaster, but that was ASCII HT characters creeping into the final editing of an RFC…

---

From: tom petch <[email-masked]>
Date: Wed, 15 Dec 2021 12:34:21 +0000

>> should be discouraged at all levels of our organization.

Moi aussi.

Since programming got structured, concepts such a
if -then  -else
do while
and such like have become universal and much clearer than a prose 
descripion.  Can be overdone of course but I would rely on the judgement 
of an ART reviewer as to what is likely to be understood by most.

In the example quoted, I would add a few 'then' and perhaps semicolon 
for end of statement

Tom Petch

> .

---

From: Nick Hilliard <[email-masked]>
Date: Wed, 15 Dec 2021 13:33:14 +0000

> in an RFC with <CODE BEGINS>?

it seems unnecessary?  Pseudocode is aimed at humans rather than 
computers, so a friendly lead-in might be more accessible.

If there were a strict grammar defined for pseudocode, i.e. to the point 
that you could feed it into a parser and get useful output, then there 
would be an argument for a delimiter token.

Nick

---

From: Bob Hinden <[email-masked]>
Date: Wed, 15 Dec 2021 09:50:24 -0800

> On Dec 15, 2021, at 5:33 AM, Nick Hilliard <[email-masked]> wrote:
> 
> it seems unnecessary?  Pseudocode is aimed at humans rather than computers, so a friendly lead-in might be more accessible.
> 
> If there were a strict grammar defined for pseudocode, i.e. to the point that you could feed it into a parser and get useful output, then there would be an argument for a delimiter token.

I agree, it not necessary to have a delimiter token.  Just say something like:

   A suggested algorithm in pseudo code for <foo> is as follows:

in the document.   It is essentially just text.

Bob

---

From: "John Levine" <[email-masked]>
Date: 15 Dec 2021 13:44:31 -0500

>in the document.   It is essentially just text.

I agree except for the "essentially".  It is just text.

We went through a long process to decide what licenses to offer for RFCs and for
computer code in them.  The TLP even describes what we consider to be code:

https://trustee.ietf.org/documents/trust-legal-provisions/code-components-list-3/

R's,
John

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Dec 2021 20:04:24 +0100

>> 	• tables of values
>> 	• classical programming code

So I’ll stop putting things into item lists (or at least make sure they are also in a table).

I think some of the discussion here essentially was about whether the various forms of pseudocode are “classical programming code”.
Of course, we also have different jurisdictions in the backs of our minds; if I think about copyright I might really be thinking about Urheberrecht/droit d’auteur…

But large parts of the discussion were about the usefulness of <CODE BEGINS> in a document without being informed that this is a legal mechanism only.

Grüße, Carsten

---

From: "John R Levine" <[email-masked]>
Date: 15 Dec 2021 14:14:29 -0500

> So I’ll stop putting things into item lists (or at least make sure they are also in a table).

I agree that the swamp is deep here.

> Of course, we also have different jurisdictions in the backs of our minds; if I think about copyright I might really be thinking about Urheberrecht/droit d’auteur…

Hey, we're in the U.S.  Moral rights do not exist unless you are spray 
painting graffiti on a derilict building that is torn down.*

> But large parts of the discussion were about the usefulness of <CODE BEGINS> in a document without being informed that this is a legal mechanism only.

In case I haven't said this clearly enough, CODE BEGINS is merely a hint. 
If something is code it gets the BSD licence, if it isn't, it doesn't, 
regardless of whether it is labeled.

Regards,

* - see https://www.trademarkandcopyrightlawblog.com/2018/02/multimillion-dollar-moral-rights-judgment-for-5pointz-graffiti-artists/

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 08:45:42 +1300

> https://trustee.ietf.org/documents/trust-legal-provisions/code-components-list-3/

As has been pointed out off list, that list is incomplete, which would be OK if it was stated to be non-exclusive, but it isn't.

My original concern was different - if an implementer wants to borrow from the pseudocode to make real code, they might be making a derivative work from the RFC in a way that is not allowed by the Trust's legal provisions**.

As far as I know, we have never discussed this issue to see what the community consensus might be.

** Before John says it, the author of the pseudocode is perfectly at liberty to grant any license for it that they want, outside the IETF standards process. But that's more work and may be tricky in a corporate context.

Regards
     Brian

---

From: Christian Huitema <[email-masked]>
Date: Wed, 15 Dec 2021 11:53:29 -0800

On 12/15/2021 11:45 AM, Brian E Carpenter wrote:
> My original concern was different - if an implementer wants to borrow 
> from the pseudocode to make real code, they might be making a 
> derivative work from the RFC in a way that is not allowed by the 
> Trust's legal provisions**. 

How is that different from reading the text of the RFC and building code 
based on it?

-- Christian Huitema

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 14:54:54 -0500

The list is the list of things that will be considered to be code even 
if they are not marked.  As such, it is inherently complete.  And  not 
limiting.

The trust complies with RFC 8721 section 4.3 in this regard.

Yours,
Joel

On 12/15/2021 2:45 PM, Brian E Carpenter wrote:
> As has been pointed out off list, that list is incomplete, which would 
> be OK if it was stated to be non-exclusive, but it isn't.
> 
> from the pseudocode to make real code, they might be making a derivative 
> work from the RFC in a way that is not allowed by the Trust's legal 
> provisions**.
> 
> ** Before John says it, the author of the pseudocode is perfectly at 
> liberty to grant any license for it that they want, outside the IETF 
> standards process. But that's more work and may be tricky in a corporate 
> context.
> 
> Regards
>      Brian
>

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 09:16:19 +1300

Hi Job,

> have in mind when initiating this conversation)

So I changed the subject.

> interpreted in any meaningful way.

I disagree. But there are certainly at least two different cases:

1) Pseudocode used for descriptive or illustrative purposes, because
it is clearer and more compact than describing a mechanism in plain
text. I think there are many examples of this.

2) Pseudocode that claims to be mathematically precise, that could
in principle be interpreted by a computer, but in practice will
be interpreted by a software or hardware designer. One example is
RFC8986, which says:
"The pseudocode describing these behaviors details local processing
at a node. An implementation of the pseudocode is compliant as long
as the externally observable wire protocol is as described by the
pseudocode."

> ever stand a chance to make sense of what the authors intended?

I spent a lot of time on the draft that became RFC8986, to
understand exactly what it was describing and whether it violated
RFC8200, and I found that the pseudocode fragments were far more
precise and normative than the text.
  
> Example #1: Dissemination of Flow Specification Rules (now RFC 8955)

Yes, if it purports to be normative but is not correctly verified.
As far as I know, RFC8986 doesn't have that problem.

However, there's a problem in including "real" code as in your example.
Real code needs context, carries library dependencies with it, and
so on. The case that is behind my original message is very informal
pseudocode *derived from* running Python code. It would have been
totally unreasonable to use the original Python for illustrative
purposes.

> Example #2: RPKI Origin Validation (RFC 6811)

I'll take your word for it. So, I agree, don't use pseudocode
for illustrative purposes when it might compete with normative
text.
  
> should be discouraged at all levels of our organization.

I believe that goes too far. But you draw attention to the dangers of
using pseudocode carelessly as pseudonormative material.

     Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 09:18:04 +1300

Joel,
> if they are not marked.  As such, it is inherently complete.  And  not

Yes, but the list doesn't state that it's not limiting. IMHO that's a bug.

    Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 09:19:36 +1300

> How is that different from reading the text of the RFC and building code

If I cut and paste from pseudocode into real code, am I violating the Trust
license?

    Brian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Dec 2021 21:27:24 +0100

On 2021-12-15, at 21:16, Brian E Carpenter <[email-masked]> wrote:
> 
> But you draw attention to the dangers of

… which, obviously, is different from using pseudocode carefully as normative material …

I think we’d need to spend some time on eliciting the properties the pseudocode must have to count as “using pseudocode carefully”.  See my previous message.

Grüße, Carsten

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 15:52:16 -0500

The FAQ, which points to the code components list, is clear that the 
list is only about what is automatically considered code.  For that 
purpose, the list is comprehensive.  Anything not listed there is not 
considered code unless it is marked <code begin>...

I am not sure what clarification you are asking for?

Yours,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 15:55:13 -0500

The link to the FAQ section is: https://trustee.ietf.org/about/faq/#code

Yours,
Joel

On 12/15/2021 3:52 PM, Joel M. Halpern wrote:
>>>> derivative

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 10:13:37 +1300

> I am not sure what clarification you are asking for?

The FAQ is fine but the list does not explain itself.

OLD:
Code Components which may be found in IETF Contributions and IETF Documents:

NEW:
Non-exclusive list of Code Components which may be found in IETF Contributions and IETF Documents:

Regards
     Brian

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 16:21:21 -0500

If it needs clarification, it would not be that.
I suppose (although i would like to think about it, and of course would 
need to talk to my fellow trustees) that

New:
Components in IETF Contributions which are considered code without 
special marking are:

might be a useful edit.

Yours
Joel

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 16 Dec 2021 10:33:04 +1300

> Components in IETF Contributions which are considered code without

Yes, if the Trust also commits to regularly updating the list as new formats (such as CDDL) appear.

    Brian

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 16:48:36 -0500

First, it is not urgent to regularly update the list, since any code not 
listed can be marked using <code begins>.

Still, second, yes, it is the trustees job to update the list.

Yours,
Joel

On 12/15/2021 4:33 PM, Brian E Carpenter wrote:
>>>>>>>> computer code in them.  The TLP even describes what we consider 
>>>>>>>> to be
>>>>>>>> code:
>>>>>>>>

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 15 Dec 2021 22:52:13 +0100

On 2021-12-15, at 22:48, Joel M. Halpern <[email-masked]> wrote:
> 
> First, it is not urgent to regularly update the list, since any code not listed can be marked using <code begins>.
> 

If the list is updated and starts to retroactively apply to RFCs already published, the set of rights granted also retroactively changes.

So I think the way it is set up, it is important to maintain this list carefully, keep old versions, and document which RFCs have been published under which version.

Grüße, Carsten

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 15 Dec 2021 16:55:44 -0500

Good point.  The RFC says that the Trust shall maintain the list.  But, 
as you say, it clearly can't apply retroactively.  Not sure what the 
right way is to handle it.

Yours,
Joel

---

From: Stephan Wenger <[email-masked]>
Date: Wed, 15 Dec 2021 22:00:04 +0000

.... a versioned list?
S.

On 12/15/21, 13:56, "ietf on behalf of Joel M. Halpern" <[email-masked] on behalf of [email-masked]> wrote:

    Yours,
    Joel

---

From: Robert Sparks <[email-masked]>
Date: Wed, 15 Dec 2021 16:22:33 -0600

I had reason to wonder what old versions of the ID guidelines looked 
like, and when they changed recently, and wished there had been some 
sort of version control maintained over it.

Please consider building something that self-documents at least dates of 
changes?

RjS

---

From: "John Levine" <[email-masked]>
Date: 15 Dec 2021 17:28:40 -0500

It appears that Brian E Carpenter  <[email-masked]> said:
>My original concern was different - if an implementer wants to borrow from the pseudocode to make real code, they might be making a derivative work from the RFC in a way that is not allowed by the Trust's legal provisions.

Oops, I lied.  A friend pointed out a sentence in the TLP I had missed, which says that if something is marked with CODE BEGINS,
it's licensed as code, regardless of what it might otherwise be:

<CODE BEGINS>
It was a dark and stormy night; 
the rain fell in torrents—
except at occasional intervals, 
when it was checked by a violent gust of wind 
which swept up the streets 
(for it is in London that our scene lies), 
rattling along the housetops, 
and fiercely agitating the scanty flame of the lamps 
that struggled against the darkness.
<CODE ENDS>

Were that to appear in an RFC, anyone can extract it and modify it so long as they
also include this license text:

================================================================
Copyright (c) 2021 IETF Trust and the persons identified as authors of
the code. All rights reserved. Redistribution and use in source and
binary forms, with or without modification, are permitted provided
that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

* Neither the name of Internet Society, IETF or IETF Trust, nor the
names of specific contributors, may be used to endorse or promote
products derived from this software without specific prior written
permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
================================================================

Your call.

R's,
John

---

From: "John Levine" <[email-masked]>
Date: 15 Dec 2021 17:31:22 -0500

>.... a versioned list?

Scroll down to the bottom of this page and we appear to have one, with the current list being 3.0.

	https://trustee.ietf.org/documents/trust-legal-provisions/

On the other hand, it says the 3.0 list was approved in 2009, and it includes CBOR which wasn't
invented until 2013, so I fear our predecessors have been a bit lax in their version management.

R's,
John

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 16 Dec 2021 00:49:19 +0100

> also include this license text:

Is there any information recorded which widely used licenses this code license is compatible with?
What is its SPDX Identifier?

How do I effect dual licensing with, say MIT (or even 0BSD) of code I have authored for an RFC to be published?  For an I-D?  (In such a way that this dual licensing is actually findable…)

(Of course, these are all not really questions to you; just questions I’d like to find the answer for.)

Grüße, Carsten

---

From: Vasilenko Eduard <[email-masked]>
Date: Thu, 16 Dec 2021 07:41:07 +0000

+1
The delimiter is unnecessary for humans.
But pseudo-code could not be processed by a machine - no standard interpretation.
Ed/
-----Original Message-----
From: ietf [mailto:[email-masked]] On Behalf Of Nick Hilliard
Sent: Wednesday, December 15, 2021 4:33 PM
To: Brian E Carpenter <[email-masked]>
Cc: IETF discussion list <[email-masked]>
Subject: Re: Question about pseudocode and <CODE BEGINS>

Brian E Carpenter wrote on 13/12/2021 21:34:
> Do people think it's a good or bad idea to label pseudocode in an RFC 
> with <CODE BEGINS>?

Nick