Convert the specification into RFC format #466

jyasskin · 2025-01-06T15:10:19Z

Fixes #461.

You can see a preview at https://jyasskin.github.io/kdl/draft-marchan-kdl2.html.

zkat · 2025-01-06T19:18:07Z

.github/workflows/archive.yml

+
+on:
+  schedule:
+    - cron: '0 0 * * 0,2,4'


I guess this is because IETF considers all discussions and repo history as normative or such?

We don't need to keep all of the actions if you don't want one of them. Discussion wouldn't be normative, but it's useful to have them around later. But for an archive of GitHub content to be useful, it would have to be stored away from GitHub, which this isn't, so I don't really see the point. It just comes with the default setup. Let me know if you'd rather I delete it.

Maybe we can skip doing this for now, then, until we actually figure out an external storage system. If you decide to do that, though, please file an issue about it so we don't completely forget to do it.

CONTRIBUTING.md

Makefile

draft-marchan-kdl2.md

zkat

Oops I didn’t mean to approve

jyasskin · 2025-01-07T03:41:23Z

.github/workflows/archive.yml

+
+on:
+  schedule:
+    - cron: '0 0 * * 0,2,4'


We don't need to keep all of the actions if you don't want one of them. Discussion wouldn't be normative, but it's useful to have them around later. But for an archive of GitHub content to be useful, it would have to be stored away from GitHub, which this isn't, so I don't really see the point. It just comes with the default setup. Let me know if you'd rather I delete it.

jyasskin · 2025-01-07T03:42:37Z

.github/workflows/update.yml

@@ -0,0 +1,36 @@
+name: "Update Generated Files"


Reading this one, it's actually dangerous enough that I've deleted it.

CONTRIBUTING.md

Makefile

draft-marchan-kdl2.md

zkat

I realized halfway through reviewing this that the places where I said "missing section link) ARE actually getting sections, but that those are the places where both the name and the section are links.

So maybe we can just turn those into Foo ([Section1](...)) for consistency?

zkat · 2025-01-07T06:43:35Z

draft-marchan-kdl2.md


-### Document
+## Document

 The toplevel concept of KDL is a Document. A Document is composed of zero or
 more [Nodes](#node), separated by newlines and whitespace, and eventually


Two things:

Looks like this specific instance is missing the section link. Perhaps there are other cases?

On a more general note, I notice that there's some inconsistency as to events we do [Foo](#foo) ([Section 1](#section1)) or just Foo ([Section 1](...)). I would prefer we normalize around one. The second (just one link) probably makes the most sense, since linking the name itself seems redundant if you're going to link the section anyway.

Yep, this is cabo/kramdown-rfc#249. Works for me to use just the Foo ({{foo}}) link structure. I'm a little nervous that'll be so many changes that it breaks git's move-detection, but if it does, we can always split it into a separate PR.

draft-marchan-kdl2.md

zkat

This looks good to me, but I'd like to let others get a chance to weigh in on the idea of doing this, before we go through with it.

Additionally, I note that there's a particular copyright notice, and I'm confused as to whether it needs modification or it just applies to the "boilerplate": https://trustee.ietf.org/about/faq/#reproducing-rfcs

We would, of course, like the copyrights to belong to KDL Contributors. One small snag might be that the contents of this repository are licensed under CC-BY-SA-4.0, which is definitely a more restrictive license than the IETF seems to expect (with good reason!!). If we are to change the license situation, we'll definitely want to make sure we know what we need to relicense to and then start the relicensing process, which might take a while, since it requires consent from every single person who has ever contributed to this repo. I believe we can cross that bridge when we get to it, though. I personally like the RFC format regardless of whether the IETF takes us on :)

zkat · 2025-01-08T05:01:48Z

Cc @tabatkins @borland @bgotink @larsgw @danini-the-panini and of course whoever else wants to chime in. We should probably set up an org team so we can ping one specific group for anyone interested in spec discussions

danini-the-panini

I'm also seeing a lot of "line too long warnings". I'm not sure if that's a deal-breaker, but I'll make a PR to try address them.

Also, do we need to rewrite the full grammar to use ABNF as described in RFC5234?

danini-the-panini · 2025-01-09T07:34:53Z

CONTRIBUTING.md

+https://author-tools.ietf.org/ or locally by running `make`. To preserve the
+intermediate RFCXML form in a local build, `touch draft-marchan-kdl2.xml` before
+running `make`.


I tried this and I just got an error

❯ touch draft-marchan-kdl2.xml ❯ make Error: Unable to parse the XML document: draft-marchan-kdl2.xml draft-marchan-kdl2: xml2rfc-txt ... FAIL make: *** [draft-marchan-kdl2.txt] Error 1

Yeah, this was silly of me. touch works if you're careful with the file timestamps, but it's less fiddly to just make that target. Fixed.

zkat · 2025-01-09T09:43:58Z

Also, do we need to rewrite the full grammar to use ABNF as described in RFC5234?

@danini-the-panini #461 (comment)

tl;dr no, but they might ask us to formalize our DSL later, maybe.

jyasskin

I figured out how to remove the default Copyright Notice in the RFC-style spec, by adding ipr: none in the header. I also copied the CC-BY-SA license declaration into a note in the spec.

@danini-the-panini, thanks for tackling the line-too-long warnings in #470.

jyasskin · 2025-01-11T00:21:22Z

CONTRIBUTING.md

+https://author-tools.ietf.org/ or locally by running `make`. To preserve the
+intermediate RFCXML form in a local build, `touch draft-marchan-kdl2.xml` before
+running `make`.


Yeah, this was silly of me. touch works if you're careful with the file timestamps, but it's less fiddly to just make that target. Fixed.

jyasskin · 2025-01-11T04:40:28Z

CONTRIBUTING.md

+This repository relates to activities in the Internet Engineering Task Force
+([IETF](https://www.ietf.org/)). All material in this repository is considered
+Contributions to the IETF Standards Process, as defined in the intellectual
+property policies of IETF currently designated as
+[BCP 78](https://www.rfc-editor.org/info/bcp78),
+[BCP 79](https://www.rfc-editor.org/info/bcp79) and the
+[IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html).
+
+Any edit, commit, pull request, issue, comment or other change made to this
+repository constitutes Contributions to the IETF Standards Process
+(https://www.ietf.org/).
+
+You agree to comply with all applicable IETF policies and procedures, including,
+BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being
+subject to a Simplified BSD License) in Contributions.


I believe that this block asserts that future contributions are licensed to the IETF Trust so that they can be used in an RFC, but it might be misleading about how past contributions have been licensed. I'm not a lawyer or an expert on this, but I think it'll be ok for you to put whatever you want here, or nothing at all, and then go back and relicense the whole thing when the IETF asks you to. What do you want here?

Any work based on the existing KDL spec carries the viral “share alike” bit. That’s kinda the whole point of that license.

From what I can gather, the IETF expects very specific licensing, which, most notably, prevents derivative works entirely. https://trustee.ietf.org/documents/trust-legal-provisions/tlp-5/ lays out licensing expectations pretty clearly. I’m pretty sure we wouldn’t even be able to dual license here.

In any case, I’m not opposed to relicensing, but we’re gonna need to start that process sooner rather than later, because it’s time consuming to track everyone down and get their consent. Additionally, we’ll need to find guidance on exactly how to license stuff in this repo so we don’t need to repeat the process just because we relicensed wrong.

I’ll make a separate issue for this

+1 for discussing in a separate issue. Do you want me to remove the licensing change in CONTRIBUTING until that's resolved?

The licensing requirements for you are less strict than you're reading, but I'm going to cc in someone who knows more (mnot) to help with the detailed discussion on that issue. In particular, I believe you need to collectively give a particular license to the IETF Trust, but your source material can also be licensed however you want to everyone else. Then the final RFC itself is licensed by the IETF Trust with some fairly restrictive conditions, but even the draft in RFC format can be more freely licensed. But we can verify the details on the issue.

Probably good to remove it for now, yes.

zkat · 2025-01-17T17:53:49Z

Can you resolve conflicts? I think I'm happy enough to merge this sooner rather than later, and no one seems opposed to this rewrite.

…inthomson/i-d-template

This works around cabo/kramdown-rfc#249.

RFCXML v3 doesn't include horizontal rules.

That compiles to <sourcecode> which preserves sequences of spaces.

For if installing the dependencies is inconvenient.

… the anchor.

jyasskin · 2025-01-18T04:29:22Z

Conflicts resolved.

zkat · 2025-01-18T05:06:34Z

@jyasskin thank you so much! I'm so excited :)

jyasskin mentioned this pull request Jan 6, 2025

Write spec in IETF RFC style #461

Closed

zkat approved these changes Jan 6, 2025

View reviewed changes

zkat reviewed Jan 6, 2025

View reviewed changes

jyasskin commented Jan 7, 2025

View reviewed changes

zkat reviewed Jan 7, 2025

View reviewed changes

zkat approved these changes Jan 8, 2025

View reviewed changes

danini-the-panini reviewed Jan 9, 2025

View reviewed changes

danini-the-panini mentioned this pull request Jan 9, 2025

Update SPEC to keep lines lengths short #470

Merged

jyasskin commented Jan 11, 2025

View reviewed changes

jyasskin force-pushed the main branch from 01922fe to c44201c Compare January 11, 2025 04:53

jyasskin added 17 commits January 17, 2025 20:20

Initial conversion to Internet-Draft.

8f544ed

Setup repository for draft-marchan-kdl2 using https://github.com/mart…

d344e41

…inthomson/i-d-template

Remove unnecessary changes.

dd1c109

Tweak source to make the I-D build.

bcc78c9

Fix zkat's name. Guess at their preferred initials.

4512ecb

Separate links where linking text equals the anchor.

826d60e

This works around cabo/kramdown-rfc#249.

Replace horizontal rules with subsections.

7a77c4e

RFCXML v3 doesn't include horizontal rules.

Use ~~~kdl instead of `` for strings with significant whitespace.

7f1c8b1

That compiles to <sourcecode> which preserves sequences of spaces.

Give breadcrumbs to the RFC format definitions.

feb9eb0

Point contributors to https://author-tools.ietf.org/.

109ad26

For if installing the dependencies is inconvenient.

Separate a code block from adjacent text.

a8fb072

Remove a workflow that overwrites customized files.

6359d03

Remove the 'archive' workflow.

469089d

Use "Term ({{term}})" uniformly instead of just when the term matches…

dad097a

… the anchor.

Fix the instructions for preserving the RFCXML.

340f206

Remove the default copyright notice until the spec is relicensed.

dd4f344

Take the IETF licensing details out of CONTRIBUTING.md.

6e2bdba

jyasskin force-pushed the main branch from 3d0b50e to 6e2bdba Compare January 18, 2025 04:26

zkat merged commit 4263a9d into kdl-org:main Jan 18, 2025
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert the specification into RFC format #466

Convert the specification into RFC format #466

jyasskin commented Jan 6, 2025

zkat Jan 6, 2025

jyasskin Jan 7, 2025

zkat Jan 7, 2025

jyasskin Jan 7, 2025

zkat left a comment

jyasskin Jan 7, 2025

jyasskin Jan 7, 2025

zkat left a comment

zkat Jan 7, 2025

jyasskin Jan 7, 2025

zkat left a comment

zkat commented Jan 8, 2025

danini-the-panini left a comment

danini-the-panini Jan 9, 2025

jyasskin Jan 11, 2025

zkat commented Jan 9, 2025

jyasskin left a comment

jyasskin Jan 11, 2025

jyasskin Jan 11, 2025

zkat Jan 11, 2025

jyasskin Jan 11, 2025

zkat Jan 11, 2025

jyasskin Jan 11, 2025

zkat commented Jan 17, 2025

jyasskin commented Jan 18, 2025

zkat commented Jan 18, 2025

Convert the specification into RFC format #466

Convert the specification into RFC format #466

Conversation

jyasskin commented Jan 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zkat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zkat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zkat left a comment

Choose a reason for hiding this comment

zkat commented Jan 8, 2025

danini-the-panini left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zkat commented Jan 9, 2025

jyasskin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zkat commented Jan 17, 2025

jyasskin commented Jan 18, 2025

zkat commented Jan 18, 2025