blob: 1eadef459f5f0ff212ca2d61efe98772761617c7 [file] [log] [blame]
Andrea Campanella4dd04222022-03-18 15:52:28 +01001Contributing to VOLTHA
2======================
3
4We'd love to accept your patches and contributions to the VOLTHA project. There are
5just a few small guidelines you need to follow.
6
7Contributor License Agreement
8-----------------------------
9
10Contributions to this project must be accompanied by a Contributor License
11Agreement. You (or your employer) retain the copyright to your contribution,
12this simply gives us permission to use and redistribute your contributions as
13part of the project. Head over to the `ONF CLA <https://cla.opennetworking.org/>`_ to see
14your current agreements on file or to sign a new one.
15
16You generally only need to submit a CLA once, so if you've already submitted one
17(even if it was for a different project), you probably don't need to do it
18again.
19
20Guides, Rules and Best Practices
21--------------------------------
22
23VOLTHA follows `Google's Engineering Practices <https://google.github.io/eng-practices/>`_,
24`Golang Formatting Guide <https://go.dev/doc/effective_go#formatting>`_. Use these documents as a guide when
25writing, submitting or reviewing code.
26VOLTHA uses gerrit to submit, review, tests and finally merge patches.
27
28Submitting Code
29+++++++++++++++
30
31Some additional points for developers:
32
Joey Armstrong3980d702023-08-23 10:57:18 -040033- Submit your changes early and often. Code and design review input
34 with corrections early in the process prevent huge changes later.
35- :doc:`Create a Jira ticket for code changes <contributing/jira_tickets>` (required)
36- :doc:`Update copyright notices <contributing/copyright>`
37- `Commit message <https://docs.voltha.org/master/howto/code/commit-message.html#pull-request-commit-message>`_ and jenkins automation.
38
39 - To enable automation, prefix your commit message with a jira ticket
40
41 - ``[VOL-4550]`` - Spiffy enhancement/feature/problem summary
42
43 - This addition will allow jenkins to magically update tickets
44 with processed job status.
45- :doc:`Request a code review <contributing/code_review>`
Andrea Campanella4dd04222022-03-18 15:52:28 +010046
47Steps to successful PRs
48+++++++++++++++++++++++
49
Joey Armstrongf713d7f2023-02-23 06:06:49 -050050 1. Checkout the code base and prepare your patch.
51 2. Workflow to modify VOLTHA code through gerrit is identical to `onos-classic`
52 and is described in `Sample Gerrit Workflow page <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_
53 3. Before submitting your patch via `git review` please pre-screen your changes to ensure code quality.
Andrea Campanella4dd04222022-03-18 15:52:28 +010054
Joey Armstrongf713d7f2023-02-23 06:06:49 -050055 .. list-table:: Patch Pre-Screening
56 :widths: 10, 40
Andrea Campanella4dd04222022-03-18 15:52:28 +010057
Joey Armstrongf713d7f2023-02-23 06:06:49 -050058 * - Command
59 - Description
60 * - `make lint <https://docs.voltha.org/master/howto/code/linting.html>`_
Joey Armstrong34f18402023-07-21 18:58:10 -040061 - Syntax check source for problems (lint, lint-shelcheck, lint-doc8)
Joey Armstrongf713d7f2023-02-23 06:06:49 -050062 * - make sca
63 - Static Code Analysis
Joey Armstrong34f18402023-07-21 18:58:10 -040064 * - make build
65 - Assemble, compile, generate, link, ...
Joey Armstrongf713d7f2023-02-23 06:06:49 -050066 * - make test
67 - Invoke VOLTHA test suite(s)
68 * - make help
Joey Armstrong34f18402023-07-21 18:58:10 -040069 - Show available targets: make help | grep lint
Andrea Campanella4dd04222022-03-18 15:52:28 +010070
Joey Armstrong34f18402023-07-21 18:58:10 -040071 4. :ref:`Commit message syntax and testing directives <pull-request--commit-message>`
72
73 5. Submitting your patch will initiate a validation
74 `jenkins job <https://jenkins.opencord.org>`_.
Joey Armstrongf713d7f2023-02-23 06:06:49 -050075 Wait for job completion status before proceeding.
76
Joey Armstrong864db882023-08-24 15:01:35 -040077 - Job status will be sent to you asynchronously in email at job completion.
78 - For direct monitoring :doc:`review gerrit Change Log<contributing/patch_followup>` for your patch.
Joey Armstrongf713d7f2023-02-23 06:06:49 -050079
Joey Armstrong864db882023-08-24 15:01:35 -040080 - If testing fails please fix your patch with step 3 then repeat 2 and 3 as needed.
Joey Armstrongf713d7f2023-02-23 06:06:49 -050081
82 **Passing CI verification is mandatory.**
83
Joey Armstrong864db882023-08-24 15:01:35 -040084 To view accumulated job status:
85
86 - `navigate to a patch <https://gerrit.opencord.org/c/ci-management/+/34599>`_
87 - View "Submit requirements" in the top left.
88 - Verified ``+1 Jenkins Technical User`` will indicate SUCCESS.
89 - Verified ``-1 Jenkins Technical User`` will indicate FAILURE.
90
Joey Armstrongf713d7f2023-02-23 06:06:49 -050091 If the CI check does not start or fails and you believe the issue is
92 un-related to a changeset you can re-trigger by commenting on the
Joey Armstrong864db882023-08-24 15:01:35 -040093 patch with `recheck <https://docs.voltha.org/master/howto/code/pull_request.html#development-and-code-reviews>`_
Joey Armstrongf713d7f2023-02-23 06:06:49 -050094
95 If failures persist `ask for assistance <https://wiki.opennetworking.org/display/COM/VOLTHA>`_ in slack or a mailing list.
96
Joey Armstrong864db882023-08-24 15:01:35 -040097 6. When patch comments are offered please make the appropriate fixes and then
Andrea Campanella4dd04222022-03-18 15:52:28 +010098 amend your commit with `git commit --amend` and re-upload to gerrit with `git review`.
99
Joey Armstrong34f18402023-07-21 18:58:10 -0400100 7. Await review. Everyone can comment on code changes, but only Core contributors
Joey Armstrong864db882023-08-24 15:01:35 -0400101 can give final review approval.
102
103 **All changes must acquire +2 Approval**.
104
105 Join one of the `communication channels <https://wiki.opennetworking.org/display/COM/VOLTHA>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100106 to request a review or to bring additional attention to your patch.
107
Joey Armstrong864db882023-08-24 15:01:35 -0400108 8. A patch will be ready to submit a merge request when
109
110 - "Submit requirements" in the top left is showing:
111
112 - Code-Review: +2 approval (or 2 x +1 approval)
113 - Verified ``+1 Jenkins Technical User``
114
Andrea Campanella7dae5ce2022-03-25 16:08:15 +0100115Versioning
116++++++++++
117
118All of the VOLTHA components and the charts include a VERSION file that specifies
119the version of the service, library, protobuf, test suite included in the repository.
Joey Armstrong45fe8052023-06-23 09:51:02 -0400120
121- The `VERSION <https://gerrit.opencord.org/plugins/gitiles/voltha-go/+/refs/heads/master/VERSION>`_ file can be found in a repository root directory.
122- One exception: maven based builds using pom.xml files.
123
Andrea Campanella7dae5ce2022-03-25 16:08:15 +0100124The VERSION is in the format and follows the `SemVer principles <https://semver.org>`_
125VOLTHA also follows the guidelines on how to increment versions as described in the
126`SemVer specification <https://semver.org/#semantic-versioning-specification-semver>`_.
127
128Each increment of the VERSION file in a patch automatically triggers publishing of the repository
129artifact, e.g. docker images, with that tag.
130In VOLTHA we also use a `x.y.z-dev` format which identifies a non-released component (what is `master`).
131When a patch is merged with the `-dev` suffix in the VERSION file no artifact is published except for `master`
132docker images. The `-dev` suffix should be removed when a feature being worked on and the component
133is ready for release.
134
135We expect contributions to the VOLTHA codebase to follow these rules when submitting a patch
136and the same rules to be enforced by reviewers during the core review process.
137
138
Andrea Campanella4dd04222022-03-18 15:52:28 +0100139Core Contributors
140-----------------
141
142Anyone with a Gerrit account can open new issues, comment on existing issues, or
143contribute code by opening a review.
144
145A **“core contributor”** is someone who can manage, approve and
146merge patches, and create new branches in the main repository.
147
148Core contributors are responsible for maintaining the quality of contributions
149to the codebase. The goal of this program is to have a diverse group of
150individuals whose expertise in aggregate covers the entire project.
151
152The benefits of being a core contributor include:
153 - Increased influence of the direction of the project
154 - The ability to create branches in the main repository and after others approve it
155 merge your own code
156 - Community recognition and visibility for their contributions and expertise.
157
158Becoming a Core Contributor
159+++++++++++++++++++++++++++
160
161Core contributor candidates need to have a demonstrated proficiency with the
162VOLTHA codebase and a track record of code reviews. Members of the Technical
163Steering Team (TST) and existing core contributors will regularly invite people
164to become new core contributors. Nominations can also be made (including
165self-nominations) to the VOLTHA TST (`voltha-tst@opennetworking.org`) at any time.
166
167A good nomination will include details about who the person is (including their email
168and Github and/or Gerrit username) and outline their experience with the VOLTHA codebase
169and project at large.
170Nominations are intended to start a conversation that results in a decision to
171make the person a core contributor anyone whose nomination is not initially
172approved is encouraged to gain more experience with code submission and code
173review in order to gain further mastery over the codebase. Partial approval is
174also possible (e.g. a person may be granted the ability to handles patches only
175on a certain repository), and full approval may be granted after the contributor
176has gained more experience.
177
178New core contributors will be assigned a mentor that is either a TST member or
179existing core contributor. The mentor will serve as the primary point of contact
180to help onboard the new core contributors and answer any questions they have
181with their new responsibilities. The mentor is not the only point of contact,
182and core contributors should feel free to reach out to others if and when they
183have questions or concerns.
184
185Guidelines for Core Contributors
186++++++++++++++++++++++++++++++++
187
188Contributions in VOLTHA can should be merged after two different +1 arrive on a
189given patch-set that is verified by CI as well.
190For your own contributions, you now have the ability to approve and merge your
191own code, pending that you received two other positive reviews.
192For larger or potentially controversial reviews, please give the
193community an opportunity (at least a few business days) to review your
194contribution. Please always ask for comments on the #voltha-dev Slack channel.
195**With great power comes great responsibility; please don't abuse
196this privilege.**
197
198All Core Contributors have +2 and merge capabilities on all the repositories related
199to the VOLTHA project, but we expect that they are responsible and exercise their
200privilege **only** on patches and repositories they have expertise in and are comfortable reviewing and merging.
201
202To help patchset verification the VOLTHA test infrastructure offers Per-Patchset Verification Jobs
203triggered by specific keyword used in the patch. More information can be found in the
204`testing automation page <https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_
205We suggest Core contributors to use these triggers when they would like more checks on a patch they are uncertain about
206or that might have differences when applied to hardware pods.
207
208VOLTHA follows `Google’s best practices for code review <https://google.github.io/eng-practices/review/reviewer/>`_.
209You should apply these guidelines strictly and with confidence when reviewing
210submissions.
211
212If you are unsure about something in an issue or a review, leave a comment
213that outlines your concerns. If a resolution is difficult to reach in the
214comments section, the TST meetings are a good place to raise your concerns and
215have a discussion.
216
217Current Core Contributors
218+++++++++++++++++++++++++++
219
220This is a list of core contributors divided by area of expertise:
221
222Adapter openonu and omci-lib-go:
223
Andrea Campanella4dd04222022-03-18 15:52:28 +0100224 - `Chip Boling <chip.boling@tibitcom.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100225 - `Ozge Ayaz <ozge.ayaz@netsia.com>`_
226
227Voltha-system-tests:
228
TorstenThieme47e59db2023-05-31 08:29:47 +0000229 - to be assigned
Andrea Campanella4dd04222022-03-18 15:52:28 +0100230
231Openolt agent:
232
233 - `Thiyagarajan Subramani <Thiyagarajan.Subramani@radisys.com>`_
234 - `Burak Gurdag <burak.gurdag@netsia.com>`_
235
236ONOS apps:
237
238 - `Gamze Abaka <gamze.abaka@netsia.com>`_
239 - `Yasin Sapli <yasin.sapli@netsia.com>`_
240 - `Tunahan Sezen <tunahan.sezen@netsia.com>`_
241
242Olt adapter, rw-core:
243
244 - `Abhilash Satish Laxmeshwar <abhilash.laxmeshwar@radisys.com>`_
245 - `Gamze Abaka <gamze.abaka@netsia.com>`_
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500246
247Build system, makefiles, reviews:
248
249 - `Joey Armstrong <joey@opennetworking.org>`_
250 - `David Ferguson <daf@opennetworking.org>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100251
252All of the codebase:
253
Andrea Campanella4dd04222022-03-18 15:52:28 +0100254 - `Mahir Gunyel <mahir.gunyel@netsia.com>`_
255 - `Serkant Uluderya <serkant.uluderya@netsia.com>`_
256 - `Amit Ghosh <Amit.Ghosh@radisys.com>`_
Joey Armstrongae15c262023-03-29 15:36:28 -0400257 - `Suhas Gururaj Rao <suhas.gururaj@radisys.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100258
Andrea Campanella4dd04222022-03-18 15:52:28 +0100259Community Guidelines
260--------------------
261
Joey Armstronga4d27232022-12-29 08:50:02 -0500262This project follows `Google's Open Source Community Guidelines <https://opensource.google/conduct/>`_
263
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500264and ONF's `Code of Conduct <https://opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf>`_.