Workflow

Git Workflow

This document describes the Campus Energy Modeling project Git workflow.

Branches

The Campus Energy Modeling project uses a simplified version of Drew Fradette's Git branching model (which is itself derived from Vincent Driessen’s model). There are three main code branches:

• dev Development
• rc Release candidates
• master Stable releases

Other branches, such as feature or bugfix branches, are considered supporting branches and should be deleted after merging into one of the three main branches. This workflow is similar to (but simpler than) the OpenStudio workflow.

As code matures, it progresses from dev to rc to master.

Development

The dev branch houses the main code development for the project. All active developers should checkout/pull from and commit/push to the dev branch.

Release Candidate

When development code is nearing readiness for release, a snapshot is merged from dev to rc. Bug fixes (but no new development) then continue on the rc branch until a release candidate is ready. Release candidates are tagged with a release candidate number matching the next version, for instance -v0.1-rc1 (see Tags). Beta testing should occur from tagged release candidates in the rc branches.

Master

The master branch is reserved for stable releases. Once a release candidate is tested and considered stable, it gets pushed to master and tagged with a release number, for instance -v0.1 (see Tags).

Supporting Branches

Development of major features should be done in supporting feature branches off of dev, by convention named feature-*. When features are ready, they may be merged back to dev and the corresponding branch deleted.

For bug fixes which require multiple commits, temporary bugfix branches, by convention named bugfix-*, may be used to house the intermediate code. If detected white vetting a release candidate, bug fixes should be merged back into the rc branch and then merged back to dev. If detected in a stable release, fixing the bug should trigger another release candidate before being merged into master. In either case, the supporting branch should be deleted afterwards.

Use of either of these branch types is optional for the Campus Modeling project.

Tags

The project uses version tags to track release candidates and stable releases. Versions are tagged X.Y.Z, with X, Y, and Z representing major, minor, and revision numbers, respectively. Per the Wikipedia article,

the major number is increased when there are significant jumps in functionality, the minor number is incremented when only minor features or significant fixes have been added, and the revision number is incremented when minor bugs are fixed.

See also Semantic Versioning.

Translating this system to Git tags produces the following conventions:

• -vX.0 tags a new major stable release
• -vX.Y tags a new minor stable release
• -vX.Y.Z tags a maintenance or bugfix release for version -vX.Y
• -vX.Y-rcN and -vX.Y.Z-rcN tag release candidate N for versions X.Y and X.Y.Z, respectively

If the branching workflow is followed properly, the final release candidate in rc for any version will exist and, apart from the change log and release notes, will be identical to the corresponding release in master.

Release Cycle

Releases should always begin as a release candidate and then move to a stable release following testing and bug fixes.

Instructions for creating a new release candidate or stable release:

1. Merge upstream code.

• Merge from dev to rc for release candidates.
• Merge from rc to master for stable releases.

2. Perform any required code cleanup.
3. Test the release:

• Run the automated tests.
• Manually run some demos.

4. Update the change log.
5. Create the release notes.
6. Tag the release.

Change Log

The change log summarizes significant changes to the project between releases. It need not document every change, but should mention major bug fixes; additions of models, demos, functions, etc.; and major changes in functionality.

The change log resides in Changes.md in the root directory of the project and uses markdown syntax. It has the following general format:

# Change Log

## Development
* Description of change 5
* Description of change 4

## v1.0-rc2
* Description of change 3

## v1.0-rc1
* Description of change 2

## v0.2
* Description of change 1

## v0.1
* Initial release

Which sections are included depend on the branch:

• The dev branch change log includes the Development section plus sections corresponding to prior stable releases (v0.1, v0.2, etc.)
• The rc branch change log includes sections corresponding to the current set of release candidates (for instance, v1.0-rc1 and v1.0-rc2) plus sections corresponding to prior stable releases
• The master branch change log includes only sections corresponding to stable releases

As changes are merged into release candidates and stable releases, move the corresponding change log entries to match. For a stable release, aggregate the changes recorded under all release candidates into a single list.

Release Notes

Release notes should be included with all tagged release candidates and stable releases. The release notes supplement the change log by highlighting major changes, new functionality, and other important information about the release. Release notes only need to be updated for major and minor releases (not revisions). ReleaseNotes.md should include only highlights for the current release; it does not maintain a list of past highlights as is done in the change log.

The file ReleaseNotes.md in the root directory of the project contains the release notes in markdown syntax. It has the following general format:

# Release Notes: vX.Y

Tag line/short description for release

## Highlight 1
Description of highlight 1

## Highlight 2
Description of highlight 2

Note that ReleaseNotes.md in the dev branch is only a template.

Third Party Developers

Third party developers may contribute code to the project using Git's Fork & Pull model:

1. Create a fork of the project.
2. Create a branch to house your contribution.
3. Develop your feature or bug fix in your new branch.
4. Initiate a pull request.

The Campus Energy Modeling team will consider your pull request. If it is approved, the team will then merge your contribution back into the main project.

This guide provides one possible Fork & Pull workflow.