How to contribute

From OpenNMS
Jump to: navigation, search

Get Involved

Contribution in an Open Source project can happen in many ways. People come with ideas we had never in mind so please see the following list not as complete. Here are the things we are happy about any helping hand to make OpenNMS more awesome

Contribute Code

You are a developer and you want to change the source code. Here are few entry points which guide through different topics.

Help in Documentation

Network management can be complex, software like OpenNMS interacts and integrates with many different systems.

Documentation is similar to software: never good enough and never done. If you want to join the OpenNMS community and you want to help to improve the documentation, this page is for you. Help by finding and reporting issues on docs and fix them.

To be able to see what issues are already there and open new ones, you need access to our issue tracker. (Requires login, sign up here)

To get in contact with people who are working on issues regarding documentation or for questions, please use the opennms-docs mailing list.

The documentation is split into two headings, the Wiki Community Documentation and the Official Reference Documentation.

Wiki Community Documentation

The Wiki is a good place to describe how OpenNMS is integrated with 3rd party applications, How-Tos and tutorials. For example you want to describe how you use a SNMP monitor or an SNMP data collection in OpenNMS to monitor a Juniper MX960 with Junos OS Release 12.2. Another example could be how you used Provisiond to integrate with a specific CMDB or an inventory tool. The Official Reference Documentation on the other side explains how to configure an SNMP monitor with all it's parameter. Wiki pages can be created or changed by everyone with a valid Wiki user account.

To be able to create or edit a Wiki page you need an account which can be registered at Request Account. The Wiki is publicly available and for Spam reasons, it could take some time until your account is manually activated and verified.

If you have problems with activating your Wiki account, please get in contact on the opennms-docs mailing list.

Creating wiki pages is easy, finding them is a little bit more complicated. Please tag your created wiki page with Categories.

If you have problems or you find something you can't fix by yourself, please report this issues in our issue tracker component Documentation - Wiki.

Official Reference Documentation

This documentation describes the core features of OpenNMS and is bound to a version. The behavior of any component may change across versions of the software and this is the reason that this documentation is now located within the repository alongside the code. If you install a specific release of OpenNMS, you should use the reference documentation that matches your installed version. The contribution to this part of documentation is more strict. To change this documentation a GitHub account is required. You can create pull requests which have to be reviewed for certain criterias. If you change met all the criterias and is merged, the documentation will be deployed and released along with OpenNMS. It and reflects the core functionality of the release. The documentation style is a technical reference and should be feature complete serving as an authorative reference.

OpenNMS is used from people working different areas, so the documentation is split into the in following parts:

  • Installation Guide: The audience is people who have to deploy OpenNMS in an organization. It should describe installation scenarios and how to install OpenNMS on different platforms. Current state: guide-install.
  • Administrators Guide: The audience is people who maintain and run OpenNMS and have to configure it, e.g. monitoring of services and performance data collections. Current state: guide-admin.
  • Users Guide: The audience is people who work only with the OpenNMS WebUI and work mainly in a Network Operation Center, e.g. What are the workflows for acknowledging notifications and alarms. Current state: guide-user.
  • Developers Guide: The audience is people who write code, e.g. ReST API definition, XSDs, How to create a new Poller or a new data collector. Current state: guide-development.
  • Documentation Guide: The audience is people who want to contribute to the source based AsciiDoc documentation with guidelines. Current state: guide-doc.
  • Release Notes: The audience is administrators of OpenNMS. This document gives the list of changes in a new OpenNMS release. Current state: releasenotes.

The workflow how to contribute to the Official Reference Documentation can be found in the guide-doc.

Tools and hints for your contribution?

To lower the barrier for working on the docs, we prefer the usage of free software. If you create an illustration in yED or Xmind, export the drawing in a PNG format and provide the original source file in your pull request.

  • If you don't know anything about AsciiDoc, the following guide can help you to get started: http://docs.opennms.org/OpenNMS/snapshot/develop/documentation/guide-doc/
  • State of the art browser for changing the Wiki.
  • An Ascii text editor which is able to write UTF-8 for changing the documentation from the source
  • You want to create conceptual drawings, you can use yED. It runs on multiple platforms and is free available.
  • Describing workflows you can use Xmind which is available on multiple platforms
  • For people working on Windows the GitHub application can help working on the source based doc. Please take care on Windows writing UTF-8 and taking care with line breaks.
  • If you are working on MacOSX Atom with AsciiDoc preview plugin can help