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