This section describes how to submit bug reports and feature requests, and to contribute code and documentation to the project. It also describes the general workflow involved in code contribution.

Contributing to the ONOS Codebase

Reporting bugs

Creating tickets on JIRA : As mentioned earlier, the ONOS project employs JIRA to track the status of various tasks.

Submitting patches

Writing unit tests and Javadocs : Naturally, code contributions almost always include writing unit tests (JUnit) and documenting the codebase (comments and Javadocs).

Don’t break things: Sanity checking with Maven

Promotion : With a good track record, a contributor may advance to core developer status (Do we implement a mentorship system here?).

Contributing to the ONOS Guides 

The ONOS Guides and tutorials are written using the Confluence Wiki markup interface. In order to lower the curve required to add or edit information, and to introduce consistency, the Guides avoid the usage of raw HTML and Wiki Notation as much as possible, relying on formatting and macros provided by the Confluence interface. 

Several conventions are used within the documents. Contributors of documents that do not conform to the conventions may be asked to edit them. 

Section Headings

Each section in a page should have a terse title in one of the Heading levels under the Paragraph dropdown. The convention for (sub)section headings are:

• Main sections : Heading 2
• Subsections : Heading 3
• Subsequent subsections : Heading 4

To apply a heading format, simply drop the cursor on a line, and select the heading from the dropdown.

Table of Contents (TOC)

For Individual Pages

A new page should always have a table of contents near the top, after a brief summary of the page. The Table of Contents macro is used to automatically grow the TOC out of the page as sections are added.

To add a TOC, select Insert > Table of Contents. A popup for TOC options should appear. Here, set the Maximum Heading Level to 3, to prevent the TOC from capturing subsections past Heading 3. This aids to reduce the noise in the listing. 

For the Guides

An ONOS guidebook is a collection of child pages under one parent page containing a top-level table of contents. This TOC shows pages and their main sections (i.e. up to Heading 2) as links.

Code blocks

Code blocks are used instead of inlined monotype for multi-word/line commands and sample shell/CLI output. Code blocks may be added by:

1. Navigating to Insert >  Other Macros
2. Choosing Code Block from the "Select Macro" popup window
   

This brings up the prompt for configuring the code block. Here, syntax highlighting should be turned off by selecting "Plain Text" in the Syntax Highlighting option before hitting "Create".

Links 

It is good to link to the appropriate pages/sections whenever they are mentioned. 

Whenever a new page is added to a Guide, corresponding links should also be added to the top-level TOC.