Community/Welcome Guide

From OpenNMS
Jump to: navigation, search

Hello World

Welcome to the OpenNMS community- the place of the world's first enterprise-grade network management platform developed under the open source model. This document is meant for anyone interested in learning about the OpenNMS project and the surrounding ecosystem. It is intended for people who are new to the project.

In this document you will learn the following topics:

  • Where can you find documentation
  • How can you get in contact with users, developers in the community
  • Which organizational groups are involved and how is it governed
  • How to get involved and how to contribute to the project
  • How are issues and incidents managed and the development process

Documentation

In OpenNMS, you can find two types of documentation. The first type is a MediaWiki based documentation. It is the place where you can find tutorials from users how to integrate with 3rd party applications or devices and how are workflows around the project are defined. This documentation can be easily edited and changed by any person with a registered account on the MediaWiki and the change policy is not very strict. The Wiki-based documentation can be found in http://wiki.opennms.org/wiki/Main_Page and is structured by categories.

The second type is an Asciidoc based documentation. This documentation is version controlled and will be shipped with OpenNMS as official documentation. It is intended to document the full feature set of a specific OpenNMS version and can be used as a reference. Any person with a registered GitHub account can provide changes as Pull Request and follows the Code Contribution Workflow. People with commit permissions, i.e. OGP's and The OpenNMS Group employees are allowed to review and merge such changes so they will be published with the next release of OpenNMS. With every OpenNMS release, the version-controlled documentation will be built and deployed. The latest documentation can be found online on https://docs.opennms.org

Helpful links as a starting point

Get in Contact

Find people who have experience in network management and monitoring in several places. You can ask questions by using our topic driven mailing list. All these mailing lists can be found on the Mailing Lists page in the wiki. Talk with people in real-time using registering a nick on Mattermost or via IRC, connect the freenode network and join channel #opennms. With the Q&A platform you can find help or send your own questions.

Besides mail, chat and the Q&A forum it is also possible to get in contact in real life footnote:[Real Life: A place with awesome graphics and you can get hurt]. There are two conferences organized by the OpenNMS community:

  • DevJam: The 5th season of the year to hack, learn and work for one week with people on OpenNMS. The annual conference is held at the University of Minnesota in Minneapolis in June/July.
  • OpenNMS on YouTube
  • The OpenNMS User Conference Europe which is organized by the OpenNMS Foundation Europe e.V. (OFE).

Talks and workshops are given by people from the community and commercial background with OpenNMS. There are several places where you can get news and information around the OpenNMS project.

Social Media

Blogs and other content

Contribution

Rather than just using software there are several possibilities to contribute in the community. Reporting a bug, make suggestions for enhancements, help improving documentation or write in a blog how you solved a special problem are ways to enrich the project. In most cases, you start with using OpenNMS in your environment and with more experience you may find bugs in the software. OpenNMS uses JIRA as bug and issue tracking software. We use it not just for tracking bugs it is also the core component to release the software and plan new features and enhancements. To create issues it is required to create JIRA account.

If you are able to fix open issues with code patches or you just want to provide source code contribution with patches, you have to sign the OpenNMS Contribution Agreement. This is a fundamental requirement to get your source code contribution merged to the main release of OpenNMS. Contributing documentation is a great possibility to learn new features or fill gaps and give you the possibility to share your learning experience. It is also a great way to figure out where are limitations and opens other possibilities to help to improve the software.

In the OpenNMS community, there are two main events, DevJam and OUCE. Both conferences are organized by volunteers organizing the event. From running a call for papers, help organizing projects, giving talks, workshops or help to prepare the infrastructure - there are several tasks you can get involved.

OpenNMS is the work of a large number of people. In order to maintain some order with respect to the copyright to the code, every contributor is asked to sign a "Contributor Agreement". The OpenNMS Contributor Agreement is based directly on the Sun (now Oracle) Contributor Agreement. It implements the concept of a dual copyright. This allows the OpenNMS code copyright to be consolidated under one organization (The OpenNMS Group) while allowing the creator of the code to maintain all of their rights.

Oracle provides a rather comprehensive FAQ on this agreement.

To get your code contribution upstream it is required to download, sign and send us the OpenNMS Contributor Agreement (OCA).

Development

The OpenNMS software is developed on GitHub and is structured in several development branches. Different branches are the basis to develop new features and make a new release. The source code is maintained in a public GitHub repository.

Development branches

Master Branch

The master branch is used for stable releases. Changes are not committed directly to this branch, all changes go through the development. After a time period, described in section Release Management, features from development will be merged to master and are tagged as versions of OpenNMS. To ensure stable releases there will be release candidates defined and are publicly available as installation packages and can be tested.

Develop Branch

The function of the Develop Branch is used as integration branch for features, bug, and hotfixes. Changes to this branch should only be driven from specific feature branches to the Develop Branch.

Feature Branch

These branches are originated from the Develop Branch and represent a specific enhancement or complete feature. The name of this feature branch is described in our issue tracking system link:http://issues.opennms.org[JIRA]. To identify features to the issue tracking system, the branches start with the JIRA issue number. This is important for the reason JIRA creates the Release Notes which tracks all changes between versions.

Foundation Branch

This special branch is used to get hot- or bug fixes back from the commercial OpenNMS MERDIAN. It is used by The OpenNMS Group, Inc. and gives a transparent way to see which fixes and features are backported.

Code Contribution Workflow

With GitHub comes the possibility to fork the whole code base of OpenNMS and change code and documentation as you want. You want to contribute your changes back to the release of OpenNMS you can follow the link:https://help.github.com/articles/using-pull-requests/[GitHub Fork & Pull] development principle. Pull Requests solve a specific issue and require an entry in our JIRA issue tracking system. These Pull Requests have to be reviewed and have to pass tests before they can get merged from an OGP or OpenNMS Group member.

Workflow for code contribution

This workflow ensures code changes are tracked for release management driven by JIRA. The pull request review step is important to get a shared understanding of requested code changes and improve code stability and quality.


Bug tracking and project management

The OpenNMS community appreciates feedback from user and tester. Any bug in code, documentation or workflows can help us to improve the project and the software. If you find a bug please verify it is not already been reported by searching JIRAs bugs list: https://issues.opennms.org. In the top menu Issues, you can use Search for Issues in the project OpenNMS with Type: Bug.

If you found a new bug, fill out a bug report:

  • Give a clear, concise summary
  • Provide as much detail as possible in the description. Paste in your command output or stack traces, link to screenshots, etc.
  • Be sure to include which version of the software you are using. This is especially critical if you are using a development or unstable branch.
  • Add information about your Java environment which is used by OpenNMS. You can find it in the configuration java.conf in your OpenNMS configuration directory and by running java -version
  • Any deployment-specific info is helpful as well. Example: Ubuntu 14.04 LTS, which version of PostgreSQL, JRobin, RRDtool, store-by-group- or store-by-foreignsource settings.

To verify bugs you can use the mailing lists or the Q&A board.

Release management

OpenNMS is released and distributed in two flavors HORIZON and MERIDIAN. Both distributions are released under the AGPLv3 license model. Version numbers follow the Semantic Versioning Schema.

Important Release Information
  • The HORIZON major releases follows the main release cycle of 3-4 month.
  • HORIZON minor releases are targeted for every third Thursday of a month.
  • All new features are developed in HORIZON and will go in MERIDIAN only if they are stable enough for commercial support.
  • The OpenNMS Group, Inc. provides the MERIDIAN distribution with commercial support and the main release cycle of *~12 months* and support is given for an extended lifetime.
  • Security and bugfix patches are maintained by The OpenNMS Group, Inc. and are backported between the two distributions.
  • To get patches and fixes for MERIDIAN, it is required to have a MERIDIAN subscription for repository access.

Release relationship between HORIZON and MERIDIAN

Bugfixes and security patches are shared and new features will be moved from HORIZON to MERIDIAN. The decision to release new features in HORIZON is community driven and the for MERIDIAN it is driven by The OpenNMS Group, Inc. To release the software the community and The OpenNMS Group uses the public available JIRA issue tracking software.

HORIZON 4 month release phases

  • Development: Phase to develop new features, changes in architecture and major bug fixes. This state can be installed as OpenNMS Horizon SNAPSHOT release. Changes are merged from pull requests after reviewing and testing. Major releases can require configuration changes or data migration.
  • Feature Freeze: No features are pulled in develop branch. The code base gets stabilized and get ready for a first release candidate.
  • Stabilize code: Getting problems solved, missing unit tests are added, outstanding review are done, fixes are made and get Continuous Integration green. Preparation for Release Candidate 1
  • Release Candidate 1 (RC1): Test phase driven by the OpenNMS community. Hotfixes can be made and applied to development branch during the test phase.
  • Release Candidate 2 (RC2): Test phase with applied hotfixes from RC1
  • Release: Release date for HORIZON which can be installed as a stable release.

Phases for releases are announced on the OpenNMS Developers mailing list. Releases are announced on the OpenNMS announce mailing list and can also be found as an entry on the OpenNMS Website and changes are published in Releases section of the project website.

Branch and Pull Request Guidelines

We use several tools to manage the software and the workflows require some guidelines to track changes from gradle to grave through our software. The tool chain goes from JIRA to GitHub to Bamboo which is our quality gate and delivers the packages which can be installed by anyone wants to use OpenNMS. To provide transparency and make the usage for others as easy as possible, we recommend contributors to follow this Pull Request guidelines:

  1. Create an JIRA issue for the work you want to contribute. Release management is done through JIRA, if your changes can't be assigned to a JIRA issue, they are not tracked accordingly and can cause trouble in the future. Your changes will be invisible to others cause they do not appear in the change log of the release notes.
  2. Create a branch from the target you want to contribute to in the form of jira/${issue-number}. This way users can track easily all stages from JIRA to the PR in GitHub until to packages delivered on our mirrors. A target could be develop for the next major release of Horizon, a specific Horizon minor release branch or foundation if it needs to be fixed in long term support versions of Meridian.
  3. Tag Pull Requests subjects with "${issue-number}: <your title>". This makes it easy to search in Pull Requests and identify changes related to a JIRA issue for further maintenance.
  4. Ensure your Pull Requests go green in Bamboo and if not ask for help in the OpenNMS Development channel in our public [chat](https://chat.opennms.org).

Pull Request Labels

Changes to the source code are made with Pull Requests and need to be reviewed for transparency and quality assurance. They can be merged from an elected OGP within the community or employees of The OpenNMS Group. The following labels are defined:

By Type
  • enhancement: Extend or improve an existing feature
  • docs: Changes to documentation
  • configuration: Changes to OpenNMS configuration for device and application monitoring support
  • backport: Changes which need to be backported to older versions
  • bug: Fixes an existing bug in the code base
  • refactoring: Related just to code which does refactoring of same feature and functionality
By Workflow
  • duplicate: Changes are made already somewhere else
  • invalid: Changes can't be merged cause the code changes don't fit use cases
  • revert: This change reverts and previously merged Pull Request or Commit
  • review: This Pull Request is done and needs to be reviewed and merged to the code base
  • triage: This Pull Request can't be merged cause there are open questions or discussions which makes the PR incomplete to merge
  • wontfix: This Pull Request will not be merged for several reasons

Continuous Integration

For quality assurance we use Atlassian Bamboo as Continuous Integration (CI) system footnote:[Open Source Licensed, https://www.atlassian.com/software/bamboo]. It is publicly available on https://bamboo.internal.opennms.org It provides the following tasks:

  • Checks code for compile errors
  • Runs unit and integration test infrastructure
  • Runs final smoke tests
  • Build and generates Java API documentation
  • Build and generates version related documentation
  • Build and distribute RPM and DEB packages to the public server

All branches in the OpenNMS GitHub repository will be processed by the CI system. Feature branches and results are distributed to the public available repository server as YUM and DEB package. If you are interested to get your branch of your forked OpenNMS processed through bamboo, please contact the OpenNMS Developer mailing list. There are also branches intended to fix bugs, which means that they do not introduce new features. These branches are named after the JIRA issue following the pattern NMS-{issue-number}. Builds are automatically triggered by changes in feature-, develop or master branches.

Governance

The project is mainly driven by The OpenNMS Group, Inc. and an elected group of community contributors OGP. OGP and people from The OpenNMS Group, Inc. have commit access to the project where the software is released and distributed. Most decisions will be made using a lazy consensus model.

The OpenNMS Group, Inc.

The OpenNMS Group, Inc. is the biggest sponsor of the project and provides a commercial product OpenNMS MERIDIAN which is similar to Red Hats Enterprise Linux subscription. Beside that, they also develop new features through OpenNMS HORIZON which is similar to Red Hats Fedora and free as in freedom. The build and packaging infrastructure is also maintained and provided by the commercial company.

OpenNMS Foundation Europe e.V.

Getting people independent from companies to the project, there is a non-profit foundation based in Germany. Organizations and individuals can apply to become new members. Details on membership can be found on http://www.opennms.eu/membership.

The OpenNMS Foundation Europe e.V. (OFE) was founded on July 31st, 2012. The objective of the organization is to promote, develop, educate and research around free software and network (management) technologies, especially OpenNMS. The OFE website with links to material of the conference can be found at http://www.opennms.eu.

OFE promotes the development, usage, and adoption of the network management platform OpenNMS. Getting people with different skill sets together is important and for this reason, they run the annual OpenNMS User Conference Europe (OUCE). This conference is run by foundation members and volunteers. The OFE initiates software development and studies which are made available to the public under the GPL or a suitable successor.

The statutes of the foundation can be found at http://www.opennms.eu/statutes (in German). Members are expected to participate in the OpenNMS community through technical contributions or community building efforts.

Order of the Green Polo

The Order of the Green Polo (OGP) is the super secret brotherhood of developers of the OpenNMS Project. You can recognize and OGP member by their good looks as well as their super-flashy, very coveted OpenNMS Green Polo.

[quote, Tarus Balog, Founder of the OpenNMS Project] Back in fall of 2004, I wanted to find a way to recognize those people who make OpenNMS what it is, and to thank them in some fashion. Ever since the advent of "business casual" workplace attire, the "logo" polo shirt has become a fixture in IT departments around the world. We sell black and white polos with the OpenNMS logo on our website. But this is much, much, much, different. These are "green" polos, very rare, and they will never be available for sale. Think of them as equivalent to winning The Master's golf tournament's green jacket - only harder to get. In order to get one, all one has to do is give up all hope of having a life outside of OpenNMS, work long hours for free, and basically become a closed superhero, squashing bugs (or uncovering existence) in a single bound.