]> Arrcus, Inc

US mjethanandani@gmail.com

YANG GitHub 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 Source for this draft and an issue tracker can be found at .

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 document, and the YANG module. The document 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 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. Guidance for writing YANG modules is discussed in . Guidelines related to code components () or citations to references listed in the YANG module do not apply to VELOCE.

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.

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 Working Group GitHub Usage Guidance. 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 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 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. The procedure for managing WG documents (e.g., assign editors) applies for managing YANG modules (IETF Working Group Guidelines and Procedures). For considerations related to granting editors write and administrators' right refer to Working Group GitHub Usage Guidance. Other administrative policies as they relate to migration, personal change or the WG closing is 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 Working Group GitHub Usage Guidance. 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. A procedure for assessing consensus is discussed in Working Group GitHub Usage Guidance 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. 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.

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

The goal of the experiment is to determine how the YANG modules can be developed outside of an RFC, while making sure that all the IETF processes are followed, including making sure that the WG is involved in the development of the module, and it has the rough consensus of the WG, and the IETF as a whole, before it is "published".

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.

The "exit criteria" for the experiment will be successful publication of the modules that are identified as part of the experiment.

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 experiment should not take more than two years to develop. If the experiment takes longer than that, 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.

This document has no operational considerations at this time.

The security considerations discussed in apply here.

This document has no IANA actions.

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.