blob: dba3b8e7f5eb867a680485d78453d5a6a136334f [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.
93The VERSION is in the format and follows the `SemVer principles <https://semver.org>`_
94VOLTHA also follows the guidelines on how to increment versions as described in the
95`SemVer specification <https://semver.org/#semantic-versioning-specification-semver>`_.
96
97Each increment of the VERSION file in a patch automatically triggers publishing of the repository
98artifact, e.g. docker images, with that tag.
99In VOLTHA we also use a `x.y.z-dev` format which identifies a non-released component (what is `master`).
100When a patch is merged with the `-dev` suffix in the VERSION file no artifact is published except for `master`
101docker images. The `-dev` suffix should be removed when a feature being worked on and the component
102is ready for release.
103
104We expect contributions to the VOLTHA codebase to follow these rules when submitting a patch
105and the same rules to be enforced by reviewers during the core review process.
106
107
Andrea Campanella4dd04222022-03-18 15:52:28 +0100108Core Contributors
109-----------------
110
111Anyone with a Gerrit account can open new issues, comment on existing issues, or
112contribute code by opening a review.
113
114A **“core contributor”** is someone who can manage, approve and
115merge patches, and create new branches in the main repository.
116
117Core contributors are responsible for maintaining the quality of contributions
118to the codebase. The goal of this program is to have a diverse group of
119individuals whose expertise in aggregate covers the entire project.
120
121The benefits of being a core contributor include:
122 - Increased influence of the direction of the project
123 - The ability to create branches in the main repository and after others approve it
124 merge your own code
125 - Community recognition and visibility for their contributions and expertise.
126
127Becoming a Core Contributor
128+++++++++++++++++++++++++++
129
130Core contributor candidates need to have a demonstrated proficiency with the
131VOLTHA codebase and a track record of code reviews. Members of the Technical
132Steering Team (TST) and existing core contributors will regularly invite people
133to become new core contributors. Nominations can also be made (including
134self-nominations) to the VOLTHA TST (`voltha-tst@opennetworking.org`) at any time.
135
136A good nomination will include details about who the person is (including their email
137and Github and/or Gerrit username) and outline their experience with the VOLTHA codebase
138and project at large.
139Nominations are intended to start a conversation that results in a decision to
140make the person a core contributor anyone whose nomination is not initially
141approved is encouraged to gain more experience with code submission and code
142review in order to gain further mastery over the codebase. Partial approval is
143also possible (e.g. a person may be granted the ability to handles patches only
144on a certain repository), and full approval may be granted after the contributor
145has gained more experience.
146
147New core contributors will be assigned a mentor that is either a TST member or
148existing core contributor. The mentor will serve as the primary point of contact
149to help onboard the new core contributors and answer any questions they have
150with their new responsibilities. The mentor is not the only point of contact,
151and core contributors should feel free to reach out to others if and when they
152have questions or concerns.
153
154Guidelines for Core Contributors
155++++++++++++++++++++++++++++++++
156
157Contributions in VOLTHA can should be merged after two different +1 arrive on a
158given patch-set that is verified by CI as well.
159For your own contributions, you now have the ability to approve and merge your
160own code, pending that you received two other positive reviews.
161For larger or potentially controversial reviews, please give the
162community an opportunity (at least a few business days) to review your
163contribution. Please always ask for comments on the #voltha-dev Slack channel.
164**With great power comes great responsibility; please don't abuse
165this privilege.**
166
167All Core Contributors have +2 and merge capabilities on all the repositories related
168to the VOLTHA project, but we expect that they are responsible and exercise their
169privilege **only** on patches and repositories they have expertise in and are comfortable reviewing and merging.
170
171To help patchset verification the VOLTHA test infrastructure offers Per-Patchset Verification Jobs
172triggered by specific keyword used in the patch. More information can be found in the
173`testing automation page <https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_
174We suggest Core contributors to use these triggers when they would like more checks on a patch they are uncertain about
175or that might have differences when applied to hardware pods.
176
177VOLTHA follows `Google’s best practices for code review <https://google.github.io/eng-practices/review/reviewer/>`_.
178You should apply these guidelines strictly and with confidence when reviewing
179submissions.
180
181If you are unsure about something in an issue or a review, leave a comment
182that outlines your concerns. If a resolution is difficult to reach in the
183comments section, the TST meetings are a good place to raise your concerns and
184have a discussion.
185
186Current Core Contributors
187+++++++++++++++++++++++++++
188
189This is a list of core contributors divided by area of expertise:
190
191Adapter openonu and omci-lib-go:
192
Andrea Campanella4dd04222022-03-18 15:52:28 +0100193 - `Chip Boling <chip.boling@tibitcom.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100194 - `Ozge Ayaz <ozge.ayaz@netsia.com>`_
195
196Voltha-system-tests:
197
TorstenThieme47e59db2023-05-31 08:29:47 +0000198 - to be assigned
Andrea Campanella4dd04222022-03-18 15:52:28 +0100199
200Openolt agent:
201
202 - `Thiyagarajan Subramani <Thiyagarajan.Subramani@radisys.com>`_
203 - `Burak Gurdag <burak.gurdag@netsia.com>`_
204
205ONOS apps:
206
207 - `Gamze Abaka <gamze.abaka@netsia.com>`_
208 - `Yasin Sapli <yasin.sapli@netsia.com>`_
209 - `Tunahan Sezen <tunahan.sezen@netsia.com>`_
210
211Olt adapter, rw-core:
212
213 - `Abhilash Satish Laxmeshwar <abhilash.laxmeshwar@radisys.com>`_
214 - `Gamze Abaka <gamze.abaka@netsia.com>`_
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500215
216Build system, makefiles, reviews:
217
218 - `Joey Armstrong <joey@opennetworking.org>`_
219 - `David Ferguson <daf@opennetworking.org>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100220
221All of the codebase:
222
Andrea Campanella4dd04222022-03-18 15:52:28 +0100223 - `Mahir Gunyel <mahir.gunyel@netsia.com>`_
224 - `Serkant Uluderya <serkant.uluderya@netsia.com>`_
225 - `Amit Ghosh <Amit.Ghosh@radisys.com>`_
Joey Armstrongae15c262023-03-29 15:36:28 -0400226 - `Suhas Gururaj Rao <suhas.gururaj@radisys.com>`_
Andrea Campanella4dd04222022-03-18 15:52:28 +0100227
Andrea Campanella4dd04222022-03-18 15:52:28 +0100228Community Guidelines
229--------------------
230
Joey Armstronga4d27232022-12-29 08:50:02 -0500231This project follows `Google's Open Source Community Guidelines <https://opensource.google/conduct/>`_
232
Joey Armstrongf713d7f2023-02-23 06:06:49 -0500233and ONF's `Code of Conduct <https://opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf>`_.