blob: a02a332ea51a9095d5ac390b5cea3e6d0552f63d [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
37 - Please open a ticket in the opencord jira describing the issue/feature. During the patch please
38 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
65Core Contributors
66-----------------
67
68Anyone with a Gerrit account can open new issues, comment on existing issues, or
69contribute code by opening a review.
70
71A **“core contributor”** is someone who can manage, approve and
72merge patches, and create new branches in the main repository.
73
74Core contributors are responsible for maintaining the quality of contributions
75to the codebase. The goal of this program is to have a diverse group of
76individuals whose expertise in aggregate covers the entire project.
77
78The benefits of being a core contributor include:
79 - Increased influence of the direction of the project
80 - The ability to create branches in the main repository and after others approve it
81 merge your own code
82 - Community recognition and visibility for their contributions and expertise.
83
84Becoming a Core Contributor
85+++++++++++++++++++++++++++
86
87Core contributor candidates need to have a demonstrated proficiency with the
88VOLTHA codebase and a track record of code reviews. Members of the Technical
89Steering Team (TST) and existing core contributors will regularly invite people
90to become new core contributors. Nominations can also be made (including
91self-nominations) to the VOLTHA TST (`voltha-tst@opennetworking.org`) at any time.
92
93A good nomination will include details about who the person is (including their email
94and Github and/or Gerrit username) and outline their experience with the VOLTHA codebase
95and project at large.
96Nominations are intended to start a conversation that results in a decision to
97make the person a core contributor – anyone whose nomination is not initially
98approved is encouraged to gain more experience with code submission and code
99review in order to gain further mastery over the codebase. Partial approval is
100also possible (e.g. a person may be granted the ability to handles patches only
101on a certain repository), and full approval may be granted after the contributor
102has gained more experience.
103
104New core contributors will be assigned a mentor that is either a TST member or
105existing core contributor. The mentor will serve as the primary point of contact
106to help onboard the new core contributors and answer any questions they have
107with their new responsibilities. The mentor is not the only point of contact,
108and core contributors should feel free to reach out to others if and when they
109have questions or concerns.
110
111Guidelines for Core Contributors
112++++++++++++++++++++++++++++++++
113
114Contributions in VOLTHA can should be merged after two different +1 arrive on a
115given patch-set that is verified by CI as well.
116For your own contributions, you now have the ability to approve and merge your
117own code, pending that you received two other positive reviews.
118For larger or potentially controversial reviews, please give the
119community an opportunity (at least a few business days) to review your
120contribution. Please always ask for comments on the #voltha-dev Slack channel.
121**With great power comes great responsibility; please don't abuse
122this privilege.**
123
124All Core Contributors have +2 and merge capabilities on all the repositories related
125to the VOLTHA project, but we expect that they are responsible and exercise their
126privilege **only** on patches and repositories they have expertise in and are comfortable reviewing and merging.
127
128To help patchset verification the VOLTHA test infrastructure offers Per-Patchset Verification Jobs
129triggered by specific keyword used in the patch. More information can be found in the
130`testing automation page <https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_
131We suggest Core contributors to use these triggers when they would like more checks on a patch they are uncertain about
132or that might have differences when applied to hardware pods.
133
134VOLTHA follows `Google’s best practices for code review <https://google.github.io/eng-practices/review/reviewer/>`_.
135You should apply these guidelines strictly and with confidence when reviewing
136submissions.
137
138If you are unsure about something in an issue or a review, leave a comment
139that outlines your concerns. If a resolution is difficult to reach in the
140comments section, the TST meetings are a good place to raise your concerns and
141have a discussion.
142
143Current Core Contributors
144+++++++++++++++++++++++++++
145
146This is a list of core contributors divided by area of expertise:
147
148Adapter openonu and omci-lib-go:
149
150 - `Holger Hildebrandt <holger.hildebrandt@adtran.com>`_
151 - `Chip Boling <chip.boling@tibitcom.com>`_
152 - `Michael Pagenkopf <michael.pagenkopf@adtran.com>`_
153 - `Ozge Ayaz <ozge.ayaz@netsia.com>`_
154
155Voltha-system-tests:
156
157 - `Torsten Thieme <torsten.thieme@adtran.com>`_
158
159Openolt agent:
160
161 - `Thiyagarajan Subramani <Thiyagarajan.Subramani@radisys.com>`_
162 - `Burak Gurdag <burak.gurdag@netsia.com>`_
163
164ONOS apps:
165
166 - `Gamze Abaka <gamze.abaka@netsia.com>`_
167 - `Yasin Sapli <yasin.sapli@netsia.com>`_
168 - `Tunahan Sezen <tunahan.sezen@netsia.com>`_
169
170Olt adapter, rw-core:
171
172 - `Abhilash Satish Laxmeshwar <abhilash.laxmeshwar@radisys.com>`_
173 - `Gamze Abaka <gamze.abaka@netsia.com>`_
174
175All of the codebase:
176
177 - `Andrea Campanella <andrea@opennetworking.org>`_
178 - `Matteo Scandolo <teo@opennetworking.org>`_
179 - `Girish Gowdra <girish@opennetworking.org>`_
180 - `Hardik Windlass <hardik@opennetworking.org>`_
181 - `Suchitra Vemuri <suchitra@opennetworking.org>`_
182 - `Saurav Das <saurav.das@opennetworking.org>`_
183 - `Mahir Gunyel <mahir.gunyel@netsia.com>`_
184 - `Serkant Uluderya <serkant.uluderya@netsia.com>`_
185 - `Amit Ghosh <Amit.Ghosh@radisys.com>`_
186 - `Khenaidoo Nursimulu <knursimu@ciena.com>`_
187 - `David Bainbridge <dbainbri.ciena@gmail.com>`_
188
189
190Community Guidelines
191--------------------
192
193This project follows `Google's Open Source Community Guidelines <https://opensource.google.com/conduct/>`_
194and ONF's [Code of Conduct](CODE_OF_CONDUCT.md).