How to contribute?

How can I report enhancement requests and bugs?

OpenNMS uses JIRA as a software management application. This is where we report bugs and issues to enhance and develop the software. Software versions and releases are driven from this JIRA instance. Please use JIRA for qualified problems that can be addressed in software development. To qualify problems we use this Discourse forum and our Chat.

To create issues you must create a JIRA account.

How can I report security issues?

Please send all security-related issues to Use this address for all of our OpenNMS software, including any of OpenNMS’s web services. The process of how we deal with security issues is described in Security fixes and Security Process.

How do I contribute to the project?

If you are able to fix open issues with code patches or you want to provide source code contribution with patches, you have to sign the OpenNMS Contribution Agreement (OCA). Read the agreement, sign in with GitHub to agree, and “sign” by filling out the form. The OCA implements the concept of dual copyright. This consolidates the OpenNMS code copyright under one organization (The OpenNMS Group) while allowing the creator of the code to maintain all of their rights.

This is a fundamental requirement to get your source code contribution merged to the main release of OpenNMS. The OpenNMS software is developed with git and the source code is publicly hosted on GitHub.

To align JIRA and GitHub we use a workflow to create JIRA issues first and reference them by the JIRA issue number in the pull request.

The general workflow is as follows:

Note that you get the code by forking a repository and you send us pull requests. Organizational things like JIRA can also be done afterward. :slight_smile:

  • Master Branch: The master branch represents the code of the latest stable release.
  • Develop Branch: This is the default branch and is the target and integration branch for the next major release. It is the source you branch off when you want to develop new features and enhancements which need to be in the next major release.
  • Minor/Patch Release Branches: If you need to fix bugs with a target for a next minor/patch release, branch off the branch named release-<major>-<minor>-<patch>. To decide which changes go to which version, we follow Major releases can break things, so please read the release notes before you upgrade!
  • Foundation Branch: We use this special branch to get hot- or bug fixes back from the commercial OpenNMS Meridian release which is also auto-merged upstream to Horizon releases. These branches are maintained by The OpenNMS Group and give you a way to see which fixes and features get back-ported to long-term maintained versions of the software.

When you finish your work, create a pull request against “Develop” when you branched off to target for the next major release or pick the “Minor/Patch” release branch where you want to release your changes.

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

Do you use continuous integration (CI) systems?

For quality assurance, we use CircleCI as a continuous integration (CI) system. It is publicly available on

We use it for the following tasks:

  • Check code for compile errors
  • Run unit and integration test infrastructure
  • Run smoke tests
  • Build and publish Java API documentation
  • Build and publish version-related documentation
  • Build and distribute RPM and DEB packages to the public server
  • Build and publish Docker container images to DockerHub

All branches in the OpenNMS GitHub repository will be processed by the CI system. Feature branches and results are distributed to the publicly available repository server as YUM and DEB packages. Builds are automatically triggered by changes in feature-, develop, or master branches.

What about documentation?

Spot a typo? Think something is missing from the documentation or a topic could be explained better? Set your inner technical writer free by contributing to the documentation. With a “docs as code” approach we use a similar Jira/review/build process described above. Follow the guidelines for doc contribution in … the documentation!