Workflows

Development Workflow

1. Fork this repository to your desired GitHub account.

2. Make a new feature branch from the develop branch on your forked repository.

3. Create a "Draft" pull request for the new feature branch to hipas/gridlabd develop. Assign the pull request to yourself, set the tags, and project.

4. When the work is complete and the pull request validation on CircleCI and Docker returns true, set the pull request to "Ready for Review" and assign a reviewer.

5. When the review is approved, merge the pull request to develop using a "Squash" merge.

Release Workflow

The release procedure of HiPAS GridLAB-D is as follows:

1. Stage develop branch in preparation for the merge into master (OUTDATED).

• Merge master into develop branch using a normal merge.

• Change the base image latest tag in .circleci/config.yml to the current tag number.

• List code changes (ie all PRs that are part of this release)

• List current unresolved issues, if any.

2. Validate the develop branch on local system, CircleCI and DockerHub.

• Build, install, and validate the develop branch on the local system.

• Build and validate the Docker image of the develop branch on the local system.

• All issues noted must be resolved before moving to Step 3.

3. Merge develop into master using a "Rebase" merge.

4. Ensure that DockerHub was able to build the image based on latest commit: slacgismo/gridlabd:latest

5. Pull the latest slacgismo/gridlabd image and tag it with the next release name and number on the Docker images page. If the changes are minor, the next image number should be used. The next image name should use if the changes are major. Major changes include:

• Removal of deprecated functionality.

• Changes in functionality that are not forward compatible from the previous release. "Compatibility" refers to whether the simulation runs with the same inputs, but not whether the simulation produces the same results.

6. Update the release images

• Push the image to DockerHub and update [Docker images]] page.

• Generate the new AWS image.

7. Create a new develop branch from master.

• Change the .circleci/config.yml to refer to the latest base image.

• Update the patch number in gldcore/version.h

• Create the pull request to stage the merge from develop to master.

• Merge the new develop update to all the working develop-* branches.

8. Merge the new master into the existing minor and major workflows

• Merge the updated minor and major branches into the respected minor-* and major-* branches.

9. Draft the tag/release with the update to master using the version number (e.g., X.Y.Z) and release name (e.g., Name-Z). Don't forget to copy the PR "Code" and "Documentation" change list into the release description.

Sandbox Workflow

1. By convention any branch that is not named master* or develop* is not considered part of the managed workflows for HiPAS GridLAB-D. Developers are recommended to name their private sandbox branches using the convention username/<branch-name>.

2. Team sandboxes can be named similarly by using a team, project, and other conceptual grouping, e.g., use-case/<scenario-name>.

3. A sandbox workflow may be turned into a development workflow by creating a new development branch from develop and "Squash" merging the sandbox branch into the new branch. After this is completed the sandbox branch is deleted and the Development Workflow is followed.

Types of Merges

There are three types of merges used in HiPAS Workflows. Use of the correct merge is vital to preserving the integrity of the commit history as desired by the development team.

1. Normal merge - This is used to merge master -> develop

• Keeps all commits history of the feature branch and move them into the master branch

• Adds an extra dummy commit to the master branch

2. Rebase merge - This is used to merge develop -> master

• Appends all commits history of the feature branch in the front of the master branch

3. Squash merge - This is used to merge develop-* to develop

• Groups all feature branch commits into one commit which it adds as a dummy commit to the front of the master branch