This is an archive of the ONOS 1.2 wiki. For the current ONOS wiki, look here.

This section describes, and provides pointers to, the various aspects involved in code contribution to the ONOS project.

 

Suggested Process Outline

Developers are encouraged to build on ONOS and, as much as possible, to contribute their enhancements back to its code base. The ONOS team strives to provide the right balance between enabling and encouraging innovation and creativity, but at the same time maintaining the coherency of ONOS architecture and the code. To that effect, we welcome partners and contributors to follow the process outlined below:

  • Explore and prototype your ideas freely atop the ONOS code-base.
    • We encourage doing this via quick proof-of-concepts exercises to vet out feasibility and test the concepts, but without investing much effort beyond that.
    • If possible, advertise on onos-discuss mailing list for feedback and potential collaborators.
  • Formulate a brief proposal in writing to the TST using the onos-tech-steering-team mailing list.
    • If person-to-person discussion is desired, it is suggested to put the item on the agenda for the bi-weekly TST meetings. Preferably, this should be done through onos-tech-steering-team mailing list. 
    • Technical discussion on the IRC channel can also be conducted.
    • The reason for this interactive phase is to make sure that the proposal is properly aligned with ONOS architecture & technical direction, that it conforms to the overall software design and that the abstractions are properly formed.
    • For larger submissions, the technical steering team would also coordinate with the release planning team to decide which ONOS release the submission should join.
    • For larger submissions the release planning team would also need to determine what support resources will be available for the new features or subsystems.
    • Jira Epic or User Stories would be formulated during this part of the process, for tracking the features and associated activities as part of the identified ONOS release.
  • Submit new or changed Java APIs for review via Gerrit. 
    • It is suggested to use Java interfaces rather than Java classes as this forces the discussion to revolve around the semantics of the contract, rather than implementation specifics. If appropriate, interfaces can easily mutate into classes later.
    • Code-style and Javadoc guidelines should be followed in order to maintain code consistency and quality of documentation.
  • Adjust the Java APIs based on the feedback from the TST and from the broader ONOS community.
  • Proceed with implementation and submit code for review via Gerrit.
    • Preferably, this can be done in fairly small and discrete chunks. In our experience, dropping large chunks of code for review leads to longer review cycles.
    • Code-style guidelines and unit test guidelines should be followed in order to maintain code consistency and code quality.
    • Care should be taken not to negatively impact the overall system performance and stability.
    • Jira sub-tasks can be used to track progress and to give visibility of the work to the rest of ONOS community.
    • If applicable, features should have CLI & debug support.
    • Submitter is responsible of maintaining code up to date with the master until the change-set has been committed to the codebase.

Clearly for bug fixes and small enhancements, the above process can be significantly abbreviated. However, for larger feature contributions, following this process will greatly increase the chances of success and should make for a smooth experience overall. We look forward to your contributions and to see what exciting ideas and solutions you can build with ONOS!

Getting ONOS source code

Developers should check out ONOS source, as per Getting ONOS - ONOS Source Code.

Licensing and Contributor Agreement

Any code contributed to ONOS source must be released under the Apache 2.0 license, i.e. the licensing information must appear in the header of contributed files. The IDE setup section describes how to configure the IDE to automatically add the licensing information for two IDEs, Eclipse and IntelliJ.

In addition, code submitters must agree to the project Contributor License Agreement (CLA), based on that of the Apache Software Foundation. The CLA may be found here.

Guidelines

To maintain a level of manageability in the codebase, the project maintains a set of coding and testing guidelines.

Coding style

The code style guide can be found here. Many IDEs may be configured to take care of the formatting aspects of the coding style. 

Unit tests

Unit tests are a fundamental part of ensuring the stability of ONOS. Any new classes or system components should be accompanied by unit tests. For existing code, any changes that do not alter functionality should pass existing tests; however, existing tests should also be modified to reflect any changes that alter the behavior of a class or interface. Existing tests should not be disabled when new functionality is added, unless the tests are obsolete.

All available unit tests are run as part of a full build process. Contributions should pass all tests and build successfully before being submitted. 

The full guidelines for unit tests can be found here.

Code Review

The ONOS project uses Gerrit for code review. Once submitted, a changeset is inspected by ONOS committers. The reviewers of a submitted patch, or changeset, depend on several criteria. For example, the reviewers for modifications to the existing codebase will likely include current maintainers of the particular subsystems that the changeset affects. Reviewers of new additions, e.g. applications, subsystems, and providers, will depend on where and how the new changeset will affect the existing codebase, as well as who, if any, has provided guidance during the development process of the changeset. 

Feedback

The primary mode for feedback is via email. This includes notifications about changeset acceptance and rejection, as well as reviewer comments that should be addressed. Therefore, it is important to 1) be subscribed to the project, and 2) have email notifications configured in user settings. Git/Gerrit Setup addresses the configuration of Gerrit. 

For a changeset to be accepted, it must receive one review with a +2 (not to be confused with two reviews of +1). A changeset given a -2 will not be accepted. 

More information on Gerrit may be found here.

Code submission

The process of submitting code and amending changesets using the git Gerrit plugin is described in the next section.

 

Previous : Submitting a new feature proposal
Next : Sample Gerrit Workflow

 

  • No labels