DeveloperInformation.md

Developer Information

Setup

1. Install the latest version of OpenStudio. We recommend a minimum version of OpenStudio 3.2.1.

2. Install the Ruby version that corresponds to your OpenStudio install. See the OpenStudio SDK Version Compatibility Matrix.

   1. On Mac:
   2. Install Ruby 2.7.2 using rbenv (ruby -v from command prompt to check installed version).
   3. On Windows:
   4. Install Ruby+Devkit 2.7.2 (ruby -v from command prompt to check installed version).
   5. Using BTAP development Environment
   6. Do nothing.

3. Connect Ruby to OpenStudio:

   1. On Mac:
   2. Create a file called openstudio.rb
   3. Contents: require "/Applications/openstudio-3.2.1/Ruby/openstudio.rb". Modify 3.2.1 to the version you installed.
   4. Save it here: /usr/lib/ruby/site_ruby/openstudio.rb
   5. On Windows:
   6. Create a file called openstudio.rb
   7. Contents: require "C:/openstudio-3.2.1/Ruby/openstudio.rb". Modify 3.2.1 to the version you installed.
   8. Save it here: C:/Ruby27-x64/lib/ruby/site_ruby/openstudio.rb
   9. Start > right click Computer > Properties > Advanced system settings > Environment variables. In the User variables section (top) add a new Variable with the name GEM_PATH and the Value C:\Ruby27-x64\lib\ruby\gems\2.5.0.
   10. Using BTAP development Environment
   11. Do nothing.

4. Install the bundler ruby gem. (gem install bundler from command prompt)

5. Install Git.

6. Install GitHub desktop or another GUI that makes Git easier to use.

7. Clone the source code using GitHub desktop (easier) or Git (harder).

8. Run all commands below from the top level directory

9. On Windows, use the Git Bash instead of the default command prompt.

10. On Mac the default terminal is fine.

11. Using BTAP development Environment use the terminator terminal ideally.

12. Command prompt: bundle install. This will install all ruby gems necessary to develop this code.

13. That's it, you are ready to make changes!

Development Process

Summary

1. Modify the code
2. Test the code (new code plus old code to make sure you didn't break anything)
3. Document the code
4. Push branch to GitHub repository
5. Continuous automation runs tests
6. Pull request
7. Code review and merge

This project uses Rake to run tasks from the terminal.

bundle exec rake -T: List all available commands

• bundle exec rake build # Build openstudio-standards-X.X.XX.gem into the pkg directory
• bundle exec rake clean # Remove any temporary products
• bundle exec rake clobber # Remove any generated files
• bundle exec rake data:apicheck # Check Google Drive configuration
• bundle exec rake data:download # Download OpenStudio_Standards spreadsheets from Google Drive
• bundle exec rake data:update # Download OpenStudio_Standards from Google & export JSONs
• bundle exec rake data:update # Download OpenStudio_Standards spreadsheets and generate JSONs
• bundle exec rake data:update:manual # Generate JSONs from OpenStudio_Standards spreadsheets
• bundle exec rake data:export:jsons # Export JSONs from OpenStudio_Standards to data library
• bundle exec rake data:update:costing # Update RS-Means Database
• bundle exec rake doc # Generate the documentation
• bundle exec rake doc:show # Show the documentation in a web browser
• bundle exec rake install # Build and install openstudio-standards-X.X.XX.gem into system gems
• bundle exec rake install:local # Build and install openstudio-standards-X.X.XX.gem into system gems without network access
• bundle exec rake library:export # Export libraries for the OpenStudio Application
• bundle exec rake release[remote] # Create tag vX.X.XX and build and push openstudio-standards-X.X.XX.gem to Rubygems
• bundle exec rake rubocop # Check the code for style consistency
• bundle exec rake rubocop:auto_correct # Auto-correct RuboCop offenses
• bundle exec rake rubocop:show # Show the rubocop output in a web browser
• bundle exec rake test:btap_json_test # Run tests for btap_json_test
• bundle exec rake test:circ-90_1_general # Run tests for circ-90_1_general
• bundle exec rake test:circ-90_1_prm # Run tests for circ-90_1_prm
• bundle exec rake test:circ-all-tests # Run tests for circ-all-tests
• bundle exec rake test:circ-doe_prototype # Run tests for circ-doe_prototype
• bundle exec rake test:circ-necb # Run tests for circ-necb
• bundle exec rake test:circ-necb_bldg # Run tests for circ-necb_bldg
• bundle exec rake test:necb_local_bldgs_regression_tests # Run tests for necb_local_bld...`

Modify the code

As you add to/modify the code, please try to fit changes into the current structure rather than bolting things on willy-nilly. See the {file:docs/RepositoryStructure.md Repository Structure page} to see how the code is organized. If you don't understand something or want to discuss your plan before you get started, contact mailto:matthew.dahlhausen@nrel.gov.

1. Make a new branch for your changes.
2. Modify the code on your branch.
3. If you have data, modify the .json files and run commands to update the database, as appropriate. Historically, openstudio-standards data used a series of google spreadsheets, and is still used for non-90.1- standards. See OpenStudio_Standards Google Spreadsheet. Contact mailto:matthew.dahlhausen@nrel.gov for access.
4. You may edit the spreadsheet or modify a copy of the data, then download the spreadsheet to the data/standards directory, and run bundle exec rake data:update:manual to update the JSONs.
5. If you have edit access to the spreadsheets, you can use bundle exec rake data:update to download the latest version of the spreadsheet from Google Drive and export the JSON files.

Test the code

Tests prove that your code works as expected, but more importantly they help make sure that changes don't break other code. If your code doesn't have tests and someone else makes changes that break it, it's your own fault.

1. Create a new file called test_XX.rb in the /test/subdirectory directory.
2. Put tests into your file. See other test files for examples.
3. ruby test/sub_directory/test_XX.rb Run your new test file.
4. Fix your code and make sure your tests pass.

Document the code

Good documentation is critical. Changes or additions without good documentation will not be accepted. This library uses YARD to generate documentation. You simply write the documentation inline as specially tagged comments and the rest happens automagically. This YARD cheat sheet quickly shows you how to document things. You can also look at the other methods documented in the code.

1. Make sure your methods are documented.
2. bundle exec rake doc Generate the documentation and document any undocumented methods that are listed
3. bundle exec rake doc:show Inspect the documentation in a browser to make sure it looks right.

Push branch to GitHub

1. Commit your changes to your branch.
2. Merge /Master into your branch and resolve any conflicts.
3. Push your branch to GitHub.

Pull request

Once your code is done and the tests are passing locally on your branch with Master merged in, go to GitHub and create a Pull Request. This tells the main developers that you have changes to bring into the main code.

Code Review & Merge

The main developers will review your changes and either approve the pull request or give you some comments. If they approve the pull request, you are done and your changes are now part of the main code!

Look at the continuous integration results

1. When a commit is made to any branch, the continuous integration machine will run all the tests.
2. For pull requests, the status of the tests will automatically be posted to GitHub.
3. Developers will need to be given access to the continuous integration system to see detailed results.

Issues and New Features

1. Issues and feature requests are reported on the GitHub Repository Issues Page.
2. Issues should be labeled according to the OpenStudio Issue Prioritization Guide
3. Failing tests do not need to be listed as issues; they should be fixed if they fail.

Data

A database containing all the data used by openstudio-standards (and more) is being developed here