Re: The RPC's roadmap regarding GitHub

[Rohan Mahy <[e-mail]>]

Hi Rob,
This loses the property that is so valuable about generating the files to
be included.

All, I think a better approach would be for the RPC to accept a snapshot of
all the included files with a corresponding git commit hash from the
original repo. Is this something that could be added to the process please?
It would not completely automate the process of fixing an error in the
generated examples, but would contain the changes in a very manageable way
IMO.

thanks,
-rohan

On Wed, 5 Aug 2026, 10:28 Rob Wilton (rwilton), <[e-mail]> wrote:

> Hi Mike,
>
> I'm sure that you and your fellow editors thought this all through, but
> I'm slightly surprised by your conclusion.
>
> Why not ask an LLM to trivially write a script to inline the includes into
> a complete markdown doc but keep some comment markers for the inclusions in
> place.  Naively, I would assume that this would end up being easier work to
> reverse patch the RPC changes back into the original markdown files, which
> again, I would expect an LLM would be able to help with, than doing it via
> similar changes to the XML file.
>
> Kind regards,
> Rob
>
>
> *From: *Mike Ounsworth <mike=[e-mail]>
> *Date: *Wednesday, 5 August 2026 at 15:16
> *To: *Rohan Mahy <[e-mail]>
> *Cc: *Jean Mahoney <[e-mail]>; WG Chairs <
> [e-mail]>
> *Subject: *Re: The RPC's roadmap regarding GitHub
>
> Rohan: +3 !
>
> The RPC will retract offering you the "Edit in Markdown" option if you use
> the {::include } markdown macro, which is an INCREDIBLY useful feature of
> writing drafts in markdown.
>
> As a concrete example of this,
> https://github.com/lamps-wg/draft-composite-sigs
> is a textbook use of MT's automation: we have not modified MT's makefiles
> in any way and some of our authors now only edit in github and don't even
> have a local toolchain set up.
> That said, the draft has like 50 pages of ASN.1, tables and test vectors,
> and the authors kept having copy&paste errors where the various tables were
> out of sync with each other. So we sucked out all the tables and test
> vectors into
>   src/labesTable.md
>   src/sizeTable.md
>   src/testVectors.json
>   ...
>
> and then we {::include } those into the markdown. (those .md files are
> generated by the same python code that spits out the test vectors,
> completely eliminating manual error, but that's besides the point here). In
> the end, we have 6 uses of the {::include } macro, and that was _Night And
> Day_ for eliminating author copy&paste errors.
>
> Unfortunately, that makes the whole document ineligible for processing by
> the RPC as markdown: the RPC gave us the choice of manually copy&past'ing
> all the included files into the .md, or proceeding with editing in xml. We
> chose to edit in xml because we've been bitten so many times by copy&paste
> errors. This means that the RPC editor is likely to have a bad time editing
> this document in xml (given that none of the authors have ever looked at
> the xml), and also I have a horrible job coming of backporting changes to
> the xml back into markdown so that the WG-owned repo stays in sync with the
> published RFC. All-in-all, this does not feel like progress towards an
> efficient and low-manual-error process.
>
> -Mike
>
> *"Knowing is a barrier which prevents learning" -- Frank Herbert, Dune.*
>
> *"An expert is a person who has found out by his own painful experience
> all the mistakes that one can make in a very narrow field.” -- Niels Bohr*
>
> On Wednesday, August 5th, 2026 at 3:57 AM, Rohan Mahy <
> [e-mail]> wrote:
>
> Hi,
> I want to highlight a potential issue here with copying markdown files
> from the original source repo to the RFC editor repo.
>
> The best practice for drafts that have lots of examples of non-text
> formats, test vectors, and examples of hashes and encryption, is to
> generate the examples from some working code, preferably that can be
> machine validated. This means the repo has or runs code to generate the
> examples.
>
>
> In many of my drafts, my grammars (ABNF, TLS PL, CDDL) are snippet source
> files that appear included in the markdown and are then concatenated for
> validation.
> Likewise my examples are generated, validatdd, the get included in the
> markdown.
>
> If the RFC editor converts the markdown with include files into a markdown
> with inline content, then making a small change in the original source
> could result in substantial diffs (think hashes and test vectors).
> On the other hand, requiring the RFC editor to run arbitrary tools to
> generate text, doesn't seem appropriate either (even if these are properly
> integrated in MT's template).
> thanks,
> -rohan
>
> On Tue, 4 Aug 2026, 11:56 Mike Ounsworth, <mike=
> [e-mail]> wrote:
>
> Thanks Jean,
>
> I want to add for this audience, that I think there are two separate
> things that people think of as "editing in github" that I was getting mixed
> up, and others might too. This was only finally cleared up for me when I
> chatted with you at the RPC desk in Vienna.
>
>
> 1)
> Whether the authors of the draft have been working in github as the
> document moves through WG. This would include things like:
>
> * Using MT's github actions for markdown editing.
> * Collecting WG feedback in github issues
> * Hosting design discussions in github issues instead of / in addition to
> the mailing list.
> * Accepting WG feedback as PRs
> * Using the repo to hold additional materials, such as sample data,
> reference or hackathon implementations, design team meeting notes, pptx
> files for IETF meeting presentations, etc.
>
> Typically this is done in a github repo owned by one of the authors, or
> moved to a gh repo owned by the WG (although I think this is all informal
> and not really established process). For example, all the WGs I participate
> in have gh spaces maintained by the WG chairs:
>
> * https://github.com/lamps-wg/
> * https://github.com/ietf-wg-acme/
> * https://github.com/ietf-rats-wg/
>
>
>
> 2)
> The RPC will, while intaking a document into the RFC Queue, create a new
> RPC-owned github repo and hard-copy the .xml or .md from whehever the
> authors have been working on it. The RPC will do their iterative work in
> this gh repo, which is available to the authors to follow along if they
> prefer this over other review methods.
>
>
>
> The lightbulb I had recently is that these two things are completely
> separate and have nothing to do with each other.
>
> My personal view is that where the WG has a gh repo for the draft, that
> should be considered the official copy. When the RFC is published, any
> changes made by the RPC should be backported into it so that it builds the
> same version of the document as the published RFC. I think this is
> important so that if, in the future, the WG decides to de a -bis of that
> RFC, they have an up-to-date copy of the document source to start from. If
> the RPC finds that (2) is a convenient way for them to work, I have no
> problem with that, but I think that should be considered RPC-internal
> process and should not supersede a WG-owned repo in terms of which one is
> "the official copy".
>
>
> Given this, the end-state that I would like to see is that where a
> WG-owned gh repo already exists, the RPC should work there not in a newly
> created hard-copy. I see risks of (2) that we end up with two "official"
> copies of the document source: one owned by the RPC and one owned by the
> WG. At a minimum, we probably need written-down process to make sure that
> those stay in-sync with each other. The path I'm envisioning probably
> requires standardizing how WG gh repos are run -- you probably want them
> all centralized under an IETF Org so that the RPC staff (and not just the
> WG chairs) have administrative access to them.
>
>
> -Mike Ounsworth
>
> "Knowing is a barrier which prevents learning" -- Frank Herbert, Dune.
>
>
> "An expert is a person who has found out by his own painful experience all
> the mistakes that one can make in a very narrow field.” -- Niels Bohr
>
> On Monday, August 3rd, 2026 at 4:43 PM, Jean Mahoney <
> [e-mail]> wrote:
>
> > Hi all,
> >
> > Thanks for the comments received during the RPC presentation at the WG
> > Chairs Lunch at IETF 126! I'd like to highlight the RPC's roadmap
> > regarding GitHub, which was solidified after the RPC solicited community
> > input in Sept 2025:
> >
> > https://rpc-wiki.rfc-editor.org/doku.php?id=rpc_github_roadmap
> >
> > The RPC started with Phase 0 in November 2025. We are still accepting 5
> > documents per month for the process described in Phase 0, which includes
> > the creation of a repo at the beginning of Final Review and a single PR
> > that contains all RPC edits.
> >
> > With the rollout of our new tools in May 2026, we are now working on
> > Phase 1. In particular, documents entering the queue are now being
> > placed in GitHub repos, and editors are using git for version control as
> > they edit documents. Upcoming work for this phase is to add GitHub
> > actions to make this process smoother.
> >
> > During Phase 2, which is estimated to start in Fall 2026, the RPC will
> > share repos that will contain the entire RPC editing history with
> > authors who wish to conduct their Final Review in GitHub. Note that
> > authors are not required to interact with the repo; the current
> > email-based approach for Final Review will still be available.
> >
> > Best regards,
> > Jean
> >
> >
>
>
>