Tasks to release a new version of an existing model - EnergyInnovation/eps-us GitHub Wiki

A number of tasks are required when updating an existing model to a new version. The largest number of tasks are required to update the U.S. model to a new version, as other regions typically inherit certain files (such as the core model files, EPS.mdl and EPS.vpmx) from the U.S. version. Therefore, to be comprehensive, this checklist is based on an update of the U.S. model from one core version number to another, but a majority of these tasks will also be required to update non-U.S. regions.

Note that if you are creating the first-ever release of a new EPS region, you must also do the tasks listed in Tasks to release the first version of a new model.

Prerequisites

  1. All functional structure updates have been made in EPS.mdl
  2. All necessary input data updates have been made in InputData, and acronymn-key.xlsx has been updated accordingly
  3. All reference scenarios are complete in .cin files, with associated policy schedules in InputData/plcy-schd/FoPITY
  4. Scenario_BAU.cin contains the same settings that are specified in the input variables for any levers that are set to non-zero values in the BAU case and are exposed in the web interface (principally ctrl-settings/GDPGR and ctrl-settings/GRA)
  5. All necessary updates have been made to WebAppData.xlsx (e.g. for new or changed policy levers, graphs, targets, or reference scenario names)
  6. All necessary updates have been made to the Python scripts (most commonly, updating policy lists in CreateCombinationsScript.py and CreateContributionTestScript.py)

Tip: Check to ensure all updates from all branches are merged into the develop branch in your Git client.

Tasks in Vensim (only for core software development in U.S. national model)

  1. Update the version number in the comment in the upper left corner of the Structural Overview sheet
  2. Run a unit check (ctrl-U) and resolve any errors
  3. Push the "Simulate" button (not SyntheSim) and ensure there are no errors or warnings (except for Initial Value warnings, which are not a problem)
  4. Open the "Subscripts" pane and ensure all elements of all subscripts are enabled
  5. Select the variable Output Total CO2e Emissions on the Web Application Support Variables sheet
  6. Switch the active view to the Structural Overview sheet
  7. Choose File > Publish. Remove any files listed in the "Additional files" box. Uncheck the "Settings" box. Leave the .vgd file box checked. Click "Publish." Overwrite any existing EPS.vpmx file.

Tasks in Other Files in Model Package

  1. Update the version string in InputData/version.txt (this string typically contains only three numbers, which correspond to model structural changes, omitting any "data-only revision" fourth number)
  2. If any input variables were added or removed, update the file list in the CSV Export Tool.xlsm
  3. If present, remove the Cost Curve Generator.xlsx file, as we no longer include this file in model packages, and it does not use the updated methodology the web tool uses for box widths.

Tasks using EPS Builder and Staged Web App Review

  1. Ensure all changes from all steps above are reflected in the latest commit in the develop branch and pushed to GitHub
  2. Use EPS Builder to stage the latest commit in the develop branch
  3. Access the staging server for this region in a web browser and review it to make sure everything looks like it is working. If there is a problem, make the necessary corrections, then repeat all previous steps that were affected (including re-building the model using EPS Builder).

Tasks in Sourcetree (or other Git client)

  1. Ensure all changes from all steps above are reflected in the latest commit in the develop branch and pushed to GitHub
  2. Check out the main branch, then merge the develop branch into the main branch. Resolve any merge conflicts, usually in favor of the develop branch (i.e. "theirs")
  3. Tag the latest commit in the main branch with the version number and push the tag to GitHub. Most releases use three-part numbers, like 2.1.1 or 3.0.0. Data-only revisions (model releases that do not include any changes to EPS.mdl) increment a fourth number, starting at "1". For example, if the first release of a region's model is 2.1.1, after a data-only revision, the release number will be 2.1.1.1.

Tasks in GitHub (via web browser)

  1. In the correct repository, go to the Code tab, then click the Releases header in the right-hand column. You should see the tag you just created, listed above the most recent release.
  2. Click the "Draft a new release" button
  3. Enter the tag number in the "Tag version" field. GitHub should find the tag.
  4. Enter a title and description. The content of the description should be based on the version history details for this release, which (for the U.S. model) are located at docs/models/us.md in the eps-docs repo. Do not attach any binaries or other files. Click "Publish release."