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

Trying to get involved in an open source project can feel like a daunting task. This section provides some suggestions and pointers to make this jump smoother for those who want to get involved.

Types of Contribution

Submitting code as a developer is certainly a way to contribute to a project, but not the only way. There are many aspects to an open source project where contributors can help, including (but not limited to):

  • Testing - Functionality (unit and integration) testing, bug hunting, and implementing test frameworks 
  • UI design - Developing plugins for, and enhancing the GUI
  • Documentation - Documenting system usage and architecture, and writing tutorials for the ONOS wiki document set
  • Development - Writing applications, building use cases, and submitting bug fixes and enhancements to the existing code base

These roles are fluid - any work that modifies the system will need to be tested and documented, and documenting an aspect of the system or its usage may involve reading, running, and testing pieces of code so that you can understand them well enough to write about them.

Resources

Mailing Lists

First and foremost, anyone interested in contributing in any way should join onos-discuss. This is the primary mailing list for general questions and discussions. There are several other mailing lists that you may want to join, such as onos-dev for ONOS developers.

Tutorials and Documentation

As one of its tasks, the project maintains up-to-date tutorials for both users and contributors. In general, those interested in contribution should at least complete the Basic ONOS Tutorial, as it introduces many of ONOS's features. 

In addition to the tutorials, the ONOS Documentation Set provides guides describing various aspects of using and developing on ONOS, as well as its architecture and API documentation (Javadocs). For developers, the recommended way to use the documentation set is:

  1. Learn how to install, run, and use ONOS, as per the User's Guide
  2. Learn how to set up the development/test environment and the usage of JIRA and Gerrit, and testing and coding guidelines as per the Developer's Guide
  3. Reference relevant parts of the Architecture Guide, Javadocs, and Developer's Guide Appendices

For step 2. of the above, readers interested in development should refer to Contributing to the ONOS Codebase, and readers interested in the documentation effort should focus on Contributing to ONOS Documentation.

Crowd Registration

An account is required to access to the various contributor services and access rights, such as JIRA issue creation. An account may be created by registering here.

Lost usernames may be recovered by going here.
Lost passwords may be recovered by going here.

Project Model

Contributors begin as submitters, and may progress to committer status. In a similar vein, contributors may work on the existing ONOS codebase and use cases, or, with approval of the technical steering group, introduce their own work as a sanctioned project. ONOS Governance describes the project model that the ONOS Project follows in further detail.

Current Projects

The ONOS Project is a composite of the ONOS SDN platform itself and the various projects using it (applications and use cases). Information about the ongoing projects may be found on [Projects]. Many of these projects will have an Epic associated with them so that the tasks associated with them may easily be found, as described in the next section. 

Finding Tasks to Work On

Finding tasks on JIRA

The ONOS Project keeps track of various tasks with JIRA. In specific, we maintain a category for tasks, labeled as "Starter", which have lower barriers of entry. These Starter tasks are intended for newcomers to the project that wish to work on existing material. 

To find current Starter tasks:

  1. Go to the ONOS project JIRA, and log in with your account. You will be taken to the Project Dashboard. 



  2. From there, follow Advanced Searching and search for labels = starter and assignee = null. This will bring up all Starter tasks that are unassigned. Each task has a name of format ONOS-[number] (ONOS-255 for our example). Selecting a task will display its details.



    If you have a certain type of task you would like to work on, such as testing, you may also filter the search by epic name by appending "Epic Name" = <Epic>. For example:

    labels = starter and assignee = null and "Epic Name" = Test

    Will return all available Starter tasks related to testing. Follow Finding Issues by Epic to view available epics.

     

  3. Once you find an issue that you would like to work on, assign it to yourself by selecting "Assign to me" under People. Your name should appear under the Assignee field, and you should see a message "ONOS-[number] has been assigned".

  4. To verify that you now own the issue, go to Agile > ONOS Scrum Board. You will be taken to the Work view (swim lane) of the Scrum board, which shows the progress of all current tasks based on who is working on them. Your name should appear as one of the entries (they are alphabetical, so you may need to scroll a bit), with your new issue under the To Do column (the blue entry in the figure below). Selecting the issue will display its details in a sidebar to the right. 



    If your name or your task doesn't appear, move your issue from the Backlog, as per this section. 

  5. Once you are ready to work on the task, drag the issue from the To Do column to the In Progress column. Similarly, once you are finished, drag the issue from In Progress to Resolve Issue under Done. When your changes are accepted by the project, it can be moved to Close Issue under Done.

 

More information about searching JIRA can be found in Finding, Claiming, and Working On Issues.

Proposing a new project or task

Anyone can approach the mailing lists with project ideas and proposals. For example, if a developer has written a new application or a provider for a new protocol, and wishes to contribute it back to ONOS, it is a good idea for them to drop a line on the mailing list for feedback and further suggestions, rather than to submit a pull request without a warning.

Creating Tasks and Sub-Tasks

Sometimes, you may be asked to file an new task/issue or subtask, based on a conversation you had on a mailing list.

To create a new issue, take a look at this page. To create a subtask from the Work view, click on a task, and in the side panel, go to the button on the upper right corner (...) > Create Sub-Task: 


This will bring up a form similar to the Create Issue form described in the aforementioned link that can be filled out.

Asking Questions

If you are working on a task, and are stuck, don't be afraid to ask questions - it's certainly in everyone's interest to move the project forward! However, please be sure to search existing documentations and mailing list archives before doing so, or the response you get may consist of a link to a page or something similarly terse. Likewise, If you have log files, or steps for recreating an odd behavior, attach or mention those to your question as well - Just saying "It's broken" without the specifics will just result in a response asking for those materials. 

Submitting Bug Reports

If you encounter unexpected or incorrect behavior, first make sure that you understand what the correct behavior should be (and why it should be that way), and confirm that you are using the system correctly based on the documentation. Try to isolate the issue as much as possible, by finding the minimum set of steps (or a small, simple piece of code) that can reliably reproduce the problem. Make sure to include a transcript or log of any input steps or output. Finally, to submit the bug report itself, follow the instructions at Using Jira to create an issue: bugs, feature requests, documentation.

Return To : ONOS for Newcomers


 

  • No labels