Operations and Management Area Working Group Q. Wu Internet-Draft Huawei Intended status: Experimental M. Richardson Expires: 6 May 2027 Sandelman Software Works D. Dhody Huawei 2 November 2026 YANG deVELpment PrOCEss and maintenance (VELOCE) draft-ietf-opsawg-veloce-yang-01 Abstract This document describes a YANG deVELopment PrOCEss and maintenance (VELOCE) that is more suitable for the development of YANG modules or YANG modules update within the IETF. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/ietf-opsawg-wg/veloce/tree/main. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://ietf- opsawg-wg.github.io/veloce/draft-ietf-opsawg-veloce-yang.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-opsawg-veloce-yang/. Discussion of this document takes place on the Operations and Management Area Working Group Working Group mailing list (mailto:opsawg@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/opsawg/. Subscribe at https://www.ietf.org/mailman/listinfo/opsawg/. Source for this draft and an issue tracker can be found at https://github.com/ietf-opsawg-wg/veloce. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Wu, et al. Expires 6 May 2027 [Page 1] Internet-Draft VELOCE November 2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 6 May 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 2. VELOCE Procedure . . . . . . . . . . . . . . . . . . . . . . 4 2.1. New YANG Module Draft Development . . . . . . . . . . . . 4 2.2. The Existing YANG Module Update/Maintenance . . . . . . . 6 3. Experimental Plan . . . . . . . . . . . . . . . . . . . . . . 7 3.1. What is the goal . . . . . . . . . . . . . . . . . . . . 7 3.2. How will the experiment be conducted . . . . . . . . . . 8 3.3. How will success be determined . . . . . . . . . . . . . 8 3.4. What is the anticipated timeline . . . . . . . . . . . . 8 4. Operational Considerations . . . . . . . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 7.2. Informative References . . . . . . . . . . . . . . . . . 10 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 10 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 Wu, et al. Expires 6 May 2027 [Page 2] Internet-Draft VELOCE November 2026 1. Introduction IETF has used RFCs to publish its documents. However, RFCs, which are text documents, are not well-suited for iterative development of YANG modules that come in the form of source code. This document proposes a new approach for documenting and publishing IETF YANG modules. While this document mainly focuses on the IETF modules, IANA modules that are included in drafts, and removed ultimately on publication, can follow a similar process during the development of the IANA module. This document proposes that the publishing of a YANG module should be split into two parts: the text portion, hereby referred to as the prose, and the YANG module. The prose SHOULD continue to be used for describing the model, defining IANA Considerations, defining the Security Considerations, describing any Operational Considerations, capturing the Normative and the Informative References, etc. The YANG module, along with any related files such as YANG SID files, should be developed and maintained in a separate Source Code Mechanism (SCM) repository such as GitHub. The SCM SHOULD provide a stable link to the YANG module, which should then be included as a reference in the document. There are several reasons to develop the YANG module in an SCM. SCM provides version control and improves traceability of changes. Modern SCM provides the ability for Continuous Integration/Continuous Development (CI/CD). YANG modules can be fully validated before they are published. Changes to the module can be submitted by providing changes to the affected portions of the source code instead of the entire module. Reviews and comments can be gathered on the changes being proposed. This iterative approach lends itself to faster development and fixing of issues in YANG modules. Guidance for writing YANG modules is discussed in [RFC9907]. Guidelines related to code components (Section3.2 of [RFC9907]) or citations to references listed in the YANG module do not apply to VELOCE. 1.1. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Wu, et al. Expires 6 May 2027 [Page 3] Internet-Draft VELOCE November 2026 2. VELOCE Procedure The following practices should provide the necessary guidance on how a WG develops a new YANG module or updates an existing YANG module: 2.1. New YANG Module Draft Development It is RECOMMENDED that IETF-controlled repositories be used. See Section 1.3 of Working Group GitHub Usage Guidance [RFC8874]. Integration using third-party hosted repositories MAY be used for experimentation purposes. An IETF-controlled repository MUST be created by the WG Chairs following the procedure in Section 3.2 of Working Group GitHub Usage Guidance [RFC8874] to develop or maintain a YANG Module. For a new module, this SHOULD happen when the module is adopted as a WG item. It MAY happen for individual drafts, and that is left to the discretion of the chairs. However, once the document is adopted as a WG item, the repository SHOULD reside under the auspecies of IETF- controlled repository and managed by the WG. The name of the repository SHOULD reflect the name of the draft. In addition, the chairs MAY make sure that an appropriate CI/CD YANG validation is in place. It is RECOMMENDED that a real time collaborative working environment be provided in the repository to enable online validation of YANG modules (e.g., via yanglint) using the YANG template with the CI/CD pipeline (e.g., https://github.com/ IETF-OPS-AD/I-D-with-yang-template), and to ensure a consistent development environment across all contributors. In addition, a containerized build environment for local validation of YANG modules MAY also be provided in the repository as a backup. The procedure for managing WG documents (e.g., assign editors) applies for managing YANG modules (Section 6.1 of IETF Working Group Guidelines and Procedures [RFC2418]). For considerations related to granting editors write and administrators' right refer to Section 3.3 of Working Group GitHub Usage Guidance [RFC8874]. Other administrative policies such as ones relate to migration, personnel changes or the WG closing are defined in the Working Group GitHub Administration [RFC8875]. A release tagging mechanism should be defined to track the intermediate versions referenced by WG I-Ds and by the RFC, once published. This can come in the form of a 'git tag' or by having a branch that corresponds to the version of the draft. Wu, et al. Expires 6 May 2027 [Page 4] Internet-Draft VELOCE November 2026 Contribution methods for the YANG module are similar to those defined in Section 4 of Working Group GitHub Usage Guidance [RFC8874]. This includes the use of Issues to track open issues regarding the module, email notifications of activity on working group repositories, Editor's reporting or change log about the changes to the document (refer to to Section 4.3 of [RFC8874] for monitoring activity). They, along with corresponding links to the Pull Request (PR), are a useful way to record decisions made by the WG. PRs allow for a user to request a change to the repository. A user does not need to have write access to the repository. A fork of the repository allows the user to make changes, validate them, and post the changes as a PR against the WG repository. The editor team for regular contributors can be set up by the working group. Editors or editor team of the YANG module are encouraged not to accept changes into the "main" branch of the repository. Instead, they should be directed to a branch that is used for development. This allows the editors or editor team to review the changes and make sure that they are in line with the WG consensus before they are merged into the main branch. This also allows the editors to make sure that the changes are properly validated before they are merged into the main branch,e.g., one editor creates a pull request and another editor merges it (refer to Section 4.2 of [RFC8874]. A procedure for assessing consensus is discussed in Section 7 of Working Group GitHub Usage Guidance [RFC8874] and SHOULD be followed when accepting changes to the module in the ongoing working group document. This include approving and merging changes by document editors appointed by the Working group at the discretion of the editor team, making decision on consensus regarding changes to document, recording details of decisions in issue comments, closing issues by document editor or user that open those issues. Working group chairs should be involved to make sure the consensus has been reached when Editors summarize the issues to the WG to prepare for a new release. The YANG module MUST NOT be inserted in the document; instead, a link to the above repository MUST be included in the document. The link MUST point to a specific tagged version of the YANG module (e.g., a git tag or commit hash), not to the HEAD of a branch, so that the module's contents at RFC publication time are permanently retrievable and verifiable. VELOCE does not mandate which version of a YANG module implementations must support. The link in the published RFC identifies the module version current at the time of publication in the IANA section, but implementations MAY track a later version at their discretion. Conformance to the module SHOULD be indicated by Wu, et al. Expires 6 May 2027 [Page 5] Internet-Draft VELOCE November 2026 citing the specific module version (e.g., its revision-date or YANG Semver [I-D.ietf-netmod-yang-semver]) rather than the RFC number alone, since the module may evolve independently of the RFC text. YANG SID files [RFC9595], when applicable (e.g., for YANG/CBOR encoding), SHOULD reside in the SCM repository rather than in the document. The use of RFC 8792 folding for SID files in Internet- Drafts is discouraged, as it is not compatible with current YANG Doctor tooling. A release tagging mechanism should be defined to track the intermediate versions referenced by WG I-Ds and by the RFC, once published. This can come in the form of a 'git tag' or by having a branch that corresponds to the version of the draft. 2.2. The Existing YANG Module Update/Maintenance When updating an existing module, it is RECOMMENDED to use the same WG repository of the initial version of YANG module for the updated module maintenance, so previous history is preserved as much as possible. If no existing repository exists, then a new one MUST be created, initialized with the last published YANG module. If there is an existing repository but the responsible WG was concluded, then such repository MUST be moved to the new responsible working group's GitHub, initialized with the last published YANG module and associated git history. In the latter case, a new repository should be created under the new WG, a new remote should be added to a checkout of the existing repository, and then pushed to the new repository. Then, the existing/old repository should be archived with a message added to the README pointing to the new repository. When updating an existing, published module with bug fix changes, IETF errata reports can be used to keep track of changes to the YANG module. In the case the errata only pertains to the YANG module, once the Area Director (AD) verifies the errata using the existing IETF process, a Pull Request (PR) is opened to merge the changes into the WG repository. In the case the errata only pertains to RFC text associated with YANG module, when an RFC Errata is verified, the datatracker allow building a version of the RFC with the applied errata, which is independent from VELOCE process. In the case the errata pertains to both RFC text and YANG module, when an RFC Errata is verified, the YANG module change needs to be submitted as a PR and verified by the Area Director and incorporated into WG repository while the RFC Narrative text also needs to be verified by Area Director and building a version of the RFC with the applied errata. Wu, et al. Expires 6 May 2027 [Page 6] Internet-Draft VELOCE November 2026 A bis version of the initial RFC MAY be considered if a major change needs to be added (e.g., add a new function ) in the document. Such a decision is left to the WG. In the case of narrative text update only, an updating RFC MUST be published following normal Working Group Last Call (WG LC), IETF Last Call (IETF LC), and IESG review. There is no change to this process under VELOCE. In the case of YANG module update only, the WG may decide to update a published YANG module in the IETF WG repository and only update the IANA to change the reference to the YANG module , i.e., the link MUST point to a specific tagged version of the YANG module. In such case, YANG module update should be submited as a PR and incorporated into WG repository with AD's approval. The IANA should be updated with corresponding version of the YANG module without republishing a new RFC. In the case of combined narrative and YANG module updates, YANG module needs to be updated in the WG repository with a PR approved by AD and make sure the updating RFC references the updated YANG module. an updating RFC MUST be published following normal Working Group Last Call (WG LC), IETF Last Call (IETF LC), and IESG review. 3. Experimental Plan Much like other experimental documents, this document tries to answer the following four questions as they relate to experimental documents. 3.1. What is the goal The goal of the experiment is to determine how YANG modules can be developed outside of an RFC, while making sure that all IETF processes are followed, including WG involvement in the development of the module, and rough consensus of the WG and the IETF as a whole, before it is "published". A key objective is to balance speed, quality, and community contribution. The experiment should demonstrate a faster path to delivering well-formed YANG modules, while not sacrificing the quality and the community involvement that the IETF process requires. In particular, the experiment aims to address the pain point of the -bis revision process, where re-publishing a large document just to update a small portion of the YANG module creates unnecessary delays due to review comments on otherwise unchanged sections. Wu, et al. Expires 6 May 2027 [Page 7] Internet-Draft VELOCE November 2026 3.2. How will the experiment be conducted YANG modules developed in the IETF fall broadly into two categories. They can be new modules, or they can be a "bis" version of the module. The experiment will consist of two or more YANG module work, such that at least one of them is a new YANG module, and the other is a "bis" version of the YANG module work. This is being done to make sure that the experiment covers all the IETF processes related to the development of YANG modules. Participants in the experiment are encouraged to document their overall experience, including whether the SCM-based approach genuinely improved participation and velocity, or whether observed speed gains were attributable to other factors such as low contention on a specific module. This qualitative feedback is as important to the experiment as the publication outcome itself. 3.3. How will success be determined The primary "exit criteria" for the experiment will be successful publication of the YANG modules identified as part of the experiment, within the timelines defined in Section 3.4. For an updated module, if IETF YANG model can be updated using an IETF WG consensus process (probably including an errata report) and WG github without republishing as a new RFC, the experiment should also be deemed as success. Beyond publication, success will also be evaluated based on whether the process improved community participation in YANG module development, and whether participants found the SCM- based workflow reduced friction compared to the traditional RFC-embedded approach. A report documenting the overall experience and outcomes of the experiment SHOULD be produced at the conclusion of the experiment. 3.4. What is the anticipated timeline YANG modules have traditionally taken a long time to develop, sometimes taking over four years. However, for the purpose of this experiment, and since the idea is to demonstrate a faster way for a new YANG module to be developed, the timelines for the experiment are as follows: * A new YANG module should be published within two years of the start of the experiment. Wu, et al. Expires 6 May 2027 [Page 8] Internet-Draft VELOCE November 2026 * A "bis" version of an existing YANG module, where the primary motivation is incremental updates rather than a ground-up redesign, should be published within one year. If the experiment takes longer than these timelines, the experiment should be deemed to have failed. At that time, an analysis can be done as to why it failed and determine if the experiment should be repeated. If the experiment succeeds, then this document can be classified as a BCP, and the process be followed for all YANG modules developed in IETF. 4. Operational Considerations The separation of YANG modules from their companion documents has implications for the YANG review process. YANG Doctors SHOULD review the YANG module at the specific tagged version referenced by the document, using tooling that can retrieve and validate modules directly from the SCM repository. Working Groups adopting VELOCE are encouraged to define milestone- based development targets for YANG modules. A phased approach, where an initial version covering core functionality is published within a defined timeframe, with subsequent updates published as needed, is preferable to indefinitely delaying publication while pursuing completeness. 5. Security Considerations The security considerations discussed in Section 10 of [RFC8874] apply here. 6. IANA Considerations This document has no IANA actions. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Wu, et al. Expires 6 May 2027 [Page 9] Internet-Draft VELOCE November 2026 [RFC2418] Bradner, S., "IETF Working Group Guidelines and Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, September 1998, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8874] Thomson, M. and B. Stark, "Working Group GitHub Usage Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020, . [RFC8875] Cooper, A. and P. Hoffman, "Working Group GitHub Administration", RFC 8875, DOI 10.17487/RFC8875, August 2020, . [RFC9595] Veillette, M., Ed., Pelov, A., Ed., Petrov, I., Ed., Bormann, C., and M. Richardson, "YANG Schema Item iDentifier (YANG SID)", RFC 9595, DOI 10.17487/RFC9595, July 2024, . [RFC9907] Bierman, A., Boucadair, M., Ed., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 9907, DOI 10.17487/RFC9907, March 2026, . 7.2. Informative References [I-D.ietf-netmod-yang-semver] Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne, J., and B. Claise, "YANG Semantic Versioning", Work in Progress, Internet-Draft, draft-ietf-netmod-yang-semver- 29, 6 October 2026, . Acknowledgments This draft is triggered by the discussion in NEMOPS IAB workshop. Thanks to the participants of OPSAWG for their comments that have helped shape this draft. In particular, thanks to Jeffrey Haas, Joe Clarke, Per Andersson, Italo Busi, and Mohamed Boucadair for their feedback during IETF 125. Contributors Wu, et al. Expires 6 May 2027 [Page 10] Internet-Draft VELOCE November 2026 Mahesh Jethanandani Arrcus Email: mjethanandani@gmail.com Italo Busi Huawei Email: Italo.Busi@huawei.com Reshad Rahman Equinix Email: reshad@yahoo.com Authors' Addresses Qin Wu Huawei Email: bill.wu@huawei.com Michael Richardson Sandelman Software Works Email: mcr+ietf@sandelman.ca Dhruv Dhody Huawei Email: dd@dhruvdhody.com Wu, et al. Expires 6 May 2027 [Page 11]