YANGsters repository guidelines

Contents

Introduction
Necessary Background Information
How the Repository Works
Practical Usage
Using the Repository
Module Naming Conventions
References

A repository for IEEE 802 management model information.

Introduction

IEEE 802.1 and 802.3 write IEEE Standards that include equipment management information that is used by operators to control their equipment that implements those IEEE Standards. The management information is an integral part of the IEEE Standard, but due to its nature is hard to use directly from the IEEE Standard file. Therefore, separate files are attached to the IEEE Standard document that contain the management information definition.

IEEE 802.1 and 802.3 also use an on-line public repository to store copies of the management information definitions. The on-line repository is non-normative, but simply a convenience to the development community that builds management systems for equipment based on IEEE Standards. The repository clearly includes the IEEE License information and identifies anything in the IEEE directories are consider IEEE Contributions and are covered by the IEEE-SA Copyright Policy.

Necessary Background Information

There are many management information modeling standards that are in common use. This document will focus on YANG [RFC7950]. The process described here can be applied to any other file-based management information mechanism (for example SNMP MIBs could use a similarly structured repository).

YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols (e.g., NETCONF [RFC6241], RESTCONF [RFC8040], etc.). As described in [RFC7950], a module is the basic unit of definition in YANG. A YANG module defines a single YANG data model and is typically stored in a file (one module per file).

For the technical community both inside and outside the IEEE to leverage the IEEE 802 work efficiently, it is worth ensuring structured access to the YANG-related files.

How the Repository Works

The YANG Catalog [yangcatalog] provides tools and APIs that provide a web-service front-end to the GitHub [github] based repository for YANG modules from any organization. Currently there are other Standards Bodies that have their YANG modules hosted in the repository (IETF, BBF, and MEF). The repository has a structure that provides standards bodies to have their license text included.

The structure is hierarchical. The top-level project name for the YANG repository is “YangModels”. Under that is a directory called “yang”. There are two main directories that have important meaning. Under “yang” there is a directory called “experimental” and a directory called “standard”. For the IEEE, any YANG contained under the “experimental” has no standing with any committee of the IEEE (but is still considered an IEEE Contribution) and represents experimental work that occurs before a PAR is approved. Once a PAR is approved the YANG can be moved to the “standard” directory by the assigned editor of the project. Under the “standard” directory, the IEEE has a “draft” directory and a “published” directory. For the IEEE, the “draft” directory is used for work that has an approved PAR, but the standard has not yet been approved. Once the project completes and the standard is approved, the YANG modules that appear in the published IEEE Standard are moved to the “published” directory.

Below is the structure of the IEEE portion of the repository.

https://github.com/YangModels/yang/tree/master

/experimental/ieee
- no mandated sub-directories
/standard/ieee
- /draft
  - /802
  - /802.1
  - /802.3
  - /802.11
  - /1588
  - /…
- /published
  - /802
  - /802.1
  - /802.3
  - /802.11
  - /1588
  - /…

In the yang directory, there is a file containing the rules that apply for each different standards body. The rules for any directory under the ieee directory are listed here:

IEEE License:

All files contained within this sub-directory are considered to be intended as IEEE Contributions.
All issues entered into the trouble ticket system for this directory are considered to be intended as IEEE Contributions.
All pull requests submitted for this directory are considered to be intended as IEEE Contributions.
All contributions to IEEE standards development (whether for an individual or entity standard) shall meet the requirements outlined in the IEEE-SA Copyright Policy [ieee-sa-copyright]
Copyright release for YANG modules: Users may freely reproduce the YANG modules contained under /experimental/ieee/ so that they can be used for their intended purpose.

Practical Usage

The IEEE process for developing and approving IEEE 802 Standards does not change. The YANG modules (just like the MIB modules before them) are an integral part of the standard and the published IEEE standard is the authoritative source for the material. Any differences are resolved by going to the published IEEE standard.

The Editor of the IEEE Project that has an integral YANG (or MIB) module is responsible for requesting an upload of the initial version or changes to the related YANG files in the repository. There is an IEEE 802 identified gatekeeper for the IEEE directories of the repository that must review and commit the changes that are requested. The gatekeeper takes the edits to the files and makes the changes available in the repository. Version control and comments on what changed in the version are kept by the repository. The gatekeeper insures that the changes made are by the authorized Editors. The gatekeeper also can do a verification check that the changes made were the changes agreed using the IEEE 802 balloting process. Once the project has completed the Editor requests that the related YANG files are moved from the draft directory to the published directory of the repository. The gatekeeper validates the files against the published IEEE Standard and commits the changes to the repository. Any differences between the published IEEE Standard and the YANG files will require the Editor to fix the YANG file(s) and request the gatekeeper to update the repository. If there is an error found in the IEEE Standard, the usual IEEE process for fixing errors in published standards is followed. The Editor can fix the YANG file, but the file will exist in the draft directory until the IEEE Process for the correction has completed.

Using the Repository

The repository is publicly visible and available on the GitHub website YANG Catalog Repository [yang-catalog-repository]. Developers and/or experts that are interested in the IEEE developed YANG modules are encouraged to use the repository for exploration of management solutions related to the IEEE protocols being managed by the YANG. The repository supports the ability to make a copy (clone) the repository. Users can create their own versions of files in their private copy (fork) of the repository. These versions are for the private use of the user and will not become part of any sanctioned IEEE directory of the YANG repository. Users can request that their modifications become part of the IEEE draft, but that request is treated like an IEEE Contribution and would need to be reviewed by the editor and discussed with the working group. Users can also use the repository to submit comments to the Editor on the files in the repository. The comments are treated as contributions to the IEEE and are governed under the IEEE-SA Copyright Policy [ieee-sa-copyright].

Module Naming Conventions

To coordinate the use of the YANG namespace and ensure there are no file naming conflicts, the following guidelines have been put into place. A summary is provided below, a more complete treatment of the syntax can be seen here YANG Module Naming Guidelines [yangsters-module-naming] found on the YANGsters [yangsters] page.

The module name is made up of three parts. The “ieee-committee”, the “ieee-working-group”, and a “unique-name”. For example, a specific IEEE 802.1 name looks like “ieee802-dot1q-bridge.yang”. Where the “ieee-committee” is “ieee802”, the “ieee-working-group” includes both the working group and the base specification “dot1q”, and the “unique-name” is “bridge”. An IEEE 802.3 specific example name looks like “ieee802-dot3-link-oam.yang”. Where the “ieee-committee” is “ieee802”, the “ieee-working-group” is identified by “dot3”, and the “unique-name” in this case is “link-oam”. The naming convention is flexible enough to support other IEEE committees (like IEEE 1588 for example).