Page History

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 contributionthe formatting conventions that are used by the pages in the ONOS documentation set.

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. 

Overview

The ONOS documentation set contains the following major items:

• Tutorials - Tutorials and Screencasts to get people new to ONOS up-to-speed
• Guides - Main body of documentation for the platform in the form of the Administrator, Developer, Architecture, Contributor, and System Testing guides
• Apps and Use Cases - Landing page to each use case's documentation
  
• New Projects - Landing page to each in-progress or experimental feature in various stages of development

There are more sections, but the above set are the sections that a contributors are usually interested in. Except for the use cases, which are maintained by the members of the use cases, most everything else is contributed by the general ONOS community.

Where should <TOPIC> go?

Often, someone has something that they would like to write about, but isn't sure about where to add their topic(s). The following rules can be followed to get an idea about where to place a certain item:

• If it describes steps for how to build up to a specific, tangible example that can be run, it is a tutorial.
• If it describes a work-in-progress or a to-be-implemented function related to ONOS itself, it is a feature proposal.
• If it describes a mature function or feature and focuses on:
  • The design, architecture, and/or implementation, it is part of the Architecture and Internals Guide.
  • How to extend or modify functionality through code (APIs, classes/interfaces, etc), it is part of the Developer Guide.
  • How a user can interact with it, it is part of the Administrator Guide.
• If it describes anything about a use case, it should be added under Apps and Use Cases. For existing use cases, it is best to consult its members for where the page/topic belongs.

Documentation section owners

Similar to the Module Owners for the ONOS code base, parts of the documentation set may have owners associated with them. The section owners are responsible for maintaining the organization and content of the sections that they own, and may be contacted with questions about the pages or the type of content that they maintain.

A contributor may become a section owner by creating a set of pages, working on something associated with a certain section of the docs, or volunteering as an owner of certain content on the mailing list or documentation Slack channel. The current list of section owners are listed in the Documentation Section Owners page.

Communication channels

Have questions or want to talk with us about docs?  Join us on one of these channels:

•  The onos-docs channel on Slack
• The onos-doc mailing list

Meetings

Please join us for our regular community documentation calls.  Details below:

• Time: Every other Wednesday at 1 pacific (check the ONOS Community Calendar for dates)
• Dial-in: https://www.uberconference.com/davidwboswell
• Agenda and Meeting notes: ONOS Documentation
  

Procedure

Like everything else for the project, prominent documentation-related tasks are tracked on the ONOS Project JIRA in the Documentation epic. Anyone interested in contributing should register for an account for the project Wiki and JIRA. To register, go here and follow the 'Join ONOS' button.

Working on existing tasks

A potential contributor should take ownership of a ticket if they see a task that they're interested in. A current maintainer (or, if the item is related to an owned part of the docs, likely the section owner) will review the changes, and provide feedback if needed.  Find a list of documentation tasks that need someone to drive on Jira (and once one of these documentation tasks is done, we're happy to thank you with some ONOS swag).

Adding new content

A contributor interested in adding new content (tutorials, sections in the guides, etc.) should check if a JIRA ticket exists for the task in mind. If not, they should create a new ticket for the task, and take ownership of it. Messages should be sent to onos-discuss:

• If the content is associated with a section with a section owner
   
• Initially with ideas for the content (to help de-duplicate effort)
• With link(s) to the new content once it's written (so that reviewers are aware of the content)
  

Whenever a new page is added to a Guide, corresponding links should also be added to the top-level TOC.There may be several feedback cycles before the new pages are formally linked into the documentation set. It is generally a good idea to follow the Wiki Formatting Conventions while adding new content