Version History

Document Conventions

The following rules MUST be followed when using this document; these are taken from IETF RFC 2119 (simplified):

1. MUST: This word means that the definition is an absolute requirement of the specification.

2. MUST NOT: This phrase means that the definition is an absolute prohibition of the specification.

3. SHOULD: This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.

4. SHOULD NOT: This phrase means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

5. MAY: This word means that an item is truly optional. One user may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product, while another vendor may omit the same item.

Table of Contents

Overview

The following rules govern our branching policy, including naming and association with Jira issues. All working groups are assigned a short name and referred to as the key. The keys can be found on the projects page in jira: https://oagi.atlassian.net/jira/projects. The branch name must reference the project key and the issue number.

This document will provide three methods for creating and managing branches. We will demonstrate using the command line and Atlassian’s SourceTree: https://www.sourcetreeapp.com

Rules

• One MUST use one of the following formats for the branch name: <key>-<issue #>- or <key>/<issue #>-

• One MUST first create an issue in Jira before creating a branch. All GitHub branches MUST reference a Jira issue.

• Every Pull Request on GitHub MUST have two reviewers approve every merge.

• Branches MUST be deleted after they are merged. This keeps the active branches to a minimum and removes stale branches.

• Branches MAY reference any Jira issue except for EPICs.

• Before creating a pull request, master branch MUST be merged into working branch.

• Continuous Integration/Continuous Deployment (CI/CD) MUST succeed before branch can be merged.

Creating Branches

Branching from Jira

Jira allows you to create branches from issues. To do so, click on an issue from the default issue board and bring up the issue details.

Open

The details show a link to the right “Create branch” that uses the Jira GitHub integration to create a new branch on GitHub.

Open

The ”Create branch” link brings up this page that has a pre-formatted branch name. Note that the issue name starts with the following pattern: <key>-<issue #>-. You MUST use one of the following formats for the branch name: <key>-<issue #>- or <key>/<issue #>-. Jira will only accept the first form. The remaining text may be edited as desired.

In Jira the branch name must start with the pattern <key>-<issue #>-, otherwise you get the following error:

If you want to use the folder style of branch naming, you must use an external application.

The link from Jira will take you to the GitHub branch. You will need to select this branch in your local development environment to work on it. We will cover how to change branches using the command line and SourceTree from Atlassian.

The next section will explain how to do so using other applications.

Branching from external applications

Command line example

Source tree

Click the branch icon on the top menu bar:

Create a new branch using the folder style: <key>/<issue #>-. Paste the issue description into the text box, SourceTree will turn spaces into hyphens -.

The local branch is now organized into a folder, as can be seen on the left side. The folder format also works with other Git tools like Turtle, for example. It makes it easier for tool users to organize the various work from different working groups. GitHub will only display the full branch name and will not organize them into folders as the tools do.

Sharing the work on GitHub

The branch will be local until you push the branch to GitHub. When you are ready to share the edits to the ontology, push the changes to GitHub where others can pull the branch.

Pushing will share all the changes with the rest of the IOF and allow for collaborative development. In the next dialog box, select the branch using the left checkbox and click “OK”.

Pulling and Editing a Branch on GitHub

Command Line

SourceTree

Merging changes from others' work

Merging changes from GitHub master branch

Creating a Pull Request

CICD

Reviewers

Merging and deleting the branch