]> Huawei

bill.wu@huawei.com

Sandelman Software Works

mcr+ietf@sandelman.ca

Huawei

dd@dhruvdhody.com

Operations and Management Operations and Management Area Working Group yang development process maintenance 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 The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Operations and Management Area Working Group Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

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 . Guidelines related to code components (Section3.2 of ) or citations to references listed in the YANG module do not apply to VELOCE.

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 when, and only when, they appear in all capitals, as shown here.

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:

New YANG Module Draft Development It is RECOMMENDED that IETF-controlled repositories be used. See Section 1.3 of Working Group GitHub Usage Guidance . 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 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 ). For considerations related to granting editors write and administrators' right refer to Section 3.3 of Working Group GitHub Usage Guidance . Other administrative policies such as ones relate to migration, personnel changes or the WG closing are defined in the Working Group GitHub Administration . 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. Contribution methods for the YANG module are similar to those defined in Section 4 of Working Group GitHub Usage Guidance . 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 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 . A procedure for assessing consensus is discussed in Section 7 of Working Group GitHub Usage Guidance 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 citing the specific module version (e.g., its revision-date or YANG Semver ) rather than the RFC number alone, since the module may evolve independently of the RFC text. YANG SID files , 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.

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. 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.

Experimental Plan Much like other experimental documents, this document tries to answer the following four questions as they relate to experimental documents.

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.

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.

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 . 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.

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.
• 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.

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.

Security Considerations The security considerations discussed in Section 10 of apply here.

IANA Considerations This document has no IANA actions.

References Normative References This document provides guidelines for authors and reviewers of specifications containing YANG data models, including IANA-maintained YANG modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONF protocol implementations that utilize YANG modules. This document obsoletes RFC 8407; it also updates RFC 8126 by providing additional guidelines for writing the IANA considerations for RFCs that specify IANA-maintained YANG modules. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document provides a set of guidelines for working groups that choose to use GitHub for their work. This document describes the guidelines and procedures for formation and operation of IETF working groups. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The use of GitHub in IETF working group processes is increasing. This document describes uses and conventions for working groups that are considering starting to use GitHub. It does not mandate any processes and does not require changes to the processes used by current and future working groups not using GitHub. YANG Schema Item iDentifiers (YANG SIDs) are globally unique 63-bit unsigned integers used to identify YANG items. SIDs provide a more compact method for identifying those YANG items that can be used efficiently, notably in constrained environments (RFC 7228). This document defines the semantics, registration processes, and assignment processes for YANG SIDs for IETF-managed YANG modules. To enable the implementation of these processes, this document also defines a file format used to persist and publish assigned YANG SIDs. Informative References Cisco Systems, Inc. Cisco Systems, Inc. Equinix Ericsson Nokia Everything OPS This document specifies a YANG extension along with guidelines for applying an extended set of semantic versioning rules to revisions of YANG artifacts (e.g., modules and packages). Additionally, this document defines a YANG extension for controlling module imports based on these modified semantic versioning rules. This document updates RFCs 7950, 9907, and 8525.

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 Arrcus

mjethanandani@gmail.com

Huawei

Italo.Busi@huawei.com

Equinix

reshad@yahoo.com