Repository Development

At this point in the tutorial, it is assumed that you have checked out a new branch that is up-to-date with either the develop or latest-os-hpxml branch of the ResStock repository. Note that a pull request review is required if your changes are intended to be merged into the develop branch of the ResStock repository.

ResStock’s develop branch generally points to the resstock [1] branch of OpenStudio-HPXML. A standing latest-os-hpxml branch in ResStock helps to ensure that ResStock stays up-to-date with OpenStudio-HPXML’s development. The latest-os-hpxml is periodically merged into develop using a “Latest OS-HPXML” pull request (here is an example).

[1]

Historically the develop branch of ResStock has pointed to the master branch of OpenStudio-HPXML; this is a temporary change until all applicable OpenStudio-HPXML features are merged into master.

There is a ResStock maintenance task for keeping latest-os-hpxml up-to-date – periodically merging its corresponding pull request (as well as creating a new one following the merge). Other ResStock tasks are developmental in nature and include, e.g.:

• TSV file updates from resstock-estimation

• technical documentation/reference updates

• tests and/or CI config updates

• core ResStock measure updates

• use/test new OpenStudio-HPXML features

The ResStock branch from which to implement changes, and guidelines for implementing those changes, depend on the task. In general, changes may be:

• unrelated to OpenStudio-HPXML

• related to the resstock branch of OpenStudio-HPXML

• related to some other branch of OpenStudio-HPXML

Branch from develop

Branch from develop for:

• TSV file updates from resstock-estimation

• technical documentation/reference updates

• tests and/or CI config updates

• core ResStock measure updates

These types of changes do not involve OpenStudio-HPXML, and so it is unnecessary to ensure files in the resources/hpxml-measures folder point to the OpenStudio-HPXML resstock branch.

Also branch from develop for creating a new latest-os-hpxml branch following the merge of an old one. For updating to the latest version of OpenStudio-HPXML’s resstock branch enter the following command:

$ openstudio tasks.rb update_resources

See Running Tasks Commands for more information and context about running tasks. (Executing the update_resources task will issue the appropriate git subtree command for syncing ResStock with OpenStudio-HPXML’s resstock branch; there is more on this below.)

Once resources/hpxml-measures has been updated, there are a few remaining steps for ensuring ResStock is properly connected to OpenStudio-HPXML.

If develop moves ahead of your branch, merge develop into your branch.

Branch from latest-os-hpxml

Branch from latest-os-hpxml for:

• using the resstock branch of OpenStudio-HPXML

• using some other branch of OpenStudio-HPXML

If you want to ensure you are using the latest resstock branch of OpenStudio-HPXML, branch from the latest-os-hpxml ResStock branch. This will allow you to use/test a new OpenStudio-HPXML feature or bugfix that was recently merged into its resstock branch.

For using an OpenStudio-HPXML feature or bugfix that has not yet been merged into resstock:

1. branch from your OpenStudio-HPXML feature branch and pull in the resstock branch, then

2. branch from the latest-os-hpxml ResStock branch and follow the instructions below.

ResStock contains a subtree to the OpenStudio-HPXML repository. The subtree is located at resources/hpxml-measures, and is basically a direct copy of all the folders and files contained in OpenStudio-HPXML for a particular commit. See this link or this link for more information about subtree and the git subtree command.

When using or testing a specific OpenStudio-HPXML branch, the subtree at resources/hpxml-measures can be updated using a set of simple commands. Files located at resources/hpxml-measures should typically never be directly edited or modified manually.

For pulling in and using/testing a specific OpenStudio-HPXML branch, enter the following command:

$ git subtree pull --prefix resources/hpxml-measures https://github.com/NREL/OpenStudio-HPXML.git <branch_name> --squash

where <branch_name> represents the OpenStudio-HPXML branch (from step 1 above) to be pulled in and tested. Note that the previous command essentially mirrors what update_resources calls but with a user-specified branch name.

Once resources/hpxml-measures has been updated, there are a few remaining steps for ensuring ResStock is properly connected to OpenStudio-HPXML.

If latest-os-hpxml moves ahead of your branch, merge latest-os-hpxml into your branch. Note that this can cause merge conflicts for files in the resources/hpxml-measures folder. The best practice is to instead keep the OpenStudio-HPXML branch up-to-date with resstock, and enter the git subtree command again to pull in the latest version of resources/hpxml-measures. Should a merge of latest-os-hpxml into your branch cause merge conflicts, choose the version of resources/hpxml-measures from the up-to-date OpenStudio-HPXML branch.

Steps after git subtree

After pulling a branch of OpenStudio-HPXML into ResStock, a few additional steps are involved:

1. Run openstudio tasks.rb update_measures.

   This applies rubocop auto-correct to measures, updates measure.xml files, and ensures arguments of the ResStockArguments measure reflect BuildResidentialHPXML.

   Although update_measures has the same name as OpenStudio-HPXML’s update_measures task, it is applied only to ResStock’s core measures.

2. Run the openstudio measures/ResStockArguments/tests/resstock_arguments_test.rb unit test.

3. Based on the results of the previous test, update resources/options_lookup.tsv with any new ResStockArguments arguments introduced by BuildResidentialHPXML.

4. Based on any workflow inputs/outputs changes, update CSV files in the resources/data/dictionary folder.

   This addresses any input/output data dictionary changes introduced by OpenStudio-HPXML workflow updates.