Issues in JIRA and GitHub workflow

Changes in the official documentation and code base are tracked by JIRA - the issue tracker of OpenNMS. This is the main tool in the project to organize tasks and plan releases. When a new version of OpenNMS is released, all issues are reflected in the release notes.

It is required to have JIRA account for creating and commenting issues and a GitHub account for giving your contribution as Pull Request.

The main workflow to add or fix something is defined as the following:

  1. Create an issue in JIRA. The issue number is a unique identifier and is used as a reference, e.g. NMS-7214

  2. Fork OpenNMS to your private GitHub repository

  3. Create a feature branch from develop with the following name schema: NMS-<number>-<Your-Issue-Headline>

  4. Add a link of your working branch to your JIRA issue and allow others to help

  5. Create or fix documentation

  6. When you’ve finished, send a Pull Request of your changes to the OpenNMS repository

  7. Add a review header in your Pull Request comment message

  8. Add a link with to the Pull Request and ask for a review

  9. If the review is worked in, the Pull Request will be merged into the codebase and is now in the official release cycle.

Example workflow creating documentation

The following example describes a workflow how to create a new documentation for the DnsMonitor.

  • Everything starts with an JIRA issue

01 pick issue
Figure 1. Create or pick an issue
  • Fork the OpenNMS project in your GitHub repository.

  • Go to your GitHub account with your repositories and create working branch from develop, which is the default so you don’t have to change anything.

  • Create a working branch for the JIRA issue you want to work on with the given name schema:

    NMS-<number>-docs-<Subject-without-spaces>

For our example: NMS-6634-docs-DnsMonitor. This name is used later in the Pull Request and helps to identify and track changes driven by this issue. Type in the name in the input field and GitHub create the branch for you.

02 create branch from dev
Figure 2. Create a working branch for the JIRA issue in your repository
03 link to working branch
Figure 3. Create a link in the JIRA issue to your working branch, it indicates somebody is working on it.

There are two ways to work on the issue.

  • Option 1: Make a local copy and work on your local computer

  • Option 2: Edit directly all the files online in the GitHub web editor

Work on your computer locally

To work on your local computer git or the GitHub GUI is required. Clone your repository to you local computer with

git clone https://github.com/<your-github-nick>/opennms.git

It will download the repository with all the branches to your local system in the 'opennms' directory. By default you are in the develop branch of OpenNMS. You can switch to your previously created working branch with the following command:

git checkout -b NMS-6634-docs-DnsMonitor origin/NMS-6634-docs-DnsMonitor

You can show list all existing branches with

git branch -r

Now you have your working branch where you can start your contribution.

04 your contribution
Figure 4. Create the documentation and save it!

The command git status gives you all changes. To add your work to the version controlled history you have to add your changes to a commit. In our example we have created the 'DnsMonitor.adoc' file and it is shown as currently untracked in git.

The command

git add DnsMonitor.adoc

adds this file for the next commit.

Note
The full path to the file to add depends on your current location in the file system.
05 add to git
Figure 5. Add your created or modified files with git add.

Write a comment which explains what you did. The first line in the commit message is used as a subject line and should contain the JIRA issue number and the JIRA issue subject. After the subject keep one empty line and you can use bullet points to describe your changes

06 git comment
Figure 6. Git comment with a subject line and bullet points for the description

The commit with your change is now stored in the local history of your repository. With the following command you can upload your changes to your GitHub repository.

git push
07 git push
Figure 7. Upload your changes to your GitHub repository
Note
Upload changes to your repository doesn’t have any effect on the project. You can use it as your backup and to stage your working progress. It also allows others to help you in your current working branch.

The next step is sending your changes to the official OpenNMS repository described in section Send the Pull Request.

Work with the GitHub Web editor

It is possible to work completely on the GitHub editor.

Warning
Be careful if you don’t have a reliable internet connection. It could be possible you loose the content in case of connection loss.

You can create a new file your repository as following:

13 web create new file
Figure 8. Create a new file with the + in (1)
14 web filename content commit
Figure 9. Set a file name and create content and a commit message
  1. File name to create in our case a new documentation file with the name 'DnsMonitor.adoc'

  2. Documentation in AsciiDoc format

  3. Subject for the commit message with NMS-<number>-docs-<Subject-without-spaces>

  4. Short information about your change

You can commit the change directly online by clicking on Commit changes on the bottom end of the page.

The next step is sending your changes to the official OpenNMS repository described in section Send the Pull Request.

Send the Pull Request

If you have finished, it’s time to create a Pull Request to indicate your contribution should go in the official OpenNMS codebase. Commit and push all your changes to your GitHub repository. Create a Pull Request from the GitHub web application with click on Compare & pull request. The Pull Request will be created automatically against the correct develop branch.

08 compare branches
Figure 10. Click on Compare & pull request

GitHub will use your last git commit message for the Pull Request. Add to your commit message the following information:

JIRA: http://issues.opennms.org/browse/NMS-6634

Todo Review:
- [ ] Typo and grammar
- [ ] Formatting and conventions
- [ ] Content

This comment creates a review status indicator for the review.

09 create review indicator
Figure 11. Create a review status indicator in your Pull Request message

To indicate you need a review set a link for the Pull Request in the JIRA issue.

10 doc pull request issue
Figure 12. Create a link with a review request in the JIRA issue

Reviewer can add annotations lines in your contributed changes. You can work in this comments by just making your changes in your working branch, commit and push them to your repository. GitHub will automatically add this commits to your pull requests. If the status for Content, Formatting and conventions and Typo and grammar is finished, the Pull Request will be merged to the official OpenNMS code base.

Note
You will be notified if a reviewer adds comments or request changes through the GitHub.

If your Pull Request is merged you will be also notified and the status of your outstanding Pull Request changes to status Merged on your GitHub profile page.

11 merged pull request
Figure 13. Status of pull requests is indicated on your GitHub profile page

The OpenNMS Continuous Integration system based on Bamboo picks up the merged pull request and starts a build and deploys a version with your changes automatically. You can see the build jobs on the public available Bamboo system.