Skip to content

Developer Documentation

Jump to bottom
Matt Steen edited this page Apr 1, 2025 · 3 revisions

Testing

Unit

Unit testing verifies the functioning in isolation of software elements that are separately testable.

This should be done for each Measure in the source repository, not in this repository.

Integration

Integration testing verifies the interactions among the software components.

See the test/integration/README.

Regression

Regression testing verifies that modifications have not caused unintended effects.

TODO

Releasing

Frequency

Windows Installers of the OpenStudio CLI For Revit are generally released in two cases.

  1. OpenStudio releases a new stable version, e.g. OpenStudio-vX.Y.0.
    • The installer's minor version should be incremented, e.g. x.2.z.
  2. Measure fixes and/or improvements.
    • The installer's patch version should be incremented, e.g. x.y.1.

Instructions

  1. Commit all changes for the new release, which is important for release notes since it will point to a specific commit.
  2. Draft a new release.
  3. Create a new tag according to above[^1].
  4. Attach the signed MSI file(s).
  5. Generate release notes.

[^1]: Tags can also be created via Git commands. https://git-scm.com/book/en/v2/Git-Basics-Tagging

Directories

  • gbxmls - example gbXML files, and complex models for regression testing
  • measures - existing and new measures used to translate and test gbXML to OSM translation
  • seeds - contains seed models used by one or more OSW workflows
  • weather - contains weather files used by OSW workflows
  • workflows - OSW workflow files that using the OpenStudio CLI run the gbXML to OSM translation workflow measures, forward translate OSM to IDF, and run EnergyPlus

Configure Development Environment

  1. Install the desired version of OpenStudio (Revit currently uses OpenStudio v3.8.0)
  2. Install the custom version of EnergyPlus corresponding to the OpenStudio version (currently EnergyPlus 22.1.0 For Revit)
    1. If the version of EnergyPlus hasn't been built yet, follow the instructions in the openstudio-revit-releases repo to build one
    2. Change the default install location so that it can be installed alongside the official release if necessary (e.g. C:\EnergyPlusV22-1-0-revit)
  3. Install Ruby v3.2.2 for Windows (devkit shouldn't be necessary)
    1. Open a command prompt in the gbxml-to-openstudio directory
    2. Run gem install bundler
    3. Run bundler install
  4. Install 7-Zip
  5. Install the latest Advanced Installer

Building Signed Installers

  1. Pull the latest code
  2. Update CHANGELOG.md to reflect changes included in the new release
  3. If a previous installer_staging directory exists move it to installer_stating.old
  4. Run rake build_installer, which copies files to the installer_staging directory (bundler install may be necessary as well if the gem dependencies have changed). Ensure that any untracked files in the following directories are removed prior to running.
    • measures
    • seeds
    • weather
    • workflows
  5. Zip the installer_staging directory using 7-Zip, and drag the resulting zip file to the code-signing-client.exe executable. 7-Zip is necessary because Windows is unable to compress files with unicode names
  6. Once installer_staging.signed.zip has finished downloading simply extract the contents back into the installer_staging directory, replacing the original files
  7. Diff the installer_staging.old and installer_staging directories
    1. If any files were added they must be manually dragged into the Advanced Installer file tree
    2. If any files were removed they must be manually deleted from the Advanced Installer file tree
  8. In Advanced Installer, with the Product Details tab active, increment the patch version (e.g. 1.1.5 -> 1.1.6) and hit Save
    1. When prompted to generate a new product code click Generate new, and save again
  9. In Advanced Installer, with the Product Details tab active, click Build in the ribbon
  10. Once the build has successfully completed, browse to the OpenStudio CLI For Revit 202X-SetupFiles/ directory, and drag the newly created msi to the code-signing-client.exe executable
  11. After the signed msi has been downloaded delete the original and remove the .signed suffix from the filename
  12. Upload the signed msi installer to the openstudio-cli-4r S3 bucket. Append the filename to https://openstudio-cli-4r.s3.amazonaws.com/ to download
  13. Delete the installer_staging.old directory if it was created
  14. Commit the *.aip and CHANGELOG.md file changes
  15. Create a git tag on the new commit matching the updated release version

Clone this wiki locally