Differences

This shows you the differences between two versions of the page.

--- rpc_github_roadmap [2025/07/16 22:08] – created jmahoney
+++ rpc_github_roadmap [2026/02/12 05:44] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 ===== Introduction =====
-The RPC currently uses a file system for storing documents that they are editing and a manual process for creating diffs (for details, see the [[current_file_mgmt|Current File Management, Issue Tracking, and Version Control]] page). The tools modernization plan includes incorporating GitHub for version control.
+The RPC currently uses a file system for storing documents that they are editing and a manual process for creating diffs (for details, see the [[current_file_mgmt|Current File Management, Issue Tracking, and Version Control]] page). The tools modernization plan includes incorporating git and GitHub for version control.
-===== Phase 1: Private repos for version control and publication support (in design) =====
+===== Phase 0: Minimal GitHub support for AUTH48 (in progress) =====
+Phase 0 is an optional pilot program where the RPC will create a document repo for authors who wish to use GitHub's review functionality for AUTH48.
+==== Repo Creation ====
+At the start of AUTH48, the RPC will manually create a repo using a template with the approved source file that entered the queue, which can be in either RFCXML or kramdown-rfc format. This file will be committed to the "approved" branch.
+The RPC will then create a "proposed-edits" branch that contains all the edits that they are proposing and then create a pull request (PR) from that branch. Questions to the authors will be added as issues to the repo's issue tracker.
+==== Editor and author interactions ====
+Both authors and RPC editors will work in the PR, using the [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests.|review tools provided by GitHub]].
+Specifically,
+  * [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request|Reviewing proposed changes in a pull request]]
+  * [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request|Incorporating feedback in your pull request]]
+The suggestion feature of the PR review can be used to tweak edits made in the branch. For larger edits, such as making terminology consistent throughout the document, an author can indicate how to make the update in a review or issue comment, and the RPC will commit those updates to the "proposed-edits" branch.
+The PR is merged when no issues remain. As is done currently, authors will provide their final approval of the document via email. If the source file is kramdown-rfc, then the RPC will convert the markdown to RFCXML and create a new PR with the RFCXML source file so authors can review any formatting changes made in the XML after conversion.
+If the authors want to make changes unrelated to the RPC's edits, they will need to create their own PR, which may need to be approved by the stream manager via email, depending on whether the  changes are beyond editorial.
+Once the document and outputs are approved, the RPC will copy the final source document to their file system to complete their publication procedures.
+==== Requirements for entering Phase 0 ====
+  * Create a repo template (in progress)
+  * Refresh GitHub training for editors (in progress)
+  * Fine-tune AUTH48 procedures and instructions to authors (in progress)
+  * Experimentation with a few documents first before opening the process more widely (in progress)
+Rollout: November 2025
+===== Phase 1: Internal version control and publication support (in progress) =====
 For the first phase of working with GitHub, document repos will remain private as the RPC implements and refines their internal processes for version control and publication.
@@ Line 11: / Line 45: @@
 ==== Repo Creation ====
-Each document's source file (RFCXML or kramdown-rfc) will be placed in its own repository, which is created by the queue management system (called Purple) once the document is approved. These repos will be private and only accessible by RPC staff.
+Each document's source file (RFCXML or kramdown-rfc) will be placed in its own repository, which is created by the queue management system (called [[https://github.com/ietf-tools/purple|Purple]]) once the document is approved. These repos will be private and only accessible by RPC staff.
 The repo will have [[https://docs.github.com/en/actions/get-started/understanding-github-actions|GitHub actions]] that will do the following:
@@ Line 19: / Line 53: @@
   * Provide links to these files on a staff accessible webpage so that editors can check the files upon commit. For example:
-![][image1]
+{{WIP_page.png?500|Example work-in-progress webpage}}
 ==== Editor Interactions ====
-The RPC editors will interact with the GitHub repo using DraftForge, the editing software created by the Tools Team. The editor will clone the repository locally, make changes to the document, commit those changes to their branches, and create pull requests through DraftForge.
+The RPC editors will interact with the GitHub repo using [[https://github.com/ietf-tools/editor/|DraftForge]], the editing software created by the Tools Team. The editor will clone the repository locally, make changes to the document, commit those changes to their branches, and create pull requests through DraftForge.
-An editor will work in a branch that they created from main, making small commits as they work. They will create a pull request on GitHub when they have completed their work on the document for the next editor in the editing process to review. The document is first edited by the Document Specialist, who does formatting, then the Citation Specialist, who checks references and links, and the Primary Editor (PE), who copyedits the document.
+Editors will work in branches that they have created from main, making small commits as they work. They will create pull requests on GitHub when they have completed their work on the document for the next editor in the editing process to review. The document is first edited by the Document Specialist, who does formatting, then the Citation Specialist, who checks references and links, and the Primary Editor (PE), who copyedits the document.
-The PE will review the pull requests created by the Document and Citation Specialists and merge them into main when the PE is satisfied with the updates. The PE then creates a branch off main for their own edits.
+The PE will review the pull requests created by the Document and Citation Specialists and merge them into main when the PE is satisfied with the updates. The PE then creates branches off main for their own edits.
-When the PE is done, they will create a pull request that the RFC Editor (RE) will review. The RE will merge the branch into main when their review is complete. The RE will then create a new branch from main for their own edits. When they have completed their editing work, they will merge the branch into main.
+When the PE is done, RFC Editor (RE) will review the PE's pull requests. The RE will merge the PRs into main when their review is complete. The RE will then create branches from main for their own edits. When they have completed their editing work, they will merge their branches into main.
 === Issue Tracking ===
-Questions and issues between editors can be added to the repo's issue tracker. For questions that involve suggested text, an editor can create a pull request against the working branch showing the changes. However, questions to authors will continue to be placed in the document so the authors can see the questions as they review the source file. These questions can be exported via DraftForge and placed in an email message to authors.
+Questions and issues between editors can be added to the repo's issue tracker. For questions that involve suggested text, an editor can create a pull request against the working branch showing the changes. However, questions to authors will continue to be placed in the document so the authors can see the questions as they review the source file. An editor can export the questions using DraftForge and place them in an email message to authors.
 ==== AUTH48 ====
@@ Line 41: / Line 75: @@
 The editor who launches AUTH48 will invoke a GitHub action to make the web page that links to the formats, source, and diff files public. Another action will send an email message to the authors and other interested parties (ADs, WG chairs, etc.) to let them know that the RFC is available for final review.
-![][image2]
+{{auth48_review_page.png?500|Example AUTH48 webpage}}
 The editor handling AUTH48 will create an auth48 branch and make commits for updates received by the authors.
@@ Line 55: / Line 89: @@
 The publishing editor reviews the pre-pub PR and makes any other updates. Occasionally, the publishing editor asks the authors a question and may update the document based on that question. The publishing editor merges the PR into main when they are ready to publish.
-The publishing editor invokes a set of publication GitHub actions to run the preptool, and to place files and data with various services (rfc-editor.org, datatracker, rsync, bib.ietf.org, crossref.org).
+The publishing editor or Purple (TBD) invokes a set of publication GitHub actions to run the preptool, and to place files and data with various services (rfc-editor.org, datatracker, rsync, bib.ietf.org, crossref.org).
+Once an RFC is published, its repo is archived.
 ==== Requirements for entering Phase 1 ====
@@ Line 61: / Line 97: @@
   * DraftForge with following features: GitHub support, XML validation (in progress)
   * DraftForge training for editors (todo)
-  * Purple integration with GitHub (todo)
+  * Purple integration with GitHub (in progress)
   * GitHub actions created and functioning (todo)
   * Refresh GitHub training for editors (todo)
+  * Migrate from the current file system to GitHub repos
+Estimated rollout timeframe: Spring 2026
 ===== Phase 2: Collaborating with authors during AUTH48 (todo) =====
@@ Line 79: / Line 118: @@
 A PR created by an author will be reviewed by an editor. If there are no issues, the editor will merge it. If the changes are beyond editorial, the editor will ask the stream approver to review and review the PR.
-Once all PRs are merged and the authors have approved the document, the publication process continues as described in the first phase. An action will be available to help the authors merge a clone of the RPC repo into their document repo if they have one so they can have both their repo's history and the RPC repo's history of their document.
+Once all PRs are merged and the authors have approved the document, the publication process continues as described in the first phase. An action will be available to help the authors merge the RPC's edits into their document repo if they have one so they can have both their repo's history and the RPC repo's history of their document (Note: feedback from the community is that this proposed action to help authors port GitHub history to their repo may not be feasible or necessary).
 ==== Requirements for entering Phase 2 ====
@@ Line 87: / Line 126: @@
   * Experimentation with a few documents first before opening more widely (todo)
+Estimated rollout timeframe: Late Summer 2026
+----
+For more information about RPC projects, please see:
+  * [[https://github.com/orgs/rfc-editor/projects/2/views/1|RPC Roadmap]]
+  * [[https://datatracker.ietf.org/group/rpc/meetings/|RPC Community Calls]]