- Have CI added to any new SDK repo
- Write tests for new code functionality. Run the tests locally
- Make sure there is an issue created for items you are working on (for tracking purposes and so that the item appears in the changelog for the release). Use the following labels on the GitHub issue:
- Feature (features will appear as “New” item in the changelog)
- Enhancement (these will appear as “Improved” in the changelog)
- Bug (these will appear as “Fixed” in the changelog)
- Branch off of the
developbranch (unless it is a hotfix for production)
- When done, create pull requests against the
developbranch. You can group related issues together in the same PR).
- Make sure all tests are passing and run rubocop
- Assign a reviewer to look over the code
- Use the “DO NOT MERGE” label for Pull Requests that should not be merged
Functionality should be developed in the urbanopt-example-geojson-project repo. once it is ready and passing tests, the files from urbanopt-example-geojson-project will be copied over to the urbanopt-cli repo. Take care when performing the copy process as it is possible some changes were made directly on the cli repo (i.e., you might have to diff the files and reconcile both repos with the latest changes).
Notes for the copy process (from example-project repo to cli repo):
- Copy example_project/resources folder to example_files/resources
- Copy mappers folder over. Note: take the residential folder that is within the mappers folder and put it next to the mappers folder in the CLI repo
- Copy base_workflow.osw again and place it next to the mappers folder. Rename it as base_workflow_res.osw and place it NEXT TO the mappers folder (not inside).
- Open mappers/base_workflow.osw file in cli repo (you have previously copied it over in step 2) Remove the “BuildResidentialModel” measure section completely from this file and save.
- copy the measures folder to example_files/measures
- copy xml_building to example_files/xml_building
- copy osm_building to example_files/osm_building
- copy reopt to example_files/reopt. (on this one maybe diff the files to ensure that changes weren’t just made on the CLI repo)
- copy visualization to example_files/visualization
- There is no need to copy any of the scenario CSVs
If you make changes, ensure that all gems use the
openstudio-standard gem shipped with OpenStudio to avoid unforeseen consequences (do not include an openstudio-standard dependency in the gemfile).
Follow these steps to generate rdocs for now and existing SDK gems:
- Install NodeJS
- Go to the repository docs file, eg. urbanopt-scenario-gem/docs and type
npm install. Note: access to developerVPN will be needed for this step if within the NREL firewall.
- Move to the root level of the repo, eg. urbanopt-scenario-gem and enter these commands:
bundle exec rdoc --template-stylesheets ./docs/.vuepress/public/custom_rdoc_styles.css npm run build --prefix docs
- Finally, to deploy the docs, enter:
npm run deploy --prefix docs
Rdoc options are controlled with this config file.
When developing locally on URBANopt™ core gems and testing new functionality and dependencies via the CLI, it may be necessary to install local versions of core gems.
For local development, you will want to set the environment variable FAVOR_LOCAL_GEMS to 1. This enables local copies of gems in the Gemfile. Note that setting FAVOR_LOCAL_GEMS to 0 will not undo local gems functionality: you will have to either remove the FAVOR_LOCAL_GEMS environment variable, set it to nil or false (not 0), and open a new terminal window to turn it off.
There are 2 Gemfiles of interest:
When testing a new measure that will run in the OpenStudio workflow OSW file, enable the gem that contains the measure in the Gemfile of the project you are testing by uncommenting the appropriate block of code. You may have to modify the path or branch referenced to match what you are testing.
When testing new functionality in the URBANOPT workflow (a new scenario post-processor, for example), enable the gem in the Gemfile of the URBANopt-cli local directory by uncommenting the appropriate block of code. You may have to modify the path or branch referenced to match what you are testing.
Follow these steps when testing local gems via the CLI:
bundle install(to install the local gems that were just enabled in the Gemfile)
bundle exec rake install(to install the CLI in a place that has access to those local gems)
bundle exec uo ...(to execute the CLI calls)
- Develop new functionality in the example project directory.
- When the functionality is ready and all tests are passing, update the example project files in the urbanopt-cli repo.