Source Code Branching

Modified Git Flow

Our source code control use is inspired by the Git Flow pattern.

Specifically, we use the following naming conventions for the feature, release and hot fix branches. In addition, the versioning system we follow is Semantic Versioning 2.0.0.

PRs or how we approve code before merging

We use GitHub pull requests to solicit feedback and review of code. See below on branches for naming your branch. Once your work is ready for review, write up a pull request describing your work and any concerns. The description in the PR will also be re-purposed in our release notes.

  1. Create PR from your code branch

  2. Fill out the PR Description as described below, include the Jira ticket number in the title. This enables Jira to link the PR into the ticket.

  3. Solicit review from appropriate developers

  4. Encouraged to have a code review to share what you did and for feedback

  5. Once approved and we are not in the process of preparing a release, merge the code.

PR Description

  • Jira tickets, include description of feature or bug

  • Side Effects - any potential side effects?

  • Addresses issue found at site?

Branches

Branch names must contain DNS friendly characters as each DAS server branch can potentially be deployed as an EarthRanger site, and this is done from the branch name. That is why we can’t use periods or slashes in the branch name as would be standard for GitFlow.

Feature Branches

Feature branches are based on the current develop branch. For feature branches, include the JIRA ticket number. For example: ERA-1111. Once the feature work is completed, code is merged back into develop through a pull request on GitHub.

The version number in the develop branch should always reflect one higher version number than the one found in the current release branch.

Release Branches

When it is time to organize a release, branch from develop at the appropriate point. A release should be numbered as well. An example release branch name would be das-2-102-1 and for MT release-2.102.1.

The das server version number found in __init__.py includes the rc designation for builds: 1.15.1-rc.buildnum

buildnum - the buildnum is inserted by the CircleCI build process.

Hot Fix Branches

Hot fix branches are based from the affected release branch. Following the previous example, say a bug was identified and needed immediate fixing. We branch from das-2-102-1, then we follow the branch name format ERA-2222. The hotfix should be associated with a Jira ticket.

Once complete, the hotfix branch is merged into both the targeted release branch as well as the develop branch.

Hot fix operations:

  1. From the release branch das-2-102-1, create a hotfix branch named for the Jira Ticket ERA-2222

  2. Make the changes necessary to the ERA-2222 branch to address the bug. Hint: create a failing unittest where possible, then fix the bug.

  3. Create the PR and follow a high priority review process, involving QA

  4. Once approved, merge the fix into the release branch.

  5. Create a PR to merge the release branch into develop. See the PR reviewed and merged.

Main Branch

This has been deprecated, we may revisit this in future. Today we are using the release branch flow with no main branch.

Example workflow for a feature branch

git checkout develop
git pull  # or equivalent to be sure you have the latest code
git checkout -b ERA-1111

Make your code changes.

git add <files that changed>
git commit -m "informative comment on code changes"
git push origin ERA-1111

Once you have completed work, use the Github interface to start a Pull Request on your branch to get it merged into the develop branch.

Delete your feature branch once it has been approved and merged into develop - we do that at the end of the PR process.

Release Numbers

  • Major Change 1.x to 2.x - The API contract is broken. Massive changes to the codebase.

  • Minor Change 1.2 to 1.3 - New features, no major breaking changes.

  • Micro Change 1.2.1 to 1.2.2 - Bug fixes, very small features.