blob: 019f1da93d6d0a63c60175690496acebf87c8b7d [file] [log] [blame]
Andrea Campanella4dd04222022-03-18 15:52:28 +01001======================
2Contributing to VOLTHA
3======================
4
5We'd love to accept your patches and contributions to the VOLTHA project. There are
6just a few small guidelines you need to follow.
7
8Contributor License Agreement
9-----------------------------
10
11Contributions to this project must be accompanied by a Contributor License
12Agreement. You (or your employer) retain the copyright to your contribution,
13this simply gives us permission to use and redistribute your contributions as
14part of the project. Head over to the `ONF CLA <https://cla.opennetworking.org/>`_ to see
15your current agreements on file or to sign a new one.
16
17You generally only need to submit a CLA once, so if you've already submitted one
18(even if it was for a different project), you probably don't need to do it
19again.
20
21Guides, Rules and Best Practices
22--------------------------------
23
24VOLTHA follows `Google's Engineering Practices <https://google.github.io/eng-practices/>`_,
25`Golang Formatting Guide <https://go.dev/doc/effective_go#formatting>`_. Use these documents as a guide when
26writing, submitting or reviewing code.
27VOLTHA uses gerrit to submit, review, tests and finally merge patches.
28
29Submitting Code
30+++++++++++++++
31
32Some additional points for developers:
33
34 - Submit your changes early and often. Input and
35 corrections early in the process prevent huge changes later.
36
Joey Armstronga62c74a2022-11-23 13:16:34 -050037 - Please open a `jira ticket <https://jira.opencord.org/projects/VOL>`_ describing the issue/feature. During the patch please
Andrea Campanella4dd04222022-03-18 15:52:28 +010038 preface the commit message with `[VOL-<jira_number]` e.g. `[VOL-4550]` so it gets
39 automatically linked to the Jira ticket. This keeps code review and design discussions clean.
40
41Steps to successful PRs
42+++++++++++++++++++++++
43
44 1. Checkout the code and prepare your patch. The workflow to make changes to the VOLTHA code through gerrit is identical
45 to the one from `onos-classic` and is described in the
46 `Sample Gerrit Workflow page <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_
47
48 2. Before submitting the patch via `git review` please execute VOLTHA specific tests:
49 `make test` and `make sca`. These commands run unit test, linting and other elements
50 to assure the quality of your patch.
51
52 3. Wait for sanity checks `jenkins <https://jenkins.opencord.org>`_ to pass.
53 If the tests fail please fix your patch with step 3 an then repeat 2 and 3, as necessary.
54 **Passing CI verification is mandatory.** If the CI check does not start or fails but you think the issue
55 is un-related you can re-trigger by commenting on to the patch with `recheck`.
56
57 4. When comments are made to your patch please make the appropriate fixes and then
58 amend your commit with `git commit --amend` and re-upload to gerrit with `git review`.
59
60 5. Await review. Everyone can comment on code changes, but only Core contributors
61 can give final review approval. **All changes must get at least one
62 approval**. Join one of the `communication channels <https://wiki.opennetworking.org/display/COM/VOLTHA>`_
63 to request a review or to bring additional attention to your patch.
64
Andrea Campanella7dae5ce2022-03-25 16:08:15 +010065Versioning
66++++++++++
67
68All of the VOLTHA components and the charts include a VERSION file that specifies
69the version of the service, library, protobuf, test suite included in the repository.
70The VERSION is in the format and follows the `SemVer principles <https://semver.org>`_
71VOLTHA also follows the guidelines on how to increment versions as described in the
72`SemVer specification <https://semver.org/#semantic-versioning-specification-semver>`_.
73
74Each increment of the VERSION file in a patch automatically triggers publishing of the repository
75artifact, e.g. docker images, with that tag.
76In VOLTHA we also use a `x.y.z-dev` format which identifies a non-released component (what is `master`).
77When a patch is merged with the `-dev` suffix in the VERSION file no artifact is published except for `master`
78docker images. The `-dev` suffix should be removed when a feature being worked on and the component
79is ready for release.
80
81We expect contributions to the VOLTHA codebase to follow these rules when submitting a patch
82and the same rules to be enforced by reviewers during the core review process.
83
84
Andrea Campanella4dd04222022-03-18 15:52:28 +010085Core Contributors
86-----------------
87
88Anyone with a Gerrit account can open new issues, comment on existing issues, or
89contribute code by opening a review.
90
91A **“core contributor”** is someone who can manage, approve and
92merge patches, and create new branches in the main repository.
93
94Core contributors are responsible for maintaining the quality of contributions
95to the codebase. The goal of this program is to have a diverse group of
96individuals whose expertise in aggregate covers the entire project.
97
98The benefits of being a core contributor include:
99 - Increased influence of the direction of the project
100 - The ability to create branches in the main repository and after others approve it
101 merge your own code
102 - Community recognition and visibility for their contributions and expertise.
103
104Becoming a Core Contributor
105+++++++++++++++++++++++++++
106
107Core contributor candidates need to have a demonstrated proficiency with the
108VOLTHA codebase and a track record of code reviews. Members of the Technical
109Steering Team (TST) and existing core contributors will regularly invite people
110to become new core contributors. Nominations can also be made (including
111self-nominations) to the VOLTHA TST (`voltha-tst@opennetworking.org`) at any time.
112
113A good nomination will include details about who the person is (including their email
114and Github and/or Gerrit username) and outline their experience with the VOLTHA codebase
115and project at large.
116Nominations are intended to start a conversation that results in a decision to
117make the person a core contributor – anyone whose nomination is not initially
118approved is encouraged to gain more experience with code submission and code
119review in order to gain further mastery over the codebase. Partial approval is
120also possible (e.g. a person may be granted the ability to handles patches only
121on a certain repository), and full approval may be granted after the contributor
122has gained more experience.
123
124New core contributors will be assigned a mentor that is either a TST member or
125existing core contributor. The mentor will serve as the primary point of contact
126to help onboard the new core contributors and answer any questions they have
127with their new responsibilities. The mentor is not the only point of contact,
128and core contributors should feel free to reach out to others if and when they
129have questions or concerns.
130
131Guidelines for Core Contributors
132++++++++++++++++++++++++++++++++
133
134Contributions in VOLTHA can should be merged after two different +1 arrive on a
135given patch-set that is verified by CI as well.
136For your own contributions, you now have the ability to approve and merge your
137own code, pending that you received two other positive reviews.
138For larger or potentially controversial reviews, please give the
139community an opportunity (at least a few business days) to review your
140contribution. Please always ask for comments on the #voltha-dev Slack channel.
141**With great power comes great responsibility; please don't abuse
142this privilege.**
143
144All Core Contributors have +2 and merge capabilities on all the repositories related
145to the VOLTHA project, but we expect that they are responsible and exercise their
146privilege **only** on patches and repositories they have expertise in and are comfortable reviewing and merging.
147
148To help patchset verification the VOLTHA test infrastructure offers Per-Patchset Verification Jobs
149triggered by specific keyword used in the patch. More information can be found in the
150`testing automation page <https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_
151We suggest Core contributors to use these triggers when they would like more checks on a patch they are uncertain about
152or that might have differences when applied to hardware pods.
153
154VOLTHA follows `Google’s best practices for code review <https://google.github.io/eng-practices/review/reviewer/>`_.
155You should apply these guidelines strictly and with confidence when reviewing
156submissions.
157
158If you are unsure about something in an issue or a review, leave a comment
159that outlines your concerns. If a resolution is difficult to reach in the
160comments section, the TST meetings are a good place to raise your concerns and
161have a discussion.
162
163Current Core Contributors
164+++++++++++++++++++++++++++
165
166This is a list of core contributors divided by area of expertise:
167
168Adapter openonu and omci-lib-go:
169
170 - `Holger Hildebrandt <holger.hildebrandt@adtran.com>`_
171 - `Chip Boling <chip.boling@tibitcom.com>`_
172 - `Michael Pagenkopf <michael.pagenkopf@adtran.com>`_
173 - `Ozge Ayaz <ozge.ayaz@netsia.com>`_
174
175Voltha-system-tests:
176
177 - `Torsten Thieme <torsten.thieme@adtran.com>`_
178
179Openolt agent:
180
181 - `Thiyagarajan Subramani <Thiyagarajan.Subramani@radisys.com>`_
182 - `Burak Gurdag <burak.gurdag@netsia.com>`_
183
184ONOS apps:
185
186 - `Gamze Abaka <gamze.abaka@netsia.com>`_
187 - `Yasin Sapli <yasin.sapli@netsia.com>`_
188 - `Tunahan Sezen <tunahan.sezen@netsia.com>`_
189
190Olt adapter, rw-core:
191
192 - `Abhilash Satish Laxmeshwar <abhilash.laxmeshwar@radisys.com>`_
193 - `Gamze Abaka <gamze.abaka@netsia.com>`_
194
195All of the codebase:
196
197 - `Andrea Campanella <andrea@opennetworking.org>`_
198 - `Matteo Scandolo <teo@opennetworking.org>`_
199 - `Girish Gowdra <girish@opennetworking.org>`_
200 - `Hardik Windlass <hardik@opennetworking.org>`_
201 - `Suchitra Vemuri <suchitra@opennetworking.org>`_
202 - `Saurav Das <saurav.das@opennetworking.org>`_
203 - `Mahir Gunyel <mahir.gunyel@netsia.com>`_
204 - `Serkant Uluderya <serkant.uluderya@netsia.com>`_
205 - `Amit Ghosh <Amit.Ghosh@radisys.com>`_
206 - `Khenaidoo Nursimulu <knursimu@ciena.com>`_
207 - `David Bainbridge <dbainbri.ciena@gmail.com>`_
208
Andrea Campanella4dd04222022-03-18 15:52:28 +0100209Community Guidelines
210--------------------
211
Joey Armstronga4d27232022-12-29 08:50:02 -0500212This project follows `Google's Open Source Community Guidelines <https://opensource.google/conduct/>`_
213
Andrea Campanella4dd04222022-03-18 15:52:28 +0100214and ONF's [Code of Conduct](CODE_OF_CONDUCT.md).