YANG deVELpment PrOCEss and maintenance (VELOCE)
draft-mahesh-opsawg-veloce-yang-01

Network Working Group                                    M. Jethanandani
Internet-Draft                                               Arrcus, Inc
Intended status: Experimental                                 5 May 2026
Expires: 6 November 2026

            YANG deVELpment PrOCEss and maintenance (VELOCE)
                   draft-mahesh-opsawg-veloce-yang-01

Abstract

   This document describes a YANG deVELpment 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/mjethanandani/veloce.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

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

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

Jethanandani             Expires 6 November 2026                [Page 1]
Internet-Draft                   VELOCE                         May 2026

   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  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions and Definitions . . . . . . . . . . . . . . .   3
   2.  VELOCE Procedure  . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Experimental Plan . . . . . . . . . . . . . . . . . . . . . .   5
     3.1.  What is the goal  . . . . . . . . . . . . . . . . . . . .   5
     3.2.  How will the experiment be conducted  . . . . . . . . . .   5
     3.3.  How will success be determined  . . . . . . . . . . . . .   6
     3.4.  What is the anticipated timeline  . . . . . . . . . . . .   6
   4.  Operational Considerations  . . . . . . . . . . . . . . . . .   6
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   8

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.

Jethanandani             Expires 6 November 2026                [Page 2]
Internet-Draft                   VELOCE                         May 2026

   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 (Section 3.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.

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:

   It is RECOMMENDED that IETF-hosted 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.

   A new 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 containerized build environment be provided in the
   repository to enable local validation of YANG modules (e.g., via
   yanglint) independently of the CI/CD pipeline, and to ensure a
   consistent development environment across all contributors.

Jethanandani             Expires 6 November 2026                [Page 3]
Internet-Draft                   VELOCE                         May 2026

   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 as they relate to migration, personal
   change or the WG closing is 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.

   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.
   They, along with corresponding links to the Pull Request (PR), are a
   useful way to record decisions made by the WG.

   PR 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.  Editors of the YANG
   module are encouraged not to accept changes into the "main" or
   "master" branch of the repository.  Instead, they should be directed
   to a branch that is used for development.  This allows the editors 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.

   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.

   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.

Jethanandani             Expires 6 November 2026                [Page 4]
Internet-Draft                   VELOCE                         May 2026

   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 bis version of the initial RFC MAY be considered if a major change
   needs to be added in the document.  Such a decision is left to the
   WG.  WG may decide to update an adopted YANG module in the IETF
   repository and only update the RFC to change the reference to the
   YANG module.

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.

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 modules,
   such that at least one of them is a new YANG module, and the other is
   a "bis" version of the YANG module.  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

Jethanandani             Expires 6 November 2026                [Page 5]
Internet-Draft                   VELOCE                         May 2026

   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.

   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.

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

Jethanandani             Expires 6 November 2026                [Page 6]
Internet-Draft                   VELOCE                         May 2026

   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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC2418]  Bradner, S., "IETF Working Group Guidelines and
              Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418,
              September 1998, <https://www.rfc-editor.org/info/rfc2418>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8874]  Thomson, M. and B. Stark, "Working Group GitHub Usage
              Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020,
              <https://www.rfc-editor.org/info/rfc8874>.

   [RFC8875]  Cooper, A. and P. Hoffman, "Working Group GitHub
              Administration", RFC 8875, DOI 10.17487/RFC8875, August
              2020, <https://www.rfc-editor.org/info/rfc8875>.

   [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, <https://www.rfc-editor.org/info/rfc9595>.

Jethanandani             Expires 6 November 2026                [Page 7]
Internet-Draft                   VELOCE                         May 2026

   [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, <https://www.rfc-editor.org/info/rfc9907>.

7.2.  Informative References

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, Italo Busi, and Mohamed Boucadair for their feedback during
   IETF 125.

Author's Address

   Mahesh Jethanandani
   Arrcus, Inc
   United States of America
   Email: mjethanandani@gmail.com

Jethanandani             Expires 6 November 2026                [Page 8]