Differences

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

--- rpc_github_roadmap [2025/10/15 22:14] – Phase 0 training in progress jmahoney
+++ rpc_github_roadmap [2026/08/20 19:20] (current) – Added an FAQ jmahoney
@@ 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 git and GitHub for version control.
+The RPC is currently migrating away from a file system for storing the documents that they are editing and a manual process for creating diffs (for details about this previous system, see the [[current_file_mgmt|Legacy File Management, Issue Tracking, and Version Control]] page). The tools modernization plan includes incorporating git and GitHub for version control.
-===== Phase 0: Minimal GitHub support for AUTH48 (in design) =====
+===== Phase 0: Minimal GitHub support for Final Review (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.
+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 Final Review. This phase was designed after [[https://datatracker.ietf.org/meeting/interim-2025-rpc-07/session/rpc|discussion with the community in Sept 2025]].
 ==== 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.
+At the start of Final Review, 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.
+The RPC will then create a "RPC-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]].
+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 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 "RPC-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.
@@ Line 32: / Line 32: @@
 ==== Requirements for entering Phase 0 ====
-  * Create a repo template (in progress)
+  * Create a repo template (done)
-  * Refresh GitHub training for editors (in progress)
+  * Refresh GitHub training for editors (done)
-  * Fine-tune AUTH48 procedures and instructions to authors (in progress)
+  * Fine-tune Final Review procedures and instructions to authors (in progress)
-  * Experimentation with a few documents first before opening the process more widely (todo)
+  * Experimentation with a few documents first before opening the process more widely (in progress)
-Estimated rollout timeframe: November 2025
+Rollout: November 2025
-===== Phase 1: Internal version control and publication support (in design) =====
+===== 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 57: / Line 57: @@
 ==== Editor Interactions ====
-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.
+The RPC editors will interact with the GitHub repo using [[https://github.com/ietf-tools/draftforge|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.
-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.
+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 First Editor (also known as a Primary Editor or 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 branches off main for their own edits.
-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.
+When the PE is done, the Second Editor (also known as an RFC Editor or 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 ===
@@ Line 69: / Line 69: @@
 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 ====
+==== Final Review ====
 Interactions with authors will continue to occur via email during the first phase.
-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.
+The editor who launches Final Review 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.
-{{auth48_review_page.png?500|Example AUTH48 webpage}}
+{{auth48_review_page.png?500|Example Final Review webpage}}
-The editor handling AUTH48 will create an auth48 branch and make commits for updates received by the authors.
+The editor handling Final Review will create an RPC-edits branch and make commits for updates received by the authors.
 Note that author approvals and IANA actions will be handled via Purple and not via GitHub actions.
@@ Line 83: / Line 83: @@
 ==== Pre-publication ====
-Once the authors have approved the document, the editor merges the auth48 branch into main. They create a pre-pub branch for any updates that need to be made before publication. These edits tend to be small things like updating the date and usually do not require further author approvals.
+Once the authors have approved the document, the editor merges the RPC-edits branch into main. They create a pre-pub branch for any updates that need to be made before publication. These edits tend to be small things like updating the date and usually do not require further author approvals.
 ==== Publication ====
@@ Line 89: / 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 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).
+The publishing editor invokes a set of publication GitHub actions to run the preptool, and Purple places 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.
@@ Line 95: / Line 95: @@
 ==== Requirements for entering Phase 1 ====
-  * DraftForge with following features: GitHub support, XML validation (in progress)
+  * DraftForge with following features: GitHub support, XML validation (done)
-  * DraftForge training for editors (todo)
+  * DraftForge training for editors (in progress)
-  * 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
+  * Migrate from the current file system to GitHub repos (in progress)
-Estimated rollout timeframe: Spring 2026
+Rollout: started late May 2026
-===== Phase 2: Collaborating with authors during AUTH48 (todo) =====
+===== Phase 2: Collaborating with authors during Final Review (todo) =====
-For the second phase, the GitHub repo can be shared with authors, ADs, chairs, and Doc Shepherds (aka the document team), who can be made repo collaborators when the document enters AUTH48, but an author's interaction with the repo is not mandatory. Authors may choose not to interact with the GitHub repo and may continue to use the email-based AUTH48 process as GitHub is not the main workflow mechanism for the streams.
+For the second phase, the GitHub repo can be shared with authors, ADs, chairs, and Doc Shepherds (aka the document team), who can be made repo collaborators when the document enters Final Review, but an author's interaction with the repo is not mandatory. Authors may choose not to interact with the GitHub repo and may continue to use the email-based Final Review process as GitHub is not the main workflow mechanism for the streams.
 ==== Process ====
@@ Line 112: / Line 112: @@
 The RPC will confirm that the entire document team is willing to use GitHub when the document enters the queue. If a document team member is unwilling to work with GitHub, then the email-based process will be used.
-Questions to the authors will be placed in the issue tracker. The editor will construct PRs that have suggested text updates that address issues in the issue tracker. The editor will make the repo public and available to the collaborators at the beginning of AUTH48. PRs that suggest changes to the document text will be open for author review.
+Questions to the authors will be placed in the issue tracker. The editor will construct PRs that have suggested text updates that address issues in the issue tracker. The editor will make the repo public and available to the collaborators at the beginning of Final Review. PRs that suggest changes to the document text will be open for author review.
 Authors will review the RPC's PRs and can either merge the PR if they approve, or they can provide their own text suggestions (by either editing the branch or creating their own branch). Authors can create PRs to address open questions in the issue tracker.
@@ Line 122: / Line 122: @@
 ==== Requirements for entering Phase 2 ====
-  * Team comfort with GitHub processes - estimated to take 3 months time after Phase 1 complete (todo)
+  * Team comfort with GitHub processes - estimated to take 6 months time after Phase 1 complete (in progress)
   * GitHub actions created and functioning (todo)
-  * Experimentation with a few documents first before opening more widely (todo)
+  * Experimentation with a few documents first before opening more widely (in progress)
+Estimated rollout timeframe: Fall 2026
+===== Frequently Asked Questions =====
+**Q:** Why doesn't the RPC fork the working group's repo?
+**A:** The use of GitHub and its features is not consistent across working groups. A working group may not even have a GitHub repo. Some working groups place all their drafts in one repo, others construct repos for each document. Some working groups use repos that belong to the authors. Working groups will differ in their processes and how they use GitHub features. For example, some repos use actions, some don't. The RPC cannot know the status and processes for each repo that has been used for the documents that have entered the RFC Editor queue.
+**Q:** But isn't the RPC's repo redundant with the document's repo?
+**A:** The RPC's repos are separate from the document's working repo. The RPC's repos support the RPC's editing and publication work. Each RPC repo contains configurations for editing tools and files that support integration with the queue management system and publication automation. When an RFC is published, the repo serves as the archive of the published files.
-Estimated rollout timeframe: Late Summer 2026
 ----