blob: f774e18a4dd6ae8dd8ea4afa63a6d26f4749e24c [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 Armstrongf713d7f2023-02-23 06:06:49 -050033 - Submit your changes early and often. Code and design review input
34 with corrections early in the process prevent huge changes later.
35 - Please open a `jira ticket <https://jira.opencord.org/projects/VOL>`_ describing the issue/feature.
36 - While checking in changes please preface the commit message with
37 `[VOL-<jira_number]` e.g. `[VOL-4550]` to automatically link changesets,
38 jenkins jobs, etc making them self-documenting for discussions.
Andrea Campanella4dd04222022-03-18 15:52:28 +010039
40Steps to successful PRs
41+++++++++++++++++++++++
42
Joey Armstrongf713d7f2023-02-23 06:06:49 -050043 1. Checkout the code base and prepare your patch.
44 2. Workflow to modify VOLTHA code through gerrit is identical to `onos-classic`
45 and is described in `Sample Gerrit Workflow page <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_
46 3. Before submitting your patch via `git review` please pre-screen your changes to ensure code quality.
Andrea Campanella4dd04222022-03-18 15:52:28 +010047
Joey Armstrongf713d7f2023-02-23 06:06:49 -050048 .. list-table:: Patch Pre-Screening
49 :widths: 10, 40
Andrea Campanella4dd04222022-03-18 15:52:28 +010050
Joey Armstrongf713d7f2023-02-23 06:06:49 -050051 * - Command
52 - Description
53 * - `make lint <https://docs.voltha.org/master/howto/code/linting.html>`_
54 - Syntax check source for problems
55 * - make sca
56 - Static Code Analysis
57 * - make test
58 - Invoke VOLTHA test suite(s)
59 * - make help
60 - Show available targets, bulk source cleanup needed for `make lint` to check everything by default.
Andrea Campanella4dd04222022-03-18 15:52:28 +010061
Joey Armstrongf713d7f2023-02-23 06:06:49 -050062 4. Submitting your patch will initiate a `jenkins job <https://jenkins.opencord.org>`_ to validate changes.
63 Wait for job completion status before proceeding.
64
65 - Job completion status will be sent to you asynchronously in email.
66 - For direct monitoring `review comment history for your patch <https://gerrit.opencord.org/q/status:open+-is:wip>`_.
67 - Search for `Jenkins Technical User <https://gerrit.opencord.org/c/voltha-docs/+/33952>`_ and click a job entry.
68 - In the top grey navigation bar, following "Dashboard", click the test suite name to view the active job dashboard history `verify_voltha-docs_unit-test <https://jenkins.opencord.org/job/verify_voltha-docs_unit-test/>`_.
69
70 If testing fails please fix your patch with step 3 an then repeat 2 and 3, as necessary.
71
72 **Passing CI verification is mandatory.**
73
74 If the CI check does not start or fails and you believe the issue is
75 un-related to a changeset you can re-trigger by commenting on the
76 patch with `recheck`.
77
78 If failures persist `ask for assistance <https://wiki.opennetworking.org/display/COM/VOLTHA>`_ in slack or a mailing list.
79
80 5. When comments are made to your patch please make the appropriate fixes and then
Andrea Campanella4dd04222022-03-18 15:52:28 +010081 amend your commit with `git commit --amend` and re-upload to gerrit with `git review`.
82
Joey Armstrongf713d7f2023-02-23 06:06:49 -050083 6. Await review. Everyone can comment on code changes, but only Core contributors
Andrea Campanella4dd04222022-03-18 15:52:28 +010084 can give final review approval. **All changes must get at least one
85 approval**. Join one of the `communication channels <https://wiki.opennetworking.org/display/COM/VOLTHA>`_
86 to request a review or to bring additional attention to your patch.
87
Andrea Campanella7dae5ce2022-03-25 16:08:15 +010088Versioning
89++++++++++
90
91All of the VOLTHA components and the charts include a VERSION file that specifies
92the version of the service, library, protobuf, test suite included in the repository.
Joey Armstrong45fe8052023-06-23 09:51:02 -040093
94- The `VERSION <https://gerrit.opencord.org/plugins/gitiles/voltha-go/+/refs/heads/master/VERSION>`_ file can be found in a repository root directory.
95- One exception: maven based builds using pom.xml files.
96
Andrea Campanella7dae5ce2022-03-25 16:08:15 +010097The VERSION is in the format and follows the `SemVer principles <https://semver.org>`_
98VOLTHA also follows the guidelines on how to increment versions as described in the
99`SemVer specification <https://semver.org/#semantic-versioning-specification-semver>`_.
100
101Each increment of the VERSION file in a patch automatically triggers publishing of the repository
102artifact, e.g. docker images, with that tag.
103In VOLTHA we also use a `x.y.z-dev` format which identifies a non-released component (what is `master`).
104When a patch is merged with the `-dev` suffix in the VERSION file no artifact is published except for `master`
105docker images. The `-dev` suffix should be removed when a feature being worked on and the component
106is ready for release.
107
108We expect contributions to the VOLTHA codebase to follow these rules when submitting a patch
109and the same rules to be enforced by reviewers during the core review process.
110
111
Andrea Campanella4dd04222022-03-18 15:52:28 +0100112Core Contributors
113-----------------
114
115Anyone with a Gerrit account can open new issues, comment on existing issues, or
116contribute code by opening a review.
117
118A **“core contributor”** is someone who can manage, approve and
119merge patches, and create new branches in the main repository.
120
121Core contributors are responsible for maintaining the quality of contributions
122to the codebase. The goal of this program is to have a diverse group of
123individuals whose expertise in aggregate covers the entire project.
124
125The benefits of being a core contributor include:
126 - Increased influence of the direction of the project
127 - The ability to create branches in the main repository and after others approve it
128 merge your own code
129 - Community recognition and visibility for their contributions and expertise.
130
131Becoming a Core Contributor
132+++++++++++++++++++++++++++
133
134Core contributor candidates need to have a demonstrated proficiency with the
135VOLTHA codebase and a track record of code reviews. Members of the Technical
136Steering Team (TST) and existing core contributors will regularly invite people
137to become new core contributors. Nominations can also be made (including
138self-nominations) to the VOLTHA TST (`voltha-tst@opennetworking.org`) at any time.
139
140A good nomination will include details about who the person is (including their email
141and Github and/or Gerrit username) and outline their experience with the VOLTHA codebase
142and project at large.
143Nominations are intended to start a conversation that results in a decision to
144make the person a core contributor anyone whose nomination is not initially
145approved is encouraged to gain more experience with code submission and code
146review in order to gain further mastery over the codebase. Partial approval is
147also possible (e.g. a person may be granted the ability to handles patches only
148on a certain repository), and full approval may be granted after the contributor
149has gained more experience.
150
151New core contributors will be assigned a mentor that is either a TST member or
152existing core contributor. The mentor will serve as the primary point of contact
153to help onboard the new core contributors and answer any questions they have
154with their new responsibilities. The mentor is not the only point of contact,
155and core contributors should feel free to reach out to others if and when they
156have questions or concerns.
157
158Guidelines for Core Contributors
159++++++++++++++++++++++++++++++++
160
161Contributions in VOLTHA can should be merged after two different +1 arrive on a
162given patch-set that is verified by CI as well.
163For your own contributions, you now have the ability to approve and merge your
164own code, pending that you received two other positive reviews.
165For larger or potentially controversial reviews, please give the
166community an opportunity (at least a few business days) to review your
167contribution. Please always ask for comments on the #voltha-dev Slack channel.
168**With great power comes great responsibility; please don't abuse
169this privilege.**
170
171All Core Contributors have +2 and merge capabilities on all the repositories related
172to the VOLTHA project, but we expect that they are responsible and exercise their
173privilege **only** on patches and repositories they have expertise in and are comfortable reviewing and merging.
174
175To help patchset verification the VOLTHA test infrastructure offers Per-Patchset Verification Jobs
176triggered by specific keyword used in the patch. More information can be found in the
177`testing automation page <https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_
178We suggest Core contributors to use these triggers when they would like more checks on a patch they are uncertain about
179or that might have differences when applied to hardware pods.
180
181VOLTHA follows `Google’s best practices for code review <https://google.github.io/eng-practices/review/reviewer/>`_.
182You should apply these guidelines strictly and with confidence when reviewing
183submissions.
184
185If you are unsure about something in an issue or a review, leave a comment
186that outlines your concerns. If a resolution is difficult to reach in the
187comments section, the TST meetings are a good place to raise your concerns and
188have a discussion.
189
190Current Core Contributors
191+++++++++++++++++++++++++++
192
193This is a list of core contributors divided by area of expertise:
194
195Adapter openonu and omci-lib-go:
196
Andrea Campanella4dd04222022-03-18 15:52:28 +0100197 - `Chip Boling <chip.boling@tibitcom.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100198 - `Ozge Ayaz <ozge.ayaz@netsia.com>`_
199
200Voltha-system-tests:
201
TorstenThieme47e59db2023-05-31 08:29:47 +0000202 - to be assigned
Andrea Campanella4dd04222022-03-18 15:52:28 +0100203
204Openolt agent:
205
206 - `Thiyagarajan Subramani <Thiyagarajan.Subramani@radisys.com>`_
207 - `Burak Gurdag <burak.gurdag@netsia.com>`_
208
209ONOS apps:
210
211 - `Gamze Abaka <gamze.abaka@netsia.com>`_
212 - `Yasin Sapli <yasin.sapli@netsia.com>`_
213 - `Tunahan Sezen <tunahan.sezen@netsia.com>`_
214
215Olt adapter, rw-core:
216
217 - `Abhilash Satish Laxmeshwar <abhilash.laxmeshwar@radisys.com>`_
218 - `Gamze Abaka <gamze.abaka@netsia.com>`_
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500219
220Build system, makefiles, reviews:
221
222 - `Joey Armstrong <joey@opennetworking.org>`_
223 - `David Ferguson <daf@opennetworking.org>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100224
225All of the codebase:
226
Andrea Campanella4dd04222022-03-18 15:52:28 +0100227 - `Mahir Gunyel <mahir.gunyel@netsia.com>`_
228 - `Serkant Uluderya <serkant.uluderya@netsia.com>`_
229 - `Amit Ghosh <Amit.Ghosh@radisys.com>`_
Joey Armstrongae15c262023-03-29 15:36:28 -0400230 - `Suhas Gururaj Rao <suhas.gururaj@radisys.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100231
Andrea Campanella4dd04222022-03-18 15:52:28 +0100232Community Guidelines
233--------------------
234
Joey Armstronga4d27232022-12-29 08:50:02 -0500235This project follows `Google's Open Source Community Guidelines <https://opensource.google/conduct/>`_
236
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500237and ONF's `Code of Conduct <https://opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf>`_.