search

uuid6 / uuid6-ietf-draft

Next Generation UUID Formats
https://datatracker.ietf.org/doc/draft-peabody-dispatch-new-uuid-format/
187 stars 11 forks source link

build script for running lint and render using ietf API #47

Closed broofa closed 2 years ago

broofa commented 2 years ago

Found myself trying to figure out how to contribute and ended up going off on a tangent trying to make the xml2rfc step... well... usable. This is what I ended up with. Just a simple CLI for linting and building spec documents from the command line using the IETF tools API. Not sure how helpful this will be, but figured I'd put this up in case it was deemed useful.

Note: The IETF API uses xml2rfc@3.12 while the current version of documents on master was generated with xml2rfc@3.9. This results in various minor formatting changes to the rendered documents (not included in this PR, but you'll notice this as soon as you run the tool).

$ build
Usage: build [command]

Available commands:
  lint - validate document
  html - render html format
  text - render text format
  all - lint (then render all formats)

Aside: It'd be nice if there were a CONTRIBUTING.md document that laid out the process expected for anyone wanting to contribute a PR.

kyzer-davis commented 2 years ago

Neat! Let me check it out when I put some cycles into Draft 03 this month and next. If it looks good I am fine to merge.

Found myself trying to figure out how to contribute and ended up going off on a tangent trying to make the xml2rfc step

The actual process of creating an RFC-Complaint XML document for a draft RFC is very cumbersome. There are a ton of various tools documented by the IETF themselves and formatting net-new sections so the IETF XML parsers can understand and format the document properly has been harder than actually writing the text sometimes. I also have the benefit of knowing some folks here at Cisco that have been through the entire IETF draft process from idea inception, draft iteration, to RFC publish; so if there are any problems that I (or others) can't figure out I usually run it by them.

Aside: It'd be nice if there were a CONTRIBUTING.md document that laid out the process expected for anyone wanting to contribute a PR.

But you are right: Outlining the minimum tools, reading, and items required to get up to speed and contribute would be beneficial to everybody.