diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..acbb7b9ca --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +[Note: Please fill out the following template for your pull request. lines +tagged with "Note" can be removed from the template.] + +[Note: Before this PR can be reviewed please agree to the CLA covering this +repo. Please also review the contribution guide - +https://github.com/openconfig/public/blob/master/doc/external-contributions-guide.md] + +### Change Scope + +* [Please briefly describe the change that is being made to the models.] +* [Please indicate whether this change is backwards compatible.] +### Platform Implementations + + * Implementation A: [link to documentation](http://foo.com) and/or + implementation output. + * Implementation B: [link to documentation](http://foo.com) and/or + implementation output. + +[Note: Please provide at least two references to implementations which are relevant to the model changes proposed. Each implementation should be from separate organizations.]. + +[Note: If the feature being proposed is new - and something that is being +proposed as an enhancement to device functionality, it is sufficient to have +reviewers from the producers of two different implementations]. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e371839a0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,4 @@ +# Contributing to OpenConfig + +Please see the [contributions +guide](https://github.com/openconfig/public/blob/master/doc/contributions-guide.md). diff --git a/doc/external-contributions-guide.md b/doc/contributions-guide.md similarity index 78% rename from doc/external-contributions-guide.md rename to doc/contributions-guide.md index b9a4b4ee9..0d4f7e216 100644 --- a/doc/external-contributions-guide.md +++ b/doc/contributions-guide.md @@ -1,7 +1,8 @@ -# External Submissions to OpenConfig +# Contributions to OpenConfig *Contributors*: robjs†, aashaikh†, chris_luke⸸ † @google.com, ⸸ @comcast.com -May 2018 +Created: May 2018 +Updated: August 2022 ## Rationale As the OpenConfig project matures and is adopted by implementors and network @@ -33,12 +34,12 @@ The process for making a contribution is outlined below. 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](https://github.com/openconfig/public/issues). +public GitHub](https://github.com/openconfig/public/issues). All contributions to OpenConfig MUST be Apache 2.0 licensed. A contributor license agreement (CLA), namely the [Google CLA](https://cla.developers.google.com/), MUST be signed for any contribution -to be accepted. +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 @@ -54,9 +55,10 @@ ascribe any specific rights to a single OpenConfig member. To make a contribution to OpenConfig: 1. Open a pull request in the - [openconfig/public](https://github.com/openconfig/public) repo. A brief - description of the proposed addition along with references to any discussion - issues should be included. + [openconfig/public](https://github.com/openconfig/public) repo. The pull + request template for the repository details the information that is expected, + please fill it out, along with any additional information that is useful for + reviewers. In addition: * 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 @@ -66,10 +68,13 @@ To make a contribution to OpenConfig: 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 author must 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). + * Pull requests should update the versions of the modified models with a new + semantic version, the rules followed for this versioning are described in + [this document](https://openconfig.net/docs/semver/). 1. 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 @@ -90,28 +95,17 @@ To make a contribution to OpenConfig: available YANG toolchains, in order to detect regression issues that may occur due to OpenConfig model changes. -1. 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. +1. Discussion of the PR is carried out in the `openconfig/public` repository - + in order to ensure that different viewpoints can be considered from the + community. Real-time discussions (either scheduled or ad-hoc) can be arranged + where needed. -1. 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](https://github.com/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. +1. When the model changes are approved. The pull request will be + merged in the public repository. 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](mailto:netopenconfig@googlegroups.com), or the [public repository -issues](https://github.com/openconfig/public/issues). - +issues](https://github.com/openconfig/public/issues).