Skip to content

Latest commit

 

History

History
117 lines (101 loc) · 6.72 KB

external-contributions-guide.md

File metadata and controls

117 lines (101 loc) · 6.72 KB
Raw

External Submissions to OpenConfig

Contributors: robjs†, aashaikh†, chris_luke⸸
† @google.com, ⸸ @comcast.com
May 2018

Rationale

As the OpenConfig project matures and is adopted by implementors and network operators, an increasing number of vendors and open source projects have augmented the models with additional fields that have not fallen into the initial "minimum operationally viable" approach that OpenConfig has taken. However, this is not to say that these features are not used, or are not of interest for including in the models. It is desirable that these augmentations

  • where they meet the style, and support requirements for including in the models - be included within the standard set of models, rather than have many different augmentations covering the same feature set. To this end, this document outlines a process for external contributions to OpenConfig.

OpenConfig considers schema consistency paramount -- since it greatly impacts the usability of the models for consumers be they machine or human. As external contributions are accepted into the OpenConfig working group, the intent is to maintain the vendor-neutral, operationally-focused modelling approach taken thus far. In order that these requirements are met, external model changes will still be reviewed and approved by the core operator group before being merged into the schema. It should be noted that it is explicitly required that two vendors have implemented a particular feature before a feature is considered for inclusion in OpenConfig -- features that do not meet this requirement should continue to use vendor-specific augmentations to the schema.

The process for making a contribution is outlined below.

Contributing to OpenConfig

OpenConfig prefers code (i.e., YANG) contributions, rather than feature requests. If you wish to discuss the suitability or approach for a change, or addition to the models, this can be done with an issue in the OpenConfig public GitHub.

All contributions to OpenConfig MUST be Apache 2.0 licensed. A contributor license agreement (CLA), namely the Google CLA, MUST be signed for any contribution to be accepted.

The CLA is used to ensure that the rights to use the contribution are well understood by the OpenConfig working group, and consumers of the OpenConfig models. Since copyright over each contribution is assigned to its authors, code comments or the description field of a YANG model should reflect the contribution made, and the copyright holder. No code will be reviewed if the license is not explicitly stated, or the CLA has not been signed.

Note that we use the Google CLA because the OpenConfig project is administered and maintained by Google, not to ascribe any specific rights to a single OpenConfig member.

To make a contribution to OpenConfig:

  1. Open a pull request in the openconfig/public repo. A brief description of the proposed addition along with references to any discussion issues should be included.

    • Pull requests should be kept small. An ideal change is less than 500 lines of YANG. Small changes allow detailed discussions of the additions that are being made to the model, whilst also ensuring that course-corrections can be made early in the process. In some cases, changes larger than 500 lines may be unavoidable - these should be rare, and generally only be the case when entirely new modules are being added to the model. In this case, it is very likely an issue should have been created to discuss the addition prior to code review.
    • When the pull request adds a new feature that is supported across vendors, best practice is to include links to public-facing documentation showing the implementation of the feature within the change description. This simplifies the process of reviewing differences and the chosen abstractions (if any are used).

  2. The pull request should include both the suggested YANG additions, as well as any relevant changes to the .spec.yml files that are included within the repo. In general, where new content is being added to existing files - no change to the build specification should be required. In the case that new files are being added, new files should be added to the relevant stanza of an existing rule, or entirely new stanzas should be added.

  3. The automated CI running against each pull request will lint the pull request against the OpenConfig style guide rules. An example of the output of the linter can be found here. The list of style rules that are enforced are found in this pyang plugin. The linter can be run locally by installing the openconfig_pyang package from PyPi. Automated CI also runs a small number of integration tests with publicly available YANG toolchains, in order to detect regression issues that may occur due to OpenConfig model changes.

  4. A member of the OpenConfig operator working group will be assigned as a shepherd for the pull request. The shepherd will act as a liasion between the author(s) of the PR and the OpenConfig group - particularly, they will perform an initial review of the submission, provide feedback from the wider operator group on the PR, or directly interact with the authors to iterate on the proposal. The working group meets weekly and, in some cases, may ask the authors to join this meeting for a discussion of the changes.

  5. When the model changes are approved. The pull request will not be directly merged in the public repository, but merged in a private development repo. Members of the OpenConfig group have access to the private repo, and may make subsequent changes to the accepted pull request. Merged changes will be upstreamed from the private repo to openconfig/public periodically. This helps keep the release history well defined within the public repository, and to maintain consistency over changes that require major revision number changes.

The aim of this process is not to restrict contributions to OpenConfig, but simply to maintain the model quality and approach that the working group has strived for since its inception in 2014. Questions prior to making submissions are welcome, please use the netopenconfig Google group, or the public repository issues.