Workflows

Development Workflow

1. Make a new feature branch using a name starting with develop-<name>. This name format is required for docker to validate the branch when commits are pushed.

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

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

4. 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.

• Merge master into develop branch using a normal merge.

• Update gldcore/version.h to new version being staged for release.

• 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, GitHub Workflow 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. Manually build docker image host%: cd docker && docker build . and tag the image slacgismo/gridlabd:latest.

5. Re-tag the latest slacgismo/gridlabd 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 with next tag name and update [Docker images]] page.

• Generate the new AWS image.

7. Create a new develop branch from master.

• 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. Verify Github workflow have passed all the checks.

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